Configuration Introduction

Configuration in heimdall can refer to two different things:

the static startup configuration and
the configuration of rules, respectively rule sets

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 supported pipeline mechanisms, 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.

Static Startup Configuration

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

rules:
  mechanisms:
    authenticators:
    - id: anonymous_authenticator
      type: anonymous
    unifiers:
    - id: create_jwt
      type: jwt

  default:
    methods:
      - GET
      - POST
    execute:
      - authenticator: anonymous_authenticator
      - unifier: create_jwt

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

rules:
  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}
    unifiers:
    - id: create_jwt
      type: jwt

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 methods of the default rule can be configured in a config file as
```
rules:
  default:
    methods:
      - GET
      - POST
```
and using environment variables with
```
HEIMDALLCFG_RULES_DEFAULT_METHODS_0=GET
HEIMDALLCFG_RULES_DEFAULT_METHODS_1=POST
```
For structured configuration, like the definition of the authenticators in the example above
```
rules:
  mechanisms:
    authenticators:
    - id: anonymous_authenticator
      type: anonymous
```
The corresponding environment variables would be
```
HEIMDALLCFG_RULES_MECHANISMS_AUTHENTICATORS_0_ID=anonymous_authenticator
HEIMDALLCFG_RULES_MECHANISMS__AUTHENTICATORS_0_TYPE=anonymous
```
If a name of a property has _ it must be escaped with an additional _.
E.g. the service name, appearing for heimdall for your tracing backend can be configured in a configuration file with
```
tracing:
  service_name: foobar
```
and using the environment variables with
```
HEIMDALLCFG_TRACING_SERVICE__NAME=foobar
```

Rule Set Configuration

Heimdall gets the rule sets from rule providers, which, depending on the provider, can load rules from a plain old configuration file, residing in the local file system, or even integrate with Kubernetes to load rules from custom resources.

In all cases, a single rule definition adheres to the schema defined in rule configuration.

Usage of environment variables is not possible with, respectively in rule sets.

Last updated on Jun 11, 2023

Proxy Service Quickstart

Install