Rule

Rules are the heart of heimdall. These allow execution of arbitrary logic, required by your upstream service. This section describes everything related to the configuration of a particular rule and how can these be combined to rule sets, which can then be loaded by a rule provider.

Rule Configuration

A single rule consists of the following properties:

id: string (mandatory)
The unique identifier of a rule. It must be unique across all rules loaded by the same Rule Provider. To ensure this, it is recommended to let the id include the name of your upstream service, as well as its purpose. E.g. rule:my-service:public-api.
match: RuleMatcher (mandatory)
Defines how to match a rule and supports the following properties:
- url: string (mandatory)
  Glob or Regex pattern of the endpoints of your upstream service, which this rule should apply to. Query parameters are ignored.
- strategy: Matching Strategy (optional)
  Which strategy to use for matching of the value, provided in the url property. Can be glob or regex. Defaults to glob.
methods: string array (optional)
Which HTTP methods (GET, POST, PATCH, etc) are allowed for the matched URL. If not specified, every request to that URL will result in 405 Method Not Allowed response from heimdall.
upstream: string (mandatory in Proxy operation mode)
Defines where to forward the proxied request to. Used only when heimdall is operated in the Proxy operation mode. Only the URL schema and the host parts are used if this property is specified.
execute: Regular Pipeline (mandatory)
Which mechanisms to use to authenticate, authorize, hydrate (enrich) and mutate the subject of the request.
on_error: Error Handler Pipeline (optional)
Which error handler mechanisms to use if any of the mechanisms, defined in the execute property, fails. This property is optional only, if a default rule has been configured and contains an on_error definition.

Example 1. An example rule

id: rule:foo:bar
match:
  url: http://my-service.local/<**>
  strategy: glob
upstream: http://backend-a:8080
methods:
  - GET
  - POST
execute:
  - authenticator: foo
  - authorizer: bar
  - contextualizer: foo
  - unifier: zab
on_error:
  - error_handler: foobar

Matching Strategy

Matching strategies are used to match the url patterns in rules and explicitly set by making use of matching_strategy rule property. Following strategies are available:

regex - to match url expressions by making use of regular expressions.
glob - to match url expressions by making use of glob expressions.

Heimdall uses dlclark/regexp2 and gobwas/glob to match regex expressions, respectively glob expressions. Head over to linked resources to get more insights about possible options for expression definitions.

Example 2. Regular expressions patterns

https://mydomain.com/ matches https://mydomain.com/ and doesn’t match https://mydomain.com/foo or https://mydomain.com.
<https|http>://mydomain.com/<.*> matches https://mydomain.com/ and http://mydomain.com/foo. Doesn’t match https://other-domain.com/ or https://mydomain.com.
http://mydomain.com/<+> matches http://mydomain.com/123, but doesn’t match http://mydomain/abc.
http://mydomain.com/<(?!protected).*> matches http://mydomain.com/resource, but doesn’t match http://mydomain.com/protected.

Example 3. Glob patterns

https://mydomain.com/<m?n> matches https://mydomain.com/man and does not match http://mydomain.com/foo.
https://mydomain.com/<{foo*,bar*}> matches https://mydomain.com/foo or https://mydomain.com/bar and doesn’t match https://mydomain.com/any.

Regular Pipeline

As described in the Concepts section, heimdall’s decision pipeline consists of multiple mechanisms - at least consisting of authenticators and unifiers. The definition of such a pipeline happens as a list of required mechanisms (previously configured) with the corresponding ids in the following order:

List of authenticators using authenticator as key, followed by the required authenticator id. Authenticators following the first defined in the list are used by heimdall as fallback. That is, if first authenticator fails due to missing authentication data, second is executed, etc. By default, fallback is not used if an authenticator fails due to validation errors of the given authentication data. E.g. if an authenticator fails to validate the signature of a JWT token, the next authenticator in the list will not be executed. Instead, the entire pipeline will fail and lead to the execution of the error handler pipeline. This list is mandatory if no default rule is configured.

Some authenticators use the same sources to get subject authentication object from. E.g. the jwt and the oauth2_introspection authenticators can retrieve tokens from the same places in the request. If such authenticators are used in the same pipeline, you should configure the more specific ones before the more general ones to have working default fallbacks. To stay with the above example, the jwt authenticator is more specific compared to oauth2_introspection, as it will be only executed, if the token is in a JWT format. In contrast to this, the oauth2_introspection authenticator is more general and does not care about the token format, thus will feel responsible for the request as soon as it finds a bearer token. You can however also make use of the allow_fallback_on_error configuration property and set it to true. This will allow a fallback even if the verification of the credentials fail.

