Contextualizers

Contextualizers enrich the information about the Subject obtained via an authenticator mechanism with further information, required by either the endpoint of the upstream service itself or an authorizer mechanism. This can be handy if the actual authentication system doesn’t have all information about the subject (which is usually the case in microservice architectures), or if dynamic information about the subject, like the current location based on the IP address, is required.

Contextualizer Types

AThe following sections describe the available contextualizer 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.

Generic

This mechanism allows you to communicate to any API you want to fetch further information about the subject. 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 responses with a 2xx HTTP response code, the payload is made available in the Attributes property of the Subject, otherwise, if not overridden, an error is thrown and the execution of the regular pipeline stops. To avoid overwriting of existing attributes, this object is however not available on the top level, but under a key named by the id of the authorizer (See also the example below). If the Content-Type of the response is either ending with json or is application/x-www-form-urlencoded, the payload is decoded and made available as map, otherwise it is treated as string, but, as written above, is made available as well.

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 object, as well as the Values (see also below) objects 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 and Request objects.
cache_ttl: Duration (optional, overridable)
Allows caching of the API responses. Defaults to 10 seconds. The cache key is calculated from the entire configuration of the contextualizer instance and the available information about the current subject.
continue_pipeline_on_error: boolean (optional, overridable)
If set to true, allows the pipeline to continue with the execution of the next mechanisms. So the error, if thrown, is ignored. Defaults to false, which means the execution of the regular pipeline is stopped and the execution of the error pipeline is started.
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 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 .Values.whatever }}
    }

Since the values property is not defined but used in the payload, it must be specified in a rule making use of this contextualzer, 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 }}"
        whatever: "some value"
  - # other mechanisms

Last updated on Nov 20, 2023

Authorizers

Finalizers