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.
As of today, there is just one contextualizer type, which is described below.
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. 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 available to it. By default, this authorizer type uses HTTP POST to send the rendered payload to the endpoint. You can however override this behavior by configuring method. Depending on the API requirements you might need to configure further properties, like headers, etc as well.
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)
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.
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-CookieLast updated on Dec 24, 2022