Contextualizers

Contextualizers allow you enriching the information about the request and the authenticated subject. This page describes the available contextualizer types in detail.

Some of the contextualizers 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.

Generic

This mechanism allows you to communicate to any API you want to fetch further information about the subject. A typical scenario is getting specific attributes for later authorization purposes which are not known to the authentication system and thus were not made available in Subject’s Attributes property.

If the API responds with a 2xx HTTP response code, the prepared response is made available through the Outputs object under the corresponding pipeline step ID. Its payload is exposed through the Payload property and response headers can be accessed using the Header(name) method.

If the Content-Type of the response either ends with json or is application/x-www-form-urlencoded, the payload is decoded; otherwise, it is treated as a string.

If the endpoint responds with a non-2xx HTTP response code, an error is thrown, and execution of the authentication & authorization pipeline stops.

To enable the usage of this contextualizer, you have to set the type property to generic.

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

  • endpoint: Endpoint (mandatory, not overridable)

    The API of the service providing additional attributes about the authenticated user. At least the url must be configured. This mechanism allows templating of the url and makes the Subject, the Outputs object, as well as the Values (see also below) object available to it. By default, this contextualizer will use HTTP POST to send the rendered payload to this endpoint. You can override this behavior by configuring method as well. Depending on the API requirements of the system, this contextualizer should communicate to, you might need to configure further properties, like headers, etc.

  • forward_headers: string array (optional, overridable)

    If the API requires any headers from the request to heimdall, you can forward these unchanged by making use of this property

  • forward_cookies: string array (optional, overridable)

    If the API requires any cookies from the request to heimdall, you can forward these unchanged by making use of this property.

  • payload: string (optional, overridable)

    Your template with definitions required to communicate to the endpoint. The template can make use of Values, Subject, the Outputs, and Request objects.

  • cache_ttl: Duration (optional, overridable)

    Allows caching of the API responses. Defaults to 10 seconds. The cache identity is derived from the contextualizer, the configured cache TTL and the effective request to the endpoint, including the HTTP method, rendered URL and headers, rendered payload and endpoint authentication strategy.

  • values map of strings (optional, overridable)

    A key value map, which is made accessible to the template rendering engine as Values object to render parts of the URL and/or the payload. The actual values in that map can be templated as well with access to the Subject, the Outputs, and Request objects.

Example 1. Contextualizer configuration without payload

In this example the contextualizer is configured to call an endpoint using the HTTP GET method with the subject id being part of the url path. As the endpoint requires the X-My-Session-Cookie cookie for subject authentication purposes, forward_cookies is used to achieve this.

id: foo
type: generic
config:
  endpoint:
    url: https://some-other.service/users/{{ .Subject.ID }}
    method: GET
  forward_cookies:
    - X-My-Session-Cookie
Example 2. Contextualizer configuration with payload

In this example the contextualizer is configured to call an endpoint using the HTTP POST and send some data.

id: foo
type: generic
config:
  endpoint:
    url: https://some-other.service/users
    method: POST
  payload: |
    {
      "user_id": {{ quote .Values.user_id }}
      "whatever": {{ quote .Outputs.whatever.Payload }}
    }

Since the values property is not defined but used in the payload, it must be specified in a rule making use of this contextualizer, e.g. in the following way:

- id: rule1
  # other rule properties
  execute:
  - # other mechanisms
  - contextualizer: foo
    config: # overriding with rule specifics
      values:
        user_id: "{{ .Subject.ID }}"
  - # other mechanisms

Map

This mechanism allows you to define (templated) variables which can be used in contextualizers/authorizers/finalizers afterwards to extract common logic out of Rulesets.

To enable the usage of this contextualizer, you have to set the type property to map.

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

  • items: map of strings (mandatory, not overridable)

    Every entry in the items map is rendered independently. The resulting key-value map is exposed as the Payload of this contextualizer’s entry in the Outputs object. For example, an item named foo produced by a pipeline step with the ID prepare is available as Outputs.prepare.Payload.foo.

  • values map of strings (optional, overridable)

    A key value map, which is made accessible to the template rendering engine as Values object to render parts of the URL and/or the payload. The actual values in that map can be templated as well with access to the Subject, the Outputs, and Request objects.

Example 3. Simple contextualizer configuration

In this example the contextualizer is configured to template a single variable named 'foo'.

id: foo
type: map
config:
  items:
    foo: "https://some-other.service/users/{{.Subject.ID}}"
Example 4. Contextualizer configuration with values

In this example the contextualizer is configured to template a single variable named foo, but contains a reference to local values.

id: foo
type: map
config:
  items:
    foo: "https://some-other.service/users/{{.Values.user_id}}"

Since the values property is not defined but used in items, it must be specified in a rule making use of this contextualizer, e.g. in the following way:

- id: rule1
  # other rule properties
  execute:
  - # some other steps
  - contextualizer: foo
    config: # overriding with rule specifics
      values:
        user_id: "{{ .Subject.ID }}"
  - # some further steps

Last updated on Aug 30, 2026

Authorizers Finalizers