Type Definitions

Assertions

This type enables configuration of required token and claim assertions. Depending on the object type (JWT or introspection response), the assertions apply to different parts of such objects.

  • scopes: Scopes Matcher (optional)

    Required scopes given to the client.

  • audience: string array (optional)

    Values to be matched in the aud claim. This assertion evaluates to true if at least one entry in the given audience array is present in the aud claim. Both cases, either as whitespace separated string, or a JSON array are considered.

  • issuers: string array (optional)

    Issuers to trust.

  • allowed_algorithms: string array (optional)

    Algorithms, which are trusted (according to RFC 7518). Defaults to the following list: ES256, ES384, ES512, PS384, PS512.

    If DPoP validation is enabled using proof_of_possession (see below), these algorithms are also used to validate DPoP proof JWT signatures.

  • validity_leeway Duration (optional)

    The time leeway to consider while verifying the iat, exp and the nbf. Defaults to 10 seconds.

    If DPoP validation is enabled using proof_of_possession (see below), this leeway is also considered while validating the iat claim of the DPoP proof JWT.

  • proof_of_possession: Proof of Possession Assertion (optional)

    Configures proof-of-possession validation for access tokens. If configured, heimdall enforces the configured proof-of-possession assertion. Otherwise, proof-of-possession validation is performed opportunistically. That means, if e.g., an access token is recognized as DPoP-bound, heimdall tries to satisfy the DPoP requirements according to RFC 9449.

Example 1. Assertions configuration
issuers:
 - foo
 - bar
audience:
 - zap
scopes:
 - baz
allowed_algorithms:
 - ES512
validity_leeway: 5s
proof_of_possession:
  type: dpop
  config:
    max_age: 1m
    nonce_required: false
    replay_allowed: false

Here we say, the token must have been issued either by the issuer foo, or the issuer bar, the aud claim must contain zap, the scope claim (either scp or scope) must be present and contain the scope baz, if the token is signed, it must have been signed by using the ES512 algorithm (ECDSA using P-521 and SHA-512), and if the information about token validity is present, we respect a deviation of 5 seconds.

In addition, the access token must satisfy the configured proof-of-possession assertion. In the example above, heimdall validates DPoP-bound access tokens according to RFC 9449. The DPoP proof must be bound to the presented access token, the current HTTP method and URI, and must satisfy the configured freshness and replay protection settings.

Authentication Data Source

An authentication data source is actually a list of possible strategies for principal authentication data retrieval. The entries following the first one are fallbacks and are only executed if the previous strategy could not retrieve the required authentication data from the request.

This fallback mechanism can become handy, if different clients of your application send the authentication data using different methods. RFC 6750 describes for example how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. This RFC says, a token can either be sent in the Authorization header, or in a query parameter, or even as part of the HTTP body. So you can define the following list to let Heimdall try to extract the access token from all three places:

- header: Authorization
  scheme: Bearer
- query_parameter: access_token
- body_parameter: access_token

The available strategies are described in the following sections.

Cookie Strategy

This strategy can retrieve authentication data from a specific HTTP cookie. Following properties are supported:

  • cookie: string (mandatory)

    The name of the cookie to use.

Example 2. Cookie Strategy usage

Imagine you want Heimdall to verify an authentication session, which is represented by a specific cookie before the request hits your upstream service. If the client of your upstream application, which is case of a cookie would usually be a browser sends a cookie named "session", you can inform Heimdall to extract and use it by configuring this strategy as follows:

- cookie: my_session_cookie

Header Strategy

This strategy can retrieve authentication data from a specific HTTP header. Following properties are supported:

  • header: string (mandatory)

    The name of the header to use.

  • scheme: string (optional)

    Scheme, which should be present in the header value. If specified, but not present in the header value, the authentication data cannot be retrieved, effectively making the affected authenticator feel not responsible for the request.

Example 3. Header Strategy usage

Imagine you want Heimdall to verify an access token used to protect your upstream service. If the client of your upstream application sends the access token in the HTTP Authorization header, you can inform Heimdall to extract it from there by configuring this strategy as follows:

- header: Authorization
  scheme: Bearer

