Mutators

Mutators finalize the successful execution of the pipeline and transform the available information about the subject 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.

The following section describes the available mutator types in more detail.

Mutator Types

Noop

As the name implies, this mutator does nothing. As mutators are the last step in Heimdall’s pipeline and transform available subject information into an object required by the upstream service, the usage of this mutator makes only sense in combination with the Noop Authenticator for public APIs. This authenticator type also doesn’t have any configuration options.

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

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

Header

This mutator enables transformation of a subject into HTTP headers.

To enable the usage of this mutator, 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, not the Request* functions.

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

Cookie

This mutator enables transformation of a subject into cookies.

To enable the usage of this mutator, 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, not the Request* functions.

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

JWT

This mutator 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 mutator, you have to set the type property to jwt. The usage of this mutator type requires a configured Signer as well. At least it is highly recommended 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, not the Request* functions.

  • 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 mutator instance and the available information about the current subject.

Example 4. JWT mutator configuration
id: jwt_mut
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 }},
      {{ if $user_name -}}
        "name": {{ quote $user_name }}
      {{ else -}}
        "name": {{ quote $email }}
      {{ end -}}
    }

Last updated on Oct 21, 2022

Hydrators
Error Handlers