Pipelines
Pipelines let you orchestrate existing authentication and authorization systems via mechanisms.
Overview
Pipelines are specified in rules and are used to authenticate and authorize the particular requests, as well as to handle encountered errors.
As described in the Discover heimdall chapter and also shown in the diagram below, central aspects of heimdall are upstream specific pipelines, which allow you to orchestrate different services to authenticate, enrich and authorize incoming HTTP requests, transform the resulting subject information into a format, or obtain credentials required for the communication with the particular upstream services.
Figure 1. Authentication & Authorization Pipeline
Authentication & Authorization Pipeline
Even the figure above shows four steps, these are actually organized in three stages as depicted in the diagram below. Each of these stages is assembled by as many mechanisms (which represent the actual steps), as required to fulfill the corresponding requirements.
Figure 2. Pipeline Stages
Authentication Stage: In that stage you can use any amount of authentication mechanisms, to let heimdall communicate with the actual authentication systems. This may involve retrieving information about a particular authenticated principal, obtaining key material to verify the authentication information provided in the request, or perform some other activities related to authentication. This stage is mandatory, which means, at least one authentication mechanism must be specified. If multiple are specified, the subsequent ones are only executed if the previous either fail or were not responsible for the authentication data available with the request. The result of this stage is a subject object, which can then be used by the subsequent stages.
A principal represents a single entity whose authentication data has been verified by a particular authenticator. In contrast, a subject is a higher-level construct that can consist of one or more principals and allows combining multiple authentication mechanisms (e.g., mutual TLS and a JWT) for a single request.
While currently only single-principal subjects are supported, the pipeline and configuration use the term principal to prepare for future support of such multi-principal compositions.
Authorization Stage: In that stage you can make use of any amount of contextualization and authorization mechanisms in any order to fulfill your authorization requirements. Here, you let heimdall communicate with other systems to collect contextual information required for authorization purposes (like e.g. getting the country for the IP, the request came from, retrieving subscription status of your customer, etc), and to perform the actual authorization, e.g. by talking to an Open Policy Agent, OpenFGA, any other type of authorization system, or even let heimdall perform the required checks locally. That stage is optional and is only executed after the successful execution of the authentication stage. Steps in this stage can optionally define conditions under which they are executed. The actual step execution happens in the order of their definitions.
Finalization Stage: In that stage, you can use any amount of finalization mechanisms to complete the pipeline execution. It allows you transforming the information collected about the subject in the previous stages — that is, the verified set of principals — into a representation expected by your upstream services, or even driving specific protocols, e.g. to obtain a token required by the upstream service. That stage is optional and is only executed after the successful execution of the previous stage. Steps in this stage can optionally define conditions under which they are executed. The actual step execution happens in the order of their definitions.
| Stages are implicit. That is, a pipeline is just a list of mechanism steps to be executed in the specified order. That means, all authentication mechanisms must be specified before any contextualization, authorization or finalization mechanisms are specified, with all finalization mechanisms required to be specified at the end. Violation of that rule will let heimdall refuse loading of the particular rule. |
Error Pipeline
Obviously, a mechanism used in the previously described Authentication & Authorization Pipeline may fail. This triggers execution of the error pipeline, which is basically a list of error handler mechanism steps, ranging from a simple error response to the client (which sent the request) to sophisticated ones supporting complex logic and redirects. Steps in this pipeline must define conditions under which they are executed. The first mechanism, which condition evaluates to true is executed and other are ignored. If conditions of all mechanisms fail, the default error handler is executed (see also below).
The error pipeline is optional. If no error handlers are defined, heimdall will simply response with an HTTP response code based on the error raised in the authentication & authorization pipeline.
Last updated on Oct 20, 2025