Query Parameter Strategy

  • query_parameter: string (mandatory)

    The name of the query parameter to use.

Example 4. Query Parameter Strategy usage

Imagine you want Heimdall to verify an access token used to protect your upstream service. If the client of your upstream application sends the access token in the query parameter named "access_token", you can inform Heimdall to extract it from there by configuring this strategy as follows:

- query_parameter: access_token

Body Parameter Strategy

The usage of this strategy is only possible when the request payload is either JSON or application/x-www-form-urlencoded encoded. The Content-Type of the request must also either be set to application/x-www-form-urlencoded or to a MIME type, which contains json.

  • body_parameter: string (mandatory)

    The name of the body parameter to use.

Example 5. Body Parameter Strategy usage

Imagine you want Heimdall to verify an access token used to protect your upstream service. If the client of your upstream application sends the access token in the body parameter named "access_token", you can inform Heimdall to extract it from there by configuring this strategy as follows:

- body_parameter: access_token

Authentication Data Forward Strategy

Authentication data strategy defines the way how heimdall should forward the authentication data extracted from the request to the used identity management system.

An Authentication Data Forward Strategy configuration entry must contain the following two properties:

  • type - The type of the strategy. Available types are described in the following sections.

  • config - The strategy specific configuration.

Body Forward Strategy

This strategy can be used to embed the extracted authentication data into a body parameter of the request to the identity management system.

type must be set to body. config supports the following properties:

  • name: string (mandatory)

    The name of the property for the authentication data.

Example 6. Body strategy configuration

The following snippet shows how to configure this strategy to send e.g. a token in a property named "idToken".

type: body
config:
  name: idToken

Depending on the configured "Content-Type" header for the request (see Endpoint headers) the result might look like

idToken=<whatever the token value is>

if the "Content-Type" header was set to application/x-www-form-urlencoded, or

{ "idToken": "<whatever the token value is>" }

otherwise

Cookie Forward Strategy

This strategy can be used to embed the extracted authentication data into a cookie of the request to the identity management system.

type must be set to cookie. config supports the following properties:

  • name: string (mandatory)

    The name of the cookie for the authentication data.

Example 7. Cookie strategy configuration

The following snippet shows how to configure this strategy to send e.g. a token in a cookie named "it_token".

type: cookie
config:
  name: it_token

Header Forward Strategy

This strategy can be used to embed the extracted authentication data into a header of the request to the identity management system.

type must be set to header. config supports the following properties:

  • name: string (mandatory)

    The name of the header for the authentication data.

  • scheme: string (optional)

    The scheme for the header added in front of the authentication data value.

Example 8. Header strategy configuration

The following snippet shows how to configure this strategy to send e.g. a token in a header named "X-ID-Token" with scheme "Bearer".

type: header
config:
  name: X-ID-Token
  scheme: Bearer

Query Forward Strategy

This strategy can be used to embed the extracted authentication data into a query parameter of the request to the identity management system.

Using this strategy is discouraged, as it will expose the authentication data to access logs, metrics and tracing.

type must be set to query. config supports the following properties:

  • name: string (mandatory)

    The name of the query parameter for the authentication data.

Example 9. Query strategy configuration

The following snippet shows how to configure this strategy to send e.g. a token in a query named "token".

type: query
config:
  name: token

Authentication Strategy

Authentication strategy is kind of abstract type, so you have to define which specific type to use. Each type has its own configuration options.

An AuthStrategy configuration entry must contain the following two properties:

  • type - The type of the strategy.

  • config - The strategy specific configuration.

Available strategies are described in the following sections.

API Key Strategy

This strategy can be used if your endpoint expects a specific api key be sent in a header, a cookie or query.

type must be set to api_key. config supports the following properties:

  • in: string (mandatory)

    Where to put the api key. Can be either header, cookie, or query.

    Using query strategy will expose the api key to access logs and tracing.

  • name: string (mandatory)

    The name of either the header or the cookie.

  • secret: Secret Reference (mandatory)

    Reference to the api key. The selector must reference a single string value.

Example 10. API Key Strategy configuration

The following snippet shows how to configure this strategy to send an api key in the X-My-API-Key HTTP header.

