Unifiers

Unifiers finalize the successful execution of the pipeline and unify the available information about the Subject by transforming it into a format expected, respectively required by the upstream service. This ranges from adding a simple header to a structured JWT in a specific header.

Unifier Types

The following sections describe the available unifier 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. Those unifiers, which support creation of custom objects via templating, have access to at least the Subject objects in the template. Some can also make use of the Request object.

Noop

As the name implies, this unifier does nothing. As unifier are the last step in a rule pipeline and transform the available Subject information into a format required by the upstream service, the usage of this unifier makes only sense in combination with the Noop Authenticator, e.g. if your API should be publicly available. This authenticator type also doesn’t have any configuration options.

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

Example 1. Noop unifier configuration
id: foo
type: noop

Header

This unifier enables transformation of a Subject into HTTP headers.

To enable the usage of this unifier, 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 information (See also Templating). Can also be used to build headers from the processed request object.

Example 2. Header unifier configuration
id: foo
type: header
config:
  headers:
    X-User-ID: '{{ quote .Subject.ID }}'
    X-User-Email: '{{ quote .Subject.Attributes["email"] }}'

Cookie

This unifier enables transformation of a Subject into cookies.

To enable the usage of this unifier, 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). Can also be used to build cookies from the processed request object.

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

JWT

This unifier enables transformation of a Subject object into a token in a JWT format, which is 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 unifier, you have to set the type property to jwt. The usage of this unifier 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 unifier instance and the available information about the current subject.

Example 4. JWT unifier configuration
id: jwt_unifier
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 }}
    }

Last updated on Jun 7, 2023

Contextualizers
Error Handlers