Configuration

This page explains the available configuration options in detail.

Configuration in heimdall can refer to two different things:

the static startup configuration, which is the scope of this document and
the configuration of rules, respectively rule sets, which you can find here.

Elements in the static configuration set up the services, like decision service, which basically define the entry points, heimdall will listen to, the observability capabilities, like logging, the mechanism catalogue, the default rule, as well as the rule providers (these elements are not expected to change often).

The rule set contains everything that defines how the requests are handled by heimdall for your system. This configuration can change and is seamlessly hot-reloaded, without any request interruption or connection loss.

Overview

There are two different, not mutually exclusive (you can combine them), ways to define static configuration options in Heimdall:

in a configuration file (only YAML is supported as format)
as environment variables

The evaluation happens also in the order stated above. That also means, you can always overwrite configuration options defined in a configuration file with corresponding environment variables.

If no configuration is provided, heimdall will set useful defaults. These are however not enough, as heimdall doesn’t know your context - which mechanisms are required for the one or the other of your upstream services. So, you’ll not really be able to use heimdall as all requests will be answered with an HTTP 405 Method Not Allowed response code.

Configuration File

At start up, heimdall searches for static configuration in a file named heimdall.yaml in

/etc/heimdall
$HOME/.config
the current working directory

You can also override this using the config argument: heimdall --config <path-to-your-config-file>.

The values in the configuration file can also make use of environment variables. Access to these happens using Bash syntax. Following expressions are supported:

${var} - Value of $var
${var=default} - If $var is not set, evaluate expression as default
${var:=default} - If $var is not set or is empty, evaluate expression as default

Example 1. Possible minimal fully working configuration

The configuration below defines a default rule which lets heimdall create a JSON Web Token (JWT) with sub claim set to anonymous for every request on every URL for the HTTP methods GET and POST. The JWT itself will be put into the Authorization header as a bearer token.

log:
  level: info

mechanisms:
  authenticators:
  - id: anonymous_authenticator
    type: anonymous
  finalizers:
  - id: create_jwt
    type: jwt
    config:
      signer:
        key_store:
          path: /etc/heimdall/signer.pem

default_rule:
  execute:
    - authenticator: anonymous_authenticator
    - finalizer: create_jwt

Example 2. Configuration with a mechanism defined using environment variables substitution

mechanisms:
  authenticators:
  - id: hydra_authenticator
    type: oauth2_introspection
    config:
      introspection_endpoint:
        url: http://hydra:4445/oauth2/introspect
        auth:
          type: basic_auth
          config:
            user: ${INTROSPECT_EP_USER}
            password: ${INTROSPECT_EP_PASSWORD}
  finalizers:
  - id: create_jwt
    type: jwt
    config:
      signer:
        key_store:
          path: ${SIGNER_KEY_STORE_FILE}

Environment Variables

Every configuration property, which can be defined in a configuration file can also be defined as environment variable. Following rules apply:

If not specified while starting heimdall, all variables start with HEIMDALLCFG_ prefix.

If for whatever reason, your environment configuration contains variables starting with HEIMDALLCFG_, which do not define heimdall specific configuration, heimdall will refuse starting if such configuration variable clashes (has an unexpected type) with heimdall’s configuration properties (even for environment variables, the configuration is type safe). You can overcome such situation, by ether renaming such variables, or, if this is not possible, make use of the --env-config-prefix flag with heimdall’s serve command.

Properties in a hierarchy are separated by _
E.g. the log level can be set to info in a config file as also shown in the above example with
```
log:
  level: info
```
and using an environment variable with
```
HEIMDALLCFG_LOG_LEVEL=info
```
Array entries must be defined using _<IDX>[_], with IDX being the index of the array starting with 0 and _ in brackets being only required, if the value of the configured element has a structure/hierarchy.
E.g. the trusted_proxies property of the decision service can be configured in a config file as
```
serve:
  decision:
    trusted_proxies:
      - 192.168.1.0/24
      - 192.168.2.0/24
```
and using environment variables with
```
HEIMDALLCFG_SERVE_DECISION_TRUSTED__PROXIES_0=192.168.1.0/24
HEIMDALLCFG_SERVE_DECISION_TRUSTED__PROXIES_0=192.168.2.0/24
```
For structured configuration, like the definition of the authenticators in the example above
```
mechanisms:
  authenticators:
  - id: anonymous_authenticator
    type: anonymous
```
The corresponding environment variables would be
```
HEIMDALLCFG_MECHANISMS_AUTHENTICATORS_0_ID=anonymous_authenticator
HEIMDALLCFG_MECHANISMS_AUTHENTICATORS_0_TYPE=anonymous
```
If a name of a property has _ it must be escaped with an additional _.
E.g. by setting the span processor to simple, you can instruct heimdall to synchronously export the created spans via configured exporters.
```
tracing:
  span_processor: simple
```
and using the environment variables with
```
HEIMDALLCFG_TRACING_SPAN__PROCESSOR=simple
```

Last updated on Jun 18, 2024

Operating Modes CLI