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 query parameter, 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.

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). Only Subject object is available in the template.

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). Only Subject object is available in the template.

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

JWT

This unifier enables transformation of a Subject into a bearer token in a JWT format, which is made available to your upstream service in the HTTP Authorization 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). Only Subject object is available in the template.

  • 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.

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
  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 Apr 17, 2023

Contextualizers
Error Handlers