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 orchestrating 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 can be getting information about the authenticated subject of the request, getting 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.
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. The mechanisms specified in it are executed in order of their definition.
Finalization Stage: In that stage, you can use any amount of finalization mechanisms to complete the pipeline execution and allows you transforming the information collected about the subject in the previous stages into a format expected or required by your upstream service, 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. The mechanisms specified in it are executed in order of their definition.
| Stages are implicit. That is, a pipeline is just a list of mechanisms 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. That will result in the execution of the error pipeline, which is basically a list of error handler mechanisms, ranging from a simple error response to the client (which sent the request) to sophisticated ones supporting complex logic and redirects. Mechanisms in this pipeline 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 just response with an HTTP response code based on the error raised in the authentication & authorization pipeline.
Last updated on Mar 9, 2024