Finalizers

Finalizers are the last steps executed in a rule pipeline and can e.g. create a special representation of the subject to be made available to the upstream service. This page describes the available finalizer types in detail.

Some finalizers 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 overridable and partially overridable to indicate whether the property can be overridden in a rule pipeline.

Noop

As the name implies, this finalizer does nothing. 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 and the Outputs objects 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 information (See also Templating).

In cases where multiple values are required for a single header name (e.g., impersonation groups in Kubernetes), the header finalizer will split newline-separated values into separate headers.

Example 2. Header finalizer configuration

id: foo
type: header
config:
  headers:
    X-User-ID: '{{ quote .Subject.ID }}'
    X-User-Email: '{{ index .Subject.Attributes "email" | quote }}'
    Host: '{{ .Request.Header "Host" | quote  }}'
    Impersonate-Group: |
      {{- range .Subject.Attributes.groups }}
      {{ . }}
      {{- end }}

Cookie

This finalizer enables transformation of a Subject and the Outputs objects 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 information (See also Templating).

Example 3. Cookie finalizer configuration

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

JWT

This finalizer enables transformation of the Subject and the Outputs objects into custom claims within a JWT. The resulting token is then made available to your upstream service in either the HTTP Authorization header (using the Bearer scheme) or in a custom header. Your upstream service can verify the JWT’s signature using heimdall’s JWKS endpoint to retrieve the necessary public keys/certificates.

To enable this finalizer, set the type property to jwt.

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

signer: Signer (mandatory, not overridable)
Defines the key material for signing the JWT, as well as the iss claim.
claims: string (optional, overridable)
A template specifying custom claims for the JWT. The template can use Values, Outputs, and Subject objects.
values: map of strings (optional, overridable)
A key-value map accessible as Values in the template engine for rendering claims. Values in this map can also be templated with access to Subject and Outputs.
ttl: Duration (optional, overridable)
Defines the JWT’s validity period. Defaults to 5 minutes. Heimdall automatically sets the iat and nbf claims to the current system time, and exp is calculated based on the ttl value.
header: object (optional, not overridable)
Specifies the HTTP header name and optional scheme for passing the JWT. Defaults to Authorization with scheme Bearer. If defined, name is required, and if scheme is omitted, the JWT is set as a raw value.

The generated JWT is cached until 5 seconds before expiration. The cache key is computed based on the finalizer’s configuration, the Subject, and the Outputs attributes.

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 }},
      "extra": {{ .Values | toJson }}
    }

In a rule that references the jwt_finalizer, additional claims can be dynamically inserted into the "extra" claim without redefining claims:

- id: some_rule
  # Other rule properties
  execute:
  - # Other mechanisms
  - finalizer: jwt_finalizer
    config:
      values:
        foo: bar
        user_id: '{{ .Subject.ID }}'
  - # Other mechanisms

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 information 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 Mar 3, 2025

Contextualizers Error Handlers