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
While the figure above presents four steps, the authentication and authorization pipeline is actually divided into three stages, as illustrated in the diagram below. Within each stage, you can define any number of steps, where each step represents the use of a specific mechanism to fulfill that stage’s requirements.
Figure 2. Pipeline Stages
Authentication Stage: In this stage you can define any number of steps making use of authentication mechanisms, allowing heimdall to communicate with the actual authentication systems. This may involve retrieving information about a particular authenticated principal, obtaining key material to verify authentication data provided with the request, or perform other authentication-related activities. The result of this stage is a subject object, aggregating all verified principals, which is then made available to the subsequent stages.
This stage is mandatory, meaning at least one authentication step must be defined. Authenticator steps may each contribute their own principal to the resulting subject, or they may target the same principal and thus form a fallback chain, where a subsequent step is only used if a previous one fails or determines that it is not responsible for the authentication data present in the request.
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.
Authorization Stage: In this stage you can define any number of steps that make use of contextualization and authorization mechanisms in any order, required to satisfy your authorization needs. Here, you let heimdall communicate with other systems to collect contextual information required for authorization purposes (for example, determining the country associated with the request’s IP, 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.
This stage is optional and is executed only after the authentication stage completes successfully. 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 this stage you can define any number of steps that make use of finalization mechanisms to complete the pipeline execution. It allows you transforming the information collected about the subject in the previous stages — 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.
This stage is optional and is executed only after the previous stage completes successfully. As with the authorization stage, steps may specify conditions controlling their execution, and they run in the order in which they are defined.
| Stages are implicit. A pipeline is simply a list of steps executed in the specified order. All steps referencing authentication mechanisms must appear before any steps referencing contextualization, authorization, or finalization mechanisms, and all finalization steps must appear at the end. If this ordering is violated, heimdall will refuse to load the corresponding rule. |
Error Pipeline
The execution of any step defined in the Authentication & Authorization Pipeline may fail, which leads to the execution of the error pipeline. This pipeline is also a list of steps, but each of them references an error handler mechanism. These mechanisms range from simple ones that return an error response to the client to more sophisticated variants that support complex logic or redirects.
Each step in the error pipeline must define a condition controlling when it is executed. The first step whose condition evaluates to true is executed and all remaining steps are ignored. If none of the conditions match, a default error handler is applied (see below).
The error pipeline is optional. If no error handler steps are defined, heimdall responds with an HTTP status code derived from the error raised in the Authentication & Authorization Pipeline.
Last updated on Feb 7, 2026