Authorizers

Authorizers ensure that only those subjects, which are eligible can access the desired resource. This page describes the available authorizer types in detail.

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

Allow

As the name implies, this authorizer allows any request to pass through. This authorizer type also doesn’t have any configuration options.

To enable the usage of this authorizer, you have to set the type property to allow.

Example 1. Configuration of Allow authorizer

id: allow_any_request
type: allow

Deny

As the name implies, this authorizer denies any request (on HTTP response code level this is then mapped to 403 Forbidden). It basically stops the successful execution of the pipeline, resulting in the execution of the error handler mechanisms. This authorizer type doesn’t have any configuration options.

To enable the usage of this authorizer, you have to set the type property to deny.

Example 2. Configuration of Deny authorizer

id: deny_any_request
type: deny

Local (CEL)

This authorizer allows the definition of authorization requirements based on information available about the authenticated subject, the existing pipeline results, as well as the actual request, by using CEL based authorization expressions. Each expression is expected to return true to signal success. Otherwise, the authorization fails, resulting in the execution of the error handler mechanisms.

To enable the usage of this authorizer, you have to set the type property to cel.

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

expressions: Authorization Expression array (mandatory, overridable)
List of authorization expressions, which define the actual authorization logic. Each expression has access to the Subject, the Outputs, the Results, the Request, and the Values objects.
References to Outputs should be migrated to Results; see the corresponding migration note in the description of the Outputs evaluation object.
values map of strings (optional, overridable)
A key value map, which is made accessible to the CEL engine as Values object, to support "templating" of expressions (see also examples below). The actual values in that map can be templated as well with access to the Subject, the Outputs (migrate to Results, see note above), and Request objects.

Example 3. Authorization based on subject properties

In this example, the subject is checked to be a member of the "admin" group.

id: user_is_admin
type: cel
config:
  expressions:
    - expression: |
        has(Subject.Attributes.groups) &&
        Subject.Attributes.groups.exists(g, g == "admin")
      message: User is not admin

The first line of the expression verifies that the groups property exists. The second line checks whether groups contains an entry named admin.

This example also specifies a message, which is logged if the expression fails.

Example 4. Authorization based on subject and request properties

In this example, the authorizer is configured to ensure anonymous access to a resource is possible for read requests only.

id: no_modification_allowed_by_anonymous
type: cel
config:
  expressions:
    - expression: |
        Request.Method in ["GET", "HEAD", "OPTIONS"] || Subject.ID != "anonymous"
      message: Anonymous non-read access is forbidden

The usage of this type of configuration makes sense in a pipeline, which combines multiple Authenticators, allowing anonymous and authenticated access.

Example 5. Checking for a Kubernetes Service Account

In this example, the authorizer is configured to check for a service account name in the format system:serviceaccount:<namespace>:<name>, where namespace and name are provided by making use of the Values object. By default, both properties are set to an empty string.

id: check_service_account
type: cel
config:
  values:
    namespace: ""
    name: ""
  expressions:
    - expression: >
        Subject.ID == "system:serviceaccount:" + Values.namespace + ":" + Values.name

With this configuration in place, rules can override the default expression values by specifying rule-specific settings, as shown below:

# further rule settings
execute:
  - # some other steps
  - authorizer: check_service_account
    config:
      values:
        namespace: "awesome-app"
        name: "app"
  - # some further steps

Remote

This authorizer allows communication with other systems, like Open Policy Agent, Ory Keto, etc., for the actual authorization purpose. If the used endpoint answers with a non-2xx HTTP response code, this authorizer assumes that the authorization has failed, resulting in the execution of the error handler mechanisms. Otherwise, if no expressions for the verification of the response are defined, the authorizer assumes that the request has been authorized. If expressions are defined and do not fail, the authorization succeeds.

If your authorization system provides a payload in the response, heimdall inspects the Content-Type header to prepare the payload for further usage, e.g. in payload verification expressions or by a Local (CEL) authorizer. If the content type either ends with json or is application/x-www-form-urlencoded, the payload is decoded; otherwise, it is made available as a simple string. This value is available to the authorization expressions and, after successful authorization, through the Outputs property under a key matching the authorizer’s id (see also the example below). In addition, the complete endpoint response is available through the Results property under the same key.

References to Outputs should be migrated to Results; see the corresponding migration note in the description of the Outputs evaluation object.

To enable the usage of this authorizer, you have to set the type property to remote.

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

endpoint: Endpoint (mandatory, not overridable)
The API endpoint of your authorization system. At least the url must be configured. This mechanism allows templating of the url and makes the Subject object, the Outputs object, the Results object, as well as the Values (see also below) objects available to it. By default, this authorizer 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 your authorization system, you might need to configure further properties, like headers, etc.
payload: string (optional, overridable)
Your template with definitions required to communicate to the authorization endpoint. The template can make use of Values, Outputs, Results, Subject and Request objects.
expressions: Authorization Expression array (optional, overridable)
List of CEL expressions which define the logic to be applied to the response returned by the endpoint. All expressions are expected to evaluate to true if the authorization was successful. If any of the expressions evaluates to false, the authorization fails and the message defined by the failed expression will be logged.
Each expression has access to the Payload object.
forward_response_headers_to_upstream: string array (optional, overridable)
Enables forwarding of selected response headers returned by the authorization endpoint to the upstream service.
This setting is deprecated and will be removed in the 0.18.0 release. Use the response available through the Results evaluation object together with a header finalizer instead.
cache_ttl: Duration (optional, overridable)
Allows caching of the authorization endpoint responses. Defaults to 0s, which means no caching. The cache identity is derived from the authorizer, 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. Authorization expressions are evaluated for every execution, regardless of whether the authorization endpoint response was obtained remotely or reused from the cache.
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 (migrate to Results, see note above), and Request objects.

Example 6. Configuration of Remote authorizer to communicate with Open Policy Agent (OPA)

Here the remote authorizer is configured to communicate with OPA. Since OPA expects the query to be formatted as JSON, the corresponding Content-Type header is set. Since the responses are JSON objects as well, the Accept header is also provided. In addition, this example uses the basic_auth auth type to authenticate against the endpoint.

id: opa
type: remote
config:
  endpoint:
    url: https://opa.local/v1/data/{{ .Values.namespace }}/{{ .Values.policy }}
    headers:
      Content-Type: json
      Accept: json
    auth:
      type: basic_auth
      config:
        credentials:
          source: some_source
          selector: opa_credentials
  payload: |
    { "input": { "user": {{ quote .Subject.ID }} }, "some_data": {{ quote .Values.whatever }}, "more_data": {{ quote .Outputs.whatever }} }
  values:
    namespace: myapi/policy
    policy: allow_write
    whatever: |
     {{ .Request.Header("X-Whatever") }}
  expressions:
    - expression: |
        Payload.result == true
      message: User does not have required permissions

In this case, since an OPA response could look like { "result": true } or { "result": false }, heimdall makes the response also available under Outputs["opa"], with "opa" being the id of the authorizer in this example. The same value is also available in structured form under Results["opa"].Payload.

A specific rule could then use this authorizer in the following ways:

- id: rule1
  # other rule properties
  execute:
  - # other mechanisms
  - authorizer: opa # using defaults
  - # other mechanisms

- id: rule2
  # other rule properties
  execute:
  - # other mechanisms
  - authorizer: opa
    config: # overriding with rule specifics
      values:
        policy: allow_read
        whatever: |
          {{ .Request.Header("X-SomethingElse") }}
  - # other mechanisms

Last updated on Aug 25, 2026

Authenticators Contextualizers