type: api_key
config:
  in: header
  name: X-My-API-Key
  secret:
    source: my_secrets
    selector: my_api_key

Basic Auth Strategy

This strategy can be used if your endpoint is protected by HTTP basic authentication and expects the HTTP Authorization header with required values.

type must be set to basic_auth. config supports the following properties:

  • credentials: Secret Reference (mandatory)

    Credentials to use for authentication purposes. The credentials object must include a user_id and a password entries:

    # contents of a credentials object
user_id: Aladdin
password: SesameOpen!
Example 11. Basic Auth Strategy configuration
type: basic_auth
config:
  credentials:
    source: my_secrets
    selector: creds

HTTP Message Signatures

This strategy implements HTTP message signatures according to RFC 9421 to sign outbound requests.

type must be set to http_message_signatures. config supports the following properties:

  • ttl: Duration (optional)

    The TTL of the resulting signature. Defaults to 1m. Responsible for setting created and expires parameters in the resulting signature.

  • label: string (optional)

    The label to use. Defaults to sig.

  • components: string array (mandatory)

    The components to be covered by the signature. While the RFC allows for signatures that do not cover any components, this is considered a security risk. When using the "content-digest" component, Heimdall will compute hash values of the request body using sha-256 and sha-512 algorithms. It will then add a Content-Digest header with these hash values to the request, and this header will be included in the signature calculation.

  • signer: Signer (mandatory)

    The configuration of the key material used for signature creation purposes, as well as the name used for the tag parameter in the resulting signature.

Example 12. Strategy configuration
type: http_message_signatures
config:
  ttl: 2m
  label: foo
  components: ["@method", "content-digest", "@authority", "x-my-fancy-header"]
  signer:
    name: bar
    secret:
      source: my_keys_source

OAuth2 Client Credentials Grant Flow Strategy

This strategy implements the OAuth2 Client Credentials Grant Flow to obtain an access token expected by the endpoint. Heimdall caches the received access token.

type must be set to oauth2_client_credentials. config supports the following properties:

  • token_url: string (mandatory)

    The token endpoint of the authorization server.

    Usage of TLS is enforced as long as heimdall is not started with --insecure-skip-egress-tls-enforcement flag, which allows insecure communication to any of the configured services.

  • credentials: Secret Reference (mandatory, not overridable)

    Reference to client credentials to be used for authentication purposes. The credentials object must include a client_id and a client_secret entries:

    # contents of a credentials object
client_id: Aladdin
client_secret: SesameOpen!

  • auth_method: string (optional)

    The authentication method to be used according to RFC 6749, Client Password. Can be one of

    • basic_auth (default if auth_method is not set): With that authentication method, the "application/x-www-form-urlencoded" encoded values of client_id and client_secret are sent to the authorization server via the Authorization header using the Basic scheme.

    • request_body: With that authentication method the client_id and client_secret are sent in the request body together with the other parameters (e.g. scopes) defined by the flow.

      Usage of request_body authentication method is not recommended and should be avoided.

  • scopes: string array (optional)

    The scopes required for the access token.

  • cache_ttl: Duration (optional)

    How long to cache the token received from the token endpoint. Defaults to the token expiration information from the token endpoint (the value of the expires_in field) if present. If the token expiration information is not present and cache_ttl is not configured, the received token is not cached. If the token expiration information is present in the response and cache_ttl is configured the shorter value is taken. If caching is enabled, the token is cached until 5 seconds before its expiration. To disable caching, set it to 0s. The cache key calculation is based on the values of token_url, client_id, client_secret and the scopes properties.

  • header: object (optional, overridable)

    Defines the name and scheme to be used for the header. Defaults to Authorization with scheme Bearer. If defined, the name property must be set. If scheme is not defined, no scheme will be prepended to the resulting JWT.

Example 13. Strategy configuration
type: oauth2_client_credentials
config:
  header:
    name: X-My-Token
  token_url: https://my-auth.provider/token
  credentials:
    source: my_secrets
    selector: my_client_creds
  auth_method: basic_auth
  ttl: 10m
  scopes:
    - baz
    - zap

Authorization Expression

