Operating Modes

To support different deployment scenarios, heimdall supports two operating modes.

Decision Mode

In this mode you can integrate heimdall with existing reverse proxies, or API gateways (like Kong, NGNIX, Envoy, Traefik and much more)

Figure 1. Decision Deployment

In this mode heimdall can be integrated with most probably all modern API gateways and reverse proxies as a so-called "authentication middleware". Here the reverse proxy, respectively API gateway integrating with heimdall, will forward requests to heimdall by making use of its main service endpoint for authentication and authorization purposes. As in the Reverse Proxy mode, heimdall will check if these requests match and satisfy the conditions defined in the available rules. If not, heimdall returns an error to its client (here API gateway/reverse proxy). If the rule execution was successful, it also responds to the API gateway/reverse proxy with 200 OK (can be overridden if required) and sets headers/cookies, specified in the matched rule, which are then forwarded to the upstream service.

Starting heimdall in this mode happens via the serve decision command. Head over to the description of CLI as well as to corresponding configuration options for more details.

Example 1. Decision Service Example

Imagine following request hits heimdall (sent to it by an API gateway)

GET /my-service/api HTTP/1.1
Host: heimdall:4456
X-Forwarded-Host: my-backend-service

Some payload

And there is a rule, which allows anonymous requests and sets a header with subject id set to anonymous like this

id: rule:my-service:anonymous-api-access
match:
  routes:
    - path: /my-service/api
  scheme: http
  hosts:
    - type: exact
      value: my-backend-service
  methods:
    - GET
execute:
  - authenticator: anonymous-authn
  - finalizer: id-header

Then heimdall will respond with:

HTTP/1.1 200 OK
X-User-ID: anonymous

Proxy Mode

In this operation mode you can use heimdall as a reverse proxy in front of your upstream API or web server.

Figure 2. Proxy Deployment

In this mode heimdall forwards requests to the upstream service if these satisfy the conditions defined in matched rules. Otherwise, heimdall returns an error to the client. If the execution of the rule was successful, it also forwards additional headers, specified in the rule to the upstream service.

Starting heimdall in this mode happens via the serve proxy command. Head over to the description of CLI as well as to main service configuration options for more details.

Example 2. Reverse Proxy Example

Imagine following request hits heimdall

GET /my-service/api HTTP/1.1
Host: heimdall:4456

Some payload

And there is a rule, which allows anonymous requests and sets a header with subject id set to anonymous like this

id: rule:my-service:anonymous-api-access
match:
  routes:
    - path: /my-service/api
  methods:
    - GET
forward_to:
  host: my-backend-service:8888
execute:
  - authenticator: anonymous-authn
  - finalizer: id-header

Then the request will be forwarded as follows:

GET /my-service/api HTTP/1.1
Host: my-backend-service:8888
X-User-ID: anonymous

Some payload

Last updated on Apr 8, 2025

Rule Provider Configuration