List of contextualizers and authorizers in any order (optional). Can also be mixed. As with authenticators, the list definition happens using either contextualizer or authorizer as key, followed by the required id. All mechanisms in this list are executed in the order, they are defined. If any of these fails, the entire pipeline fails, which leads to the execution of the error handler pipeline. This list is optional.
List of unifiers using unifiers as key, followed by the required unifier id. All unifiers in this list are executed in the order, they are defined. If any of these fails, the entire pipeline fails, which leads to the execution of the error handler pipeline. This list is mandatory if no default rule is configured.

In all cases, the used mechanism can be partially reconfigured if supported by the corresponding type. Configuration goes into the config properties. These reconfigurations are always local to the given rule. With other words, you can adjust your rule specific pipeline as you want without any side effects.

Execution of an contextualizer, authorizer, or unifier mechanisms can optionally happen conditionally by making use of a CEL expression in an if clause, which has access to the Subject and the Request objects. If the if clause is not present, the corresponding mechanism is always executed.

Example 4. Complex pipeline

# list of authenticators
- authenticator: foo
- authenticator: bar
  config:
    subject: anon
  # ... any further required authenticator
# list of authorizers and contextualizers in any order
- contextualizer: baz
  config:
    cache_ttl: 0s
- authorizer: zab
- contextualizer: foo
  if: Subject.ID != "anonymous"
- contextualizer: bar
- authorizer: foo
  if: Request.Method == "POST"
  config:
    expressions:
      - expression: |
          // some expression logic deviating from the
          // definition in the pipeline configuration.
  # ... any further required authorizer or contextualizer
# list of unifiers
- unifier: foo
- unifier: bar
  config:
    headers:
    - X-User-ID: {{ quote .ID }}
  # ... any further required unifiers

This example uses

two authenticators, with authenticator named bar being the fallback for the authenticator named foo. This fallback authenticator is obviously of type anonymous as it reconfigures the referenced prototype to use anon for subject id.
multiple contextualizers and authorizers, with first contextualizer having its cache disabled (cache_ttl set to 0s) and the last authorizer being of type cel as it reconfigures the referenced prototype to use a different authorization script.
two unifiers, with the second one being obviously of type header, as it defines a X-User-ID header set to the value of the subject id to be forwarded to the upstream service.
contextualizer foo is only executed if the authenticated subject is not anonymous.
authorizer foo is only executed if the request method is HTTP POST.

Error Handler Pipeline

Compared to the Regular Pipeline, the error handler pipeline is pretty simple. It is also a list of mechanisms, but all referenced types are error handler types. Thus, each entry in this list must have error_handler as key, followed by the ìd of the required error handler, previously defined in Heimdall’s Pipeline Mechanisms configuration. Error handlers are always executed as fallbacks. So, if the condition of the first error handler does not match, second is selected, if its condition matches, it is executed, otherwise the next one is selected, etc. If none of the conditions of the defined error handlers match, the default error handler is executed.

As with the regular pipeline, partial reconfiguration of the used mechanisms is possible if supported by the corresponding type. The overrides are always local to the given rule as well.

Example 5. Two error handlers

- error_handler: foo
- error_handler: bar
  config:
    when:
      # rule specific conditions

This example uses two error handlers, named foo and bar. bar will only be selected by heimdall if foo 's error condition (defined in Heimdall’s Pipeline Mechanisms configuration) does not match. bar does also override the error condition as required by the given rule.

Rule Set

In principle, a rule set is just a list of rules with some additional meta information. Each RuleSet definition has the following attributes if not stated otherwise by a particular provider:

version: string (mandatory)
The version schema of the RuleSet. The current version of heimdall supports only the version 1.
name: string (optional)
The name of a rule set. Used only for logging purposes.
rules: Rule Configuration array (mandatory)
List of the actual rules.

Example 6. Rule set with two rules

version: "1"
name: my-rule-set
rules:
- id: rule:1
  match:
    url: https://my-service1.local/<**>
  methods: [ "GET" ]
  execute:
    - authorizer: foobar
- id: rule:2
  match:
    url: https://my-service2.local/<**>
  methods: [ "GET" ]
  execute:
    - authorizer: barfoo

Last updated on Jun 20, 2023

Error Handlers

Default Rule