Authorization expressions define, as the name implies expressions for authorization purposes and have the following properties:

  • expression string (mandatory)

    The expression to execute.

  • message string (optional)

    The message to include into the error if the expression fails.

Example 14. Example expression using CEL

The expression below determine whether attributes property of a subject object (also shown below) has at least one key that starts with the group prefix, and ensure that all group-like keys have list values containing only strings that end with @acme.co.

subject
id: "foobar"
attributes:
  group1: ["admin@acme.co", "analyst@acme.co"]
  labels: ["metadata", "prod", "pii"]
  groupN: ["forever@acme.co"]
expression: |
  subject.attributes.exists(c, c.startsWith('group')) &&
  subject.attributes
      .filter(c, c.startsWith('group'))
      .all(c, subject.attributes[c]
      .all(g, g.endsWith('@acme.co')))
message: No groups ending with @acme.co present

ByteSize

ByteSize is actually a string type, which adheres to the following pattern: ^[0-9]+(B|KB|MB)$

So with 10B you can define the byte size of 10 bytes and with 2MB you can say 2 megabytes.

CORS

This functionality is only supported if heimdall is operated in proxy mode. In decision operation mode, this configuration is ignored.

CORS (Cross-Origin Resource Sharing) headers can be added and configured by making use of this type. This functionality allows for advanced security features to quickly be set. If CORS headers are set, then heimdall does not pass preflight requests to its decision pipeline, instead the response will be generated and sent back to the client directly. Following properties are supported:

  • allowed_origins: string array (optional)

    List of origins that may access the resource. Defaults to all, if not set, but any of the other CORS options are configured.

  • allowed_methods: string array (optional)

    List of methods allowed when accessing the resource. This is used in response to a preflight request. Defaults to GET, POST, HEAD, PUT, DELETE and PATCH if not set, but any of the other CORS options are configured.

  • allowed_headers: string array (optional)

    List of request headers that can be used when making the actual request.

  • exposed_headers: string array (optional)

    "Allow-List" of headers that clients are allowed to access.

  • allow_credentials: boolean (optional)

    Indicates whether the response to the request can be exposed when the credentials flag is true. When used as part of a response to a preflight request, this indicates whether the actual request can be made using credentials. Defaults to false if not set, but any of the other CORS options are configured.

  • max_age: Duration (optional)

    Indicates how long the results of a preflight request can be cached. Defaults to 0 seconds if not set, but any of the other CORS options are configured.

Example 15. Possible configuration
allowed_origins:
  - example.org
allowed_methods:
  - HEAD
  - PATCH
allow_credentials: true
max_age: 10s

Duration

Duration is actually a string type, which adheres to the following pattern: ^[0-9]+(ns|us|ms|s|m|h)$

So with 10s you can define the duration of 10 seconds and with 2h you can say 2 hours.

Endpoint

The Endpoint type defines the properties required for communication with an endpoint.

If only the URL needs to be set, you can specify it as a string. If additional properties are required, the following options are available:

  • url string (mandatory)

    The URL of the endpoint. Depending on the mechanism, the URL can be templated.

    • If templating is used, the user info, scheme, and host parts of the URL cannot be templated. Attempts to do so will result in runtime errors.

    • TLS is enforced unless heimdall is started with the --insecure-skip-egress-tls-enforcement flag, which allows insecure communication with any configured service.

  • method string (optional)

    The HTTP method to use while communicating with the endpoint. If not set POST is used.

  • retry Retry (optional)

    What to do if the communication fails. If not configured, no retry attempts are done.

  • auth Authentication Strategy (optional)

    Authentication strategy to apply, if the endpoint requires authentication.

  • headers map of strings (optional)

    HTTP headers to be sent to the endpoint.

    These headers are not analyzed by heimdall and are just forwarded to the endpoint. E.g. if you configure the Content-Encoding to something like gzip, the service behind the used endpoint might fail to answer, as it would expect the body to be compressed.

  • http_cache HTTP Cache (optional)

    Controls whether HTTP caching according to RFC 7234 should be used.

Example 16. Endpoint configuration as string
https://foo.bar
Example 17. Structured Endpoint configuration
url: https://foo.bar
method: GET
retry:
  give_up_after: 5s
  max_delay: 1s
