Default Rule

Heimdall lets you not only define upstream service specific rules, it does also support a definition of an optional default rule, which, if defined, kicks in, if no other rule matches. This way you can ensure secure defaults by simultaneously reducing the amount of work while defining upstream service API specific rules. That is, an upstream service API specific rule can reuse definitions from the default rule.

The default rule does not support all the properties, which can be configured in a specific rule. E.g. it can not be used to forward requests to an upstream service, heimdall is protecting. So, if you operate heimdall in the reverse proxy mode, the default rule should be configured to reject requests. Otherwise, heimdall will respond with an error.

The configuration of the default rule can be done by making use of the default property and configuring the following options.

  • methods: string array (optional)

    Which HTTP methods (GET, POST, PATCH, etc) are allowed. Expansion using ALL and removal by prefixing the method with an ! is supported as with the regular rules. Defaults to an empty array. If the default rule is defined and the upstream service API specific rule (see also Rule Definition does not override it, no methods will be accepted, effectively resulting in 405 Method Not Allowed response to Heimdall’s client for any urls matched by that particular rule.

  • execute: Regular Pipeline (mandatory)

    Which mechanisms to use for authentication, authorization, hydration (enrich) and mutation of the request and the subject. At least one authenticator and one unifier must be defined. A specific rule (see also Rule) can omit the definition of authenticators, if it wants to reuse the authenticators defined in the default rule. Same is true for other mechanisms. Exception are authorizers and contextualizers. As soon, as a specific rule defines at least one authorizer or contextualizer, those authorizers and contextualizers (defined in the default rule) are not considered anymore.

  • on_error: Error Handler Pipeline (mandatory)

    Which error handler mechanisms to use if any of the mechanisms, defined in the execute property fail. Allows omitting the definition of error handlers in specific rules. As soon as a specific rule defines at least one error handler mechanism, all error handler mechanisms, defined in the default rule are ignored.

Example 1. Default rule configuration
rules:
  default:
    methods:
      - GET
      - PATCH
    execute:
      - authenticator: session_cookie_from_kratos_authn
      - authenticator: oauth2_introspect_token_from_keycloak_authn
      - authorizer: deny_all_requests_authz
      - unifier: jwt_unifier
    on_error:
      - error_handler: authenticate_with_kratos_eh

This example defines a default rule, which allows HTTP GET and PATCH requests on any URL (will respond with 405 Method Not Allowed for any other HTTP method used by a client). The regular pipeline consists of two authenticators, with session_cookie_from_kratos_authn being the first and oauth2_introspect_token_from_keycloak_authn being the fallback (if the first one fails), a deny_all_requests_authz authorizer and the jwt_unifier unifier. The error pipeline is configured to execute only the authenticate_with_kratos_eh error handler.

Obviously, the regular pipeline (defined in the execute property) of this default rule will always result in an error due to deny_all_requests_authz. This way it is thought to provide secure defaults and let the upstream specific rules override at least the part dealing with authorization. Such an upstream specific rule could then look like follows:

id: rule:my-service:protected-api
match:
  url: http://my-service.local/foo
execute:
  - authorizer: allow_all_requests_authz

Take a look at how methods, on_error, as well as the authenticators and unifiers from the execute definition of the default rule are reused. Easy, no?

Last updated on Jul 20, 2023

Rule
Rule Providers