Mechanisms

Authenticators, which inspect HTTP requests for presence of authentication objects, like e.g. the presence of a specific cookie. If such objects exist, authenticators verify the related authentication status and obtain information about the corresponding principal. A principal, could be a user who tries to use particular functionality of the upstream service, a machine (if you have machine-2-machine interaction), or something different. Authenticators ensure each required principal is authenticated and that the information about it is valid. The authenticated principals together form the basis of the subject, which is used by all subsequent mechanisms.

Authorizers, which ensure that the subject — composed of the verified principals — has the required permissions to submit the given HTTP request and thus to execute the corresponding logic in the upstream service. E.g. a specific endpoint of the upstream service might only be accessible to a "user" from the "admin" group, or to an HTTP request if a specific HTTP header is set.

Contextualizers, which enrich the information about the subject with further contextual information, required either by the upstream service itself or an authorizer. This can be handy if the actual authentication system doesn’t have all information about the subject (which is usually the case in microservice architectures), or if dynamic information about the subject, such as the current location inferred from the IP address, is required.

Finalizers, which, as the name implies, finalize the execution of the pipeline and enrich the request with data such as subject information or authentication tokens required by the upstream service. Available options range from doing nothing, to adding a simple header or structured JWT, to driving specific protocols, e.g. to obtain a token required by the upstream service.

Error Handlers, which are responsible for execution of logic if any of the mechanisms described above fail. These range from a simple error response to the client, that sent the request, to sophisticated ones that support complex logic and redirects.

Mechanisms are per se generic and must be configured for usage in particular use cases.

That configuration provides useful default behavior addressing your particular requirements, like which identity management system to use, etc.

Only those mechanisms, which are defined can be used in rules. With other words, if you do not define any mechanism, you cannot define any rule.

That makes the definition of rules also very simple - just reference the required mechanisms and "tune" the configuration, specified in the catalogue only if required. Not everything can be tuned though.

It also provides secure defaults. E.g. that way you can ensure heimdall communicates only to those systems, you allowed.