auth:
  type: api_key
  config:
    name: foo
    in: cookie
    secret:
      source: my_secrets
      selector: my_api_key
headers:
  X-My-First-Header: foobar
  X-My-Second-Header: barfoo
http_cache:
  enabled: true

Error/State Type

Heimdall defines a couple of error/state types, which it uses to signal errors. Those, which are marked with (*) are available in CEL expressions. All can be used to define overrides for the HTTP response codes.

Following types are available:

  • accepted - this is the only state type in this list and is used to signal, the matched decision pipeline has been executed successfully, so the request can be forwarded to the upstream service. The response of that type results by default in a 200 OK response.

  • authentication_error (*) - used if an authenticator failed to verify authentication data available in the request. E.g. an authenticator was configured to verify a JWT and the signature of it was invalid. If none of the authenticators used in a pipeline were able to authenticate the user, and the default error handler was used to handle such error, it will by default result in a 401 Unauthorized response.

  • authorization_error (*) - used if an authorizer failed to authorize the principal. E.g. an authorizer is configured to use an expression on the given principal and request context, but that expression returned with an error. Error of this type results by default in 403 Forbidden response if the default error handler was used to handle such error.

  • communication_error (*) - this error is used to signal a communication error while communicating to a remote system during the execution of the pipeline of the matched rule. Timeouts of DNSs errors result in such an error. Error of this type results by default in 502 Bad Gateway HTTP code if handled by the default error handler.

  • internal_error - used if heimdall run into an internal error condition while processing the request. E.g. something went wrong while unmarshalling a JSON object, or if there was a configuration error, which couldn’t be raised while loading a rule, etc. Results by default in 500 Internal Server Error response to the caller.

  • no_rule_error - this error is used to signal, there is no matching rule to handle the given request. Error of this type results by default in 404 Not Found HTTP code.

  • precondition_error (*) - used if the request does not contain required/expected data. E.g. if an authenticator could not find a cookie configured. Error of this type results by default in 400 Bad Request HTTP code if handled by the default error handler.

HTTP Cache

Controls whether HTTP caching according to RFC 7234 should be used. Following properties are defined:

  • enabled boolean (optional)

    Defaults to false if not otherwise stated in the description of the configuration type, making use of the HTTP Cache settings. When set to true, heimdall will strictly comply with the HTTP caching rules defined in RFC 7234, caching responses only when allowed and reusing them only if they remain valid per the standard.

  • cache_ttl Duration (optional)

    Specifies how long heimdall should cache the response if it does not contain any explicit expiration time (no heuristic freshness lifetime is calculated). If this property is not set, heimdall considers such responses uncacheable. Unless specified otherwise in the configuration type description utilizing the HTTP Cache settings, the default value is 0s.

Principal

This configuration type enables extraction of principal information from responses received by heimdall from authentication services. Following properties are available.

  • id: string (mandatory)

    A GJSON Path pointing to the id of the principal in the JSON object.

  • attributes: string or map (optional)

    If this property is defined as a single string, it must be a GJSON Path pointing to the attributes of the principal in the JSON object. Defaults to @this. Otherwise, if it defined as a key-value map, the values of that map must be GJSON Path expressions.

Example 18. Extracting principal id from an OAuth2 Introspection endpoint response.

This example shows how to extract the principal id from an OAuth2 Introspection endpoint response and set the principal attributes to the entire response

id: sub
attributes: "@this"

Setting attributes was actually not required, as @this would be set by default anyway.

Example 19. Extracting principal from an Ory Kratos "whoami" endpoint response

In this example the id is set to the value of the identity.id property from the response. Additionally, some of the present attributes are mapped to particular names.

id: identity.id
attributes:
  email: identity.traits.email
  username: identity.traits.user

Proof of Possession Assertion

Proof of possession is a kind of abstract assertion type, so you have to define which specific type to use. Each type has its own configuration options.

A Proof of Possession assertion configuration entry must contain the following properties:

  • type - The mandatory type of the proof of possession assertion.

  • config - The optional type-specific configuration.

Available proof of possession assertion types are described in the following sections.

DPoP Assertion

This assertion validates DPoP-bound access tokens according to RFC 9449.

When configured, heimdall validates the DPoP proof JWT against the presented access token and the current request. This includes validation of the proof signature, the access token binding, the HTTP method and URI binding, proof freshness, and replay protection.

type must be set to dpop. config is optional and supports the following properties:

  • max_age: Duration (optional)

    The maximum allowed age of a DPoP proof based on its iat claim. Defaults to 1m.

    If nonce validation is enabled, this value is also used as the maximum allowed age of a nonce.

  • nonce_required: boolean (optional)

    Whether the DPoP proof must contain a nonce previously requested by heimdall. Defaults to false.

    If set to true, heimdall requires a master key to generate and validate DPoP nonces. If DPoP nonce validation is enabled and the master key is not configured, heimdall refuses to start or rejects rules which apply the configuration at rule level.

  • replay_allowed: boolean (optional)

    Whether replay of DPoP proofs is allowed. Defaults to false.

    If set to false, heimdall rejects replayed DPoP proofs based on the jti claim.

    Replay detection is performed on a best-effort basis and depends on the consistency guarantees of the configured cache backend.
Example 20. DPoP Assertion configuration
type: dpop
config:
  max_age: 1m
  nonce_required: true
  replay_allowed: false

Respond

This type enables instructing heimdall to preserve error information and provide it in the response body to the caller, as well as to use HTTP status codes deviating from those heimdall would usually use. The configuration, which can be done using this type affects only the behavior of the default error handler.

Following properties are supported:

  • verbose: boolean (optional)

    By making use of this property you can instruct heimdall to preserve error information and provide it in the response body to the caller. Defaults to false.

    Heimdall supports MIME type negotiation. So, if the client sets the HTTP Accept header to e.g. application/json, and Heimdall run into an unhandled internal error condition, in addition to responding with 500 Internal Server Error, it will render an error message, like shown below, if verbose has been set to true.

    {
  "code": "internal error",
  "message": "whatever led to the error"
}

    The message will however contain just high-level information, like "failed to parse something", but will not contain any stack traces.

  • with: ResponseOverride set (optional)

    This property enables mapping between response/error types used by heimdall and the corresponding HTTP status codes. Each entry must be from the list of the supported Error/State Types and contain exactly one property named code, which then defines the desired mapping.

    Example 21. Making error responses verbose and changing the HTTP codes for some errors
    verbose: true
with:
  authentication_error:
    code: 404
  authorization_error:
    code: 404

Retry

Implements an exponential backoff strategy for endpoint communication. It increases the backoff exponentially by multiplying the max_delay with 2^(attempt count)

  • give_up_after: Duration (optional)

    Sets an upper bound on the maximum time to wait between two requests. Default to 0, which means no upper bound.

  • max_delay: Duration (mandatory)

    The initial backoff.

Example 22. Retry configuration

In this example the backoff will be 1, 2, 4, 8, 16, 32, 60, …​

give_up_after: 60s
max_delay: 1s

Scopes Matcher

Scopes matcher is a configuration type allowing configuration of different strategies to match required scopes. In its simplest shape it can be just an array of strings (implemented by the Exact) scope matcher. To cover many use cases, different strategies are available and described in the following sections.

Regardless of the strategy, each matcher can explicitly be configured and supports the following configuration properties:

  • matching_strategy - the type of the mathing strategy.

  • values - the list of scope patterns

Exact

This the simplest matcher and is automatically selected, if just an array of strings is configured as shown in the following snippet:

- foo
- bar

However, as written in the Scopes Matcher section, it can also explicitly be selected by setting matching_strategy to exact and defining the required scopes in the values property.

Example 23. Essentially same configurations
matching_strategy: exact
values:
  - foo
  - bar
  - foo
  - bar

Hierarchic

This matcher enables matching hierarchical scopes, which use . as separator. Imagine your system is organized that way, that it defines namespaces for different services like this:

  • my-service being the top namespace

  • my-service.booking - being the namespace of the booking service

  • my-service.orders - being the namespace of the orders service

  • my-service.orders.partners - being the namespace of the order service for partners and

  • my-service.orders.customers - being the namespace of the order service for customers

Basically you’ve established an identity for each of your services (this is comparable to how SPIFFE IDs are organized and also used for).

Now, imagine you use these namespaces as scope values to limit the usage of the issued tokens. In such situations the hierarchic scope matcher can become handy if you would like to assert any scope of the token must be in e.g. the my-service or the my-service.orders namespace.

This matcher can only be used by explicitly setting the matching_strategy to hierarchic and defining the required patterns in the values property.

Example 24. Matching of hierarchic scopes
matching_strategy: hierarchic
values:
  - my-service

This configuration will ensure all scopes withing the scope or scp claim are within the my-service namespace. So scope claim like

{
  "scope": ["my-service.orders", "my-service.orders.customers"]
}

would match, but

{
  "scope": ["not-my-service", "my-service.orders.customers"]
}

would not match.

Wildcard

This matcher enables matching scopes using wildcards. It goes beyond the Hierarchic scope matcher by enabling usage of wildcards.

This matcher can only be used by explicitly setting the matching_strategy to wildcard and defining the required patterns in the values property.

Session Lifespan

This configuration type enables the configuration of session lifespans, used for session validation for those authenticators, which act on non-standard protocols. Following properties are available.

  • active: string (optional)

    A GJSON Path pointing to the field describing the "active" status of the session in the corresponding JSON object. The actual value in that field should be convertable to a bool type. If not set, the session is considered to be "active". "active" means it can be used and represent a valid session between the authentication system and the principal, the session has been issued to.

  • issued_at: string (optional)

    A GJSON Path pointing to the field in the corresponding JSON object, describing the time, when the session object has been issued. If not provided or not found, the issuance time is not considered during session validation.

  • not_before: string (optional)

    A GJSON Path pointing to the field in the corresponding JSON object describing the time, until which the session object is not allowed to be used. If not provided or not found, the corresponding time is not considered during session validation.

  • not_after: string (optional)

    A GJSON Path pointing to the field in the corresponding JSON object describing the time, after which the session object is not allowed to be used. If not provided or not found, the corresponding time is not considered during session validation.

  • time_format: string (optional)

    Since different authentication system use different representations for time strings, this property allows the definition of the time format/layout used by the authentication system. Defaults to Unix Epoch time stamp.

    You can use the following Go Playground link to test your time format settings.

  • validity_leeway: Duration (optional)

    Enables definition of an allowed time drift between the authentication system and heimdall for the validation of the session validity. Defaults to 0.

Example 25. Making use of session information received from Ory’s Kratos

A typical response from Kratos' whoami endpoint looks like follows (stripped to the most interesting parts):

{
  "id": "1338410d-c473-4503-a96a-53efa06e2531",
  "active": true,
  "expires_at": "2021-10-15T15:58:57.683338Z",
  "authenticated_at": "2021-10-14T15:58:57.683338Z",
  "issued_at": "2021-10-14T15:58:57.683338Z",
  "identity": {
    "id": "9496bbd5-f426-473f-b087-c7df853f274a",
    ...
  }
}

To enable usage of these properties in Heimdall, you can configure the Session Lifespan as follows:

active: active
issued_at: issued_at
not_before: authenticated_at
not_after: expires_at
time_format: "2006-01-02T15:04:05.999999Z07"
validity_leeway: 10s
Example 26. Making use of session information received from a compliant OAuth2 authorization service

A typical response from a token introspection endpoint looks like follows:

{
  "active": true,
  "client_id": "l238j323ds-23ij4",
  "username": "jdoe",
  "scope": "read write dolphin",
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "iss": "https://server.example.com/",
  "exp": 1419356238,
  "iat": 1419350238,
  "extension_field": "twenty-seven"
 }

To enable usage of these properties in Heimdall, you can configure the Session Lifespan as follows:

active: active
issued_at: iat
not_after: exp
validity_leeway: 10s

As you see, there is no need to define the time format as the times values appearing in the responses from an introspection endpoint are Unix Epoch time stamps.

Signer

When heimdall is used to issue signed objects, like JWTs, to enable upstream services to rely on authentic information, it acts as an issuer of such objects and requires corresponding configuration.

