Finalizers

Finalizers, as the name implies, finalize the execution of the pipeline and enrich the request with data such as subject information or authentication tokens required by the upstream service. The available options range from adding a simple header over a structured JWT in a specific header, to driving specific protocols, e.g. to obtain a token required by the upstream service.

Finalizer Types

The following sections describe the available finalizer types in more detail. Some of these may support or require additional configuration. The corresponding properties are annotated with mandatory, respectively optional to denote configuration requirement, as well as with overridable, not overriddable and partially overridable to indicate whether the property can be overridden in a rule pipeline.

Noop

As the name implies, this finalizer does nothing. As finalizer are the last step in a rule pipeline and act on the available Subject information, the usage of this finalizer makes only sense in combination with the Noop Authenticator, e.g. if your API should be publicly available. This finalizer type also doesn’t have any configuration options.

To enable the usage of this finalizer, you have to set the type property to noop.

Example 1. Noop finalizer configuration

id: foo
type: noop

Header

This finalizer enables transformation of a Subject into HTTP headers. It can also be used to map information from the original Request into headers expected by the upstream service.

To enable the usage of this finalizer, you have to set the type property to header.

Configuration using the config property is mandatory. Following properties are available:

headers: string map (mandatory, overridable)
Enables configuration of arbitrary headers with any values build from available subject and request information (See also Templating).

Example 2. Header finalizer configuration

id: foo
type: header
config:
  headers:
    X-User-ID: '{{ quote .Subject.ID }}'
    X-User-Email: '{{ quote .Subject.Attributes["email"] }}'
    Host: '{{ quote .Request.Header("Host") }}'

Cookie

This finalizer enables transformation of a Subject into cookies. It can also be used to map information from the original Request into cookies expected by the upstream service.

To enable the usage of this finalizer, you have to set the type property to cookie.

Configuration using the config property is mandatory. Following properties are available:

cookies: string map (mandatory, overridable)
Enables configuration of arbitrary cookies with any values build from available subject information (See also Templating).

Example 3. Cookie finalizer configuration

id: foo
type: cookies
config:
  cookies:
    user_id_cookie: '{{ quote .Subject.ID }}'
    user_email_cookie: '{{ quote .Subject.Attributes["email"] }}'

JWT

This finalizer enables transformation of the Subject object into a token in a JWT format, which is then made available to your upstream service in either the HTTP Authorization header with Bearer scheme set, or in a custom header. In addition to setting the JWT specific claims, it allows setting custom claims as well. Your upstream service can then verify the signature of the JWT by making use of heimdall’s JWKS endpoint to retrieve the required public keys/certificates from.

To enable the usage of this finalizer, you have to set the type property to jwt.

The usage of this finalizer type requires a configured Signer as well. At least it is a must in production environments.

Configuration using the config property is optional. Following properties are available:

claims: string (optional, overridable)
Your template with custom claims, you would like to add to the JWT (See also Templating).
ttl: Duration (optional, overridable)
Defines how long the JWT should be valid. Defaults to 5 minutes. Heimdall sets the iat and the nbf claims to the current system time. The value of the exp claim is then influenced by the ttl property.
header: object (optional, not overridable)
Defines the name and scheme to be used for the header. Defaults to Authorization with scheme Bearer. If defined, the name property must be set. If scheme is not defined, no scheme will be prepended to the resulting JWT.

The generated JWT is always cached until 5 seconds before its expiration. The cache key is calculated from the entire configuration of the finalizer instance and the available information about the current subject.

Example 4. JWT finalizer configuration

id: jwt_finalizer
type: jwt
config:
  ttl: 5m
  header:
    name: X-Token
  claims: |
    {
      {{ $user_name := .Subject.Attributes.identity.user_name -}}
      "email": {{ quote .Subject.Attributes.identity.email }},
      "email_verified": {{ .Subject.Attributes.identity.email_verified }},
      "name": {{ if $user_name }}{{ quote $user_name }}{{ else }}{{ quote $email }}{{ end }}
    }

OAuth2 Client Credentials

This finalizer drives the OAuth2 Client Credentials Grant flow to obtain a token, which should be used for communication with the upstream service. By default, as long as not otherwise configured (see the options below), the obtained token is made available to your upstream service in the HTTP Authorization header with Bearer scheme set. Unlike the other finalizers, it does not have access to any objects created by the rule execution pipeline.

To enable the usage of this finalizer, you have to set the type property to oauth2_client_credentials.

Configuration using the config property is mandatory. Following properties are available:

token_url: string (mandatory, not overridable)
The token endpoint of the authorization server.
client_id: string (mandatory, not overridable)
The client identifier for heimdall.
client_secret: string (mandatory, not overridable)
The client secret for heimdall.
auth_method: string (optional, not overridable)
The authentication method to be used according to RFC 6749, Client Password. Can be one of
- basic_auth (default if auth_method is not set): With that authentication method, the "application/x-www-form-urlencoded" encoded values of client_id and client_secret are sent to the authorization server via the Authorization header using the Basic scheme.
- request_body: With that authentication method the client_id and client_secret are sent in the request body together with the other parameters (e.g. scopes) defined by the flow.
  Usage of request_body authentication method is not recommended and should be avoided.
scopes: string array (optional, overridable)
The scopes required for the access token.
cache_ttl: Duration (optional, overridable)
How long to cache the token received from the token endpoint. Defaults to the token expiration information from the token endpoint (the value of the expires_in field) if present. If the token expiration inforation is not present and cache_ttl is not configured, the received token is not cached. If the token expiration information is present in the response and cache_ttl is configured the shorter value is taken. If caching is enabled, the token is cached until 5 seconds before its expiration. To disable caching, set it to 0s. The cache key calculation is based on the entire oauth2_client_credentials configuration without considering the header property.
header: object (optional, overridable)
Defines the name and scheme to be used for the header. Defaults to Authorization with scheme Bearer. If defined, the name property must be set. If scheme is not defined, no scheme will be prepended to the resulting JWT.

Example 5. OAuth2 Client Credentials finalizer configuration

id: get_token
type: oauth2_client_credentials
config:
  cache_ttl: 5m
  header:
    name: X-Token
    scheme: MyScheme
  token_url: https://my-oauth-provider.com/token
  client_id: my_client
  client_secret: VerySecret!
  auth_method: basic_auth
  scopes:
    - foo
    - bar

Last updated on Oct 13, 2023

Contextualizers

Error Handlers