Flows, stages, and policies: customizing your authentication with authentik

authentik is an open source Identity Provider that unifies your identity needs into a single platform, replacing Okta, Active Directory, and Auth0. Authentik Security is a public benefit company building on top of the open source project.

---

Login boxes, MFA prompts, retyping blurry CAPTCHA characters… the routine is so familiar that we could say it’s really pure muscle memory that logs most users in to their target application. With most legacy identity providers, a one-size-fits-none experience can throw unnecessary hurdles in some users' way, while allowing other sensitive actions without sufficient security checks.

With authentik, using our flows to define and customize that mundane user experience, you can safeguard against the mistakes and security hiccups that muscle memory actions can produce, and create a flexible, customized workflow for authentication and access.

In this article, we take a closer look at these major components of authentik, and how they work together as fundamental building blocks to create a powerful yet flexible user authentication process.

Let’s dive in and take a closer look at how flows, stages, and their associated policies are used in authentik.

What are flows, stages, and policies?

They are the major building blocks in authentik, and are used to define the login and authentication steps taken by a user.

From the authentik documentation’s terminology page:

• Flows are an ordered sequence of stages. These flows can be used to define how a user authenticates, enrolls, logs out, recovers their account,etc. Flows are YAML files.
• A stage represents a single verification or logic step. They are used to authenticate users, enroll users, and more. These stages can optionally be applied to a flow via policies.
• Policies are, at a base level a policy, a yes/no gate. The criteria that are defined in a policy will evaluate to True or False depending on the type of policy and settings. This can be used to conditionally and dynamically apply specific stages to a flow, grant/deny access to various objects, and for other custom logic.

One of our users wrote about self-hosting authentik, and included a great description of authentik’s flows and stages:

“First, you define Stages that represent a single step of authentication — something like requiring a user to enter their username or a password. There's a whole lot to choose from. Once you've set up your Stages, you'll create a Flow, stringing those Stages together until you have a complete process to authenticate, register, or even delete a user.” Nick Telsan

Software that is both feature-rich and highly customizable often results in over-engineered functionality; authentik avoids this by keeping the underlying logic simple, and by providing clear processes and guardrails for constructing the exact authentication flows your team needs.

By offering ready-to-go, out-of-the box, default flows, users can decide if they already have everything they need with the default flows or if they want to download a pre-configured flow or, for maximum customization, build out a customized log in and authentication experience.

Flows (which are sequences stored in an SQL database) can be exported or imported to an easily transportable and readable format. authentik uses YAML as its standard format, although the JSON format is also acceptable. For example, if you have a test environment where you perfect the exact flows you want to use in your production environment, you can export the file from the test environment and then upload it (import it) to the prod environment.

How are policies used?

A policy determines whether a flow is presented to a user, or whether a stage is used during execution. The decision is dynamic, based on if the defined criteria of the policy results in a True or False return.

Policies use information in the current flow’s execution context (such as “Is the user logged in?”, “Who is the user claiming to be?”, “From what geographic region is the user attempting to log in?”) to determine if a stage or flow should terminate, proceed, or alter the sequence of events.

To use a policy, it must be bound to a stage. Policies are associated with specific stages or flows by bindings; you bind a policy to the object (stage or flow) that you intend to “gate keep”. If the policy’s criteria is met (True), then the stage or flow is presented to the user.

authentik provides several purpose-built policies (GeoIP, reputation, event-matching, and many more), as well as a general purpose Expression Policy that allows an administrator to provide custom logic for their specific needs.

Flexibility in flows

The flexibility of authentik’s flows can be illustrated with specific examples provided out of the box as well as those provided by the community, including:

• Enforce the use of two-factor authentication (2FA), or a CAPTCHA prompt.
• Provide a recovery process for users to receive an email with a link to reset their password and then log in.
• Implement a reputation policy, which scores a user based on previously failed login attempts.
• Create new users and dynamically assign them to groups.
• Auto-assign a specific login flow for any users associated with a certain provider or source.
• Integrating authentik tokens with Hashicorp Vault, so that saved tokens (and automatic rotations) will appear in Vault.

If none of the provided flows meet your specific needs, you can always create a new flow, or copy an existing one to a new name and edit it for your specific use case.

Assigning Flows

So how do you determine which flow is presented to your users? The primary method for configuring which flow is used is in the instance’s brand settings. A brand is a global configuration option that allows you to customize the appearance and behaviour of the instance. Here, you can select from one of the default flows authentik provides for your instance, such as the default authentication flow (define the login process), recovery flow (defines how users can recover their access), or user settings flow (allows users to edit their profile).

You can also define which flow is presented to users based on the configured provider or source. For example, if the instance is configured to use SAML, OIDC, RAC, proxy as the provider, you can configure the instance to use a customized authentication flow. Similarly, if your instance uses credentials from a designated source (such as Google, GitHub, Discord, or Apple), then you can specify a default authentication flow and a default enrollment flow.

Putting it all together

For security and identity management tools that play a major role in a user’s days, it’s important to elevate usability and efficient workflows. With authentik’s dynamic flows, stages, and scenario-specific policies, the task of logging in is more secure, with highly-configurable, dynamic, user-specific workflows and prompts.

Build the authentication flow that you need to for your users.

Let us know if you have specific authentication needs, and want to learn more about our flows, stages, and policies, and how these essential building blocks in authentik can be put to work for your team in your environment. Reach out to us on GitHub, Discord, or with an email to hello@goauthentik.io.