Following properties are supported:

  • name: string (optional)

    The name used to specify the issuer. E.g. if a JWT is generated, this value is used to set the iss claim. If not set, the value heimdall is used.

  • secret: Secret Reference (mandatory)

    The reference to the cryptographic material. At least one private key must be present.

TLS

Following are the supported TLS configuration properties:

  • secret: Secret Reference (mandatory)

    The reference to a key material in a secret source. At least one private key and the corresponding certificate must be present.

  • min_version: string (optional)

    The minimal TLS version to support. Can be either TLS1.2 or TLS1.3. Defaults to TLS1.3.

  • cipher_suites: string array (optional)

    Can be configured if min_version is set to TLS1.2. If min_version is set to TLS1.3 the configured values are ignored. Only the following PFS cipher suites are supported:

    • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

    • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

    • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

    Defaults to the last six cipher suites if min_version is set to TLS1.2 and cipher_suites is not configured.

Example 27. Example configuration
secret:
  source: key_store
  selector: tls_key
key_id: foobar
min_version: TLS1.2
cipher_suites:
  - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Token Usage Error Signaling

This type configures how heimdall signals token usage errors for authenticators using OAuth2 access tokens according to RFC 6750, RFC 9449, and related specifications.

If enabled, heimdall adds WWW-Authenticate response headers for supported OAuth2 token usage schemes. For regular bearer token usage, heimdall uses the Bearer authentication scheme as defined by RFC 6750. If a request uses DPoP or fails DPoP-specific validation, heimdall uses the DPoP authentication scheme and DPoP-specific error values where applicable.

Following properties are available:

  • enabled: boolean (optional)

    Enables the generation of OAuth2 token usage error challenges using the WWW-Authenticate response header. Defaults to false.

    For bearer token usage, the challenge uses the Bearer authentication scheme. For DPoP-bound token usage, the challenge uses the DPoP authentication scheme.

  • realm: string (optional)

    The realm to include in the WWW-Authenticate header. Defaults to "Please authenticate".

  • error_uri: URI (optional)

    A URI identifying a human-readable page with information about the error.

  • include_error_description: boolean (optional)

    Whether to include the optional error_description parameter. Defaults to false.

    Enabling this option may disclose implementation details and should be used with care.

  • include_required_scope: boolean (optional)

    Whether to include the required scopes using the optional scope parameter if the error is insufficient_scope. Defaults to false.

    Enabling this option may disclose details about the protected resource’s authorization model.

  • include_dpop_algorithms: boolean (optional)

    Whether to include the optional algs parameter in DPoP challenges if DPoP proof validation fails because the proof uses an unsupported signing algorithm. Defaults to false.

    If enabled, heimdall includes the configured allowed DPoP proof signing algorithms in the WWW-Authenticate header, for example algs="ES256 ES384".

Example 28. Token usage error signaling configuration and possible challenges
enabled: true
realm: example
error_uri: https://docs.example.org/oauth2/errors
include_error_description: false
include_required_scope: false
include_dpop_algorithms: true

If a bearer access token is missing, invalid, expired, or does not satisfy the configured assertions, heimdall signals the error using a Bearer challenge, for example:

WWW-Authenticate: Bearer realm="example",
                  error="invalid_token",
                  error_uri="https://docs.example.org/oauth2/errors"

Line breaks are used to enhance readability.

And if e.g., a DPoP token failed validation due to invalid nonce, heimdall returns a use_dpop_nonce challenge and includes a fresh nonce in the DPoP-Nonce response header:

WWW-Authenticate: DPoP realm="example",
                  error="use_dpop_nonce",
                  error_uri="https://docs.example.org/oauth2/errors"
DPoP-Nonce: <nonce>

If DPoP proof validation fails because the proof uses an unsupported signing algorithm and include_dpop_algorithms is enabled, heimdall includes the allowed DPoP proof algorithms:

WWW-Authenticate: DPoP realm="example",
                  error="invalid_dpop_proof",
                  algs="ES256 ES384",
                  error_uri="https://docs.example.org/oauth2/errors"

Last updated on Jun 19, 2026

Rule Providers Reference