Learn Authentik - Authentication Stages & MFA

#Introduction

In episode 6, you learned to create policies — including the pattern that forces some users through MFA. Now it's time to open the inner workings of the machine: how the authentication flow actually works, and how that second security layer is executed by Authentik.

Imagine a building with two layered doors. The first door locks with a password — anyone who memorizes the combination can enter. The second door only opens if you also carry a special access card. One key alone isn't enough; that combination is what's called Multi-Factor Authentication. In this episode, you'll program both doors, from the identification stage to the authenticator validate stage.

#The Authentication Flow in Three Stages

In general, the login flow in Authentik runs through three stages represented by three stage types:

1. Identification stage: finds out which user is trying to log in.
2. Password stage: validates that user's credentials.
3. Authenticator validate stage: checks the MFA device, if required.

This order isn't a rigid rule — Authentik lets you rearrange and add other stages — but it's a sensible default pattern. Each stage answers a different question: "who are you", "what proof of knowledge do you have", and "what proof of possession do you have".

#Identification Stage

The identification stage answers the first question. This stage displays the login form, then looks up the user by username or email. Several behaviors can be configured:

• User lookup: search can be case-insensitive, and can be limited to specific sources.
• Built-in CAPTCHA: Authentik provides an internal CAPTCHA test that can be enabled to make simple bots that guess usernames harder.
• Pseudonym mode: a mode that hides the list of valid users — useful for preventing account enumeration.

The lookup result is stored as the user being processed, often called pending_user, in the flow context — data that later stages and policies (as you learned in episode 6) read.

#Password Stage

The password stage validates the password against the configured authentication backend: Authentik's internal user database, or an LDAP source if you use federation. Several things can be configured:

• Password policies: the complexity, expiry, and reuse-prevention rules from episode 6 are evaluated here too.
• Remember me: an option that makes the session last longer; this decision is stored as a session marker in the flow context.
• Password change: the same stage can be used in a change-password or reset-password flow.

Note: the password stage only validates "what you know". It doesn't guarantee security if the password has already leaked — that's why the second door exists.

#Authenticator Validate Stage

This is the second door. The authenticator validate stage checks whether the user has a registered MFA device, then asks them to verify. What's interesting is that this stage is conditional: it only runs if the policy bound to the stage binding passes. That's where the "MFA required for admins" pattern from episode 6 comes from.

#Supported MFA Methods

Authentik supports several authenticator types users can enroll:

• TOTP: a six-digit code that changes every 30 seconds, generated by authenticator apps like Google Authenticator or Aegis. The standard, most universal choice.
• WebAuthn/FIDO2: passkeys and security keys like YubiKey. No shared secret is used — the browser and Authentik exchange cryptographic signatures.
• Static OTP: one-time tokens printed as backup codes. Just like a spare key under the flower pot.
• Duo Push: approval notifications via the Duo app, through a third-party provider.
• SMS or Email OTP: can be built via custom stages or outpost/workflow integrations, useful when users don't have an authenticator device.

#Duplicate Stage: Login with One of Many Methods

There are situations where you want to give users a choice: "login with password OR passkey", or "verify with TOTP OR backup code". That's the purpose of the duplicate stage.

A duplicate stage marks a step as already completed. If several stages in one flow are marked as duplicates of each other, once one finishes, the rest are automatically skipped. Like a station gate: after your ticket is validated at one gate, you don't need to pass through the other queue gates.

This is also the key pattern for passwordless: run a WebAuthn duplicate stage alongside the password stage, so users with a passkey can log in without typing a password at all.

#Enrollment and Recovery

MFA is useless if users have no way to enroll devices. This is where the setup stages and supporting flows come in:

• Authenticator setup stages: authenticator-totp-setup, authenticator-webauthn-setup, and authenticator-static-setup. Each stage shows instructions, validates the device, then saves it to the user.
• Enrollment flow: when a new user registers (default-enrollment-flow), an MFA setup stage is appended at the end so the first device is enrolled right away.
• Recovery flow: default-recovery-flow is used when a user forgets their password or loses a device. This flow usually verifies email or backup codes before allowing new device setup.

#Binding MFA to Applications

The most common way to enable MFA is binding a policy to the authenticator validate stage binding in the authentication flow. For example: require MFA only for members of the admins group.

Expression policy: MFA required for the admins group

if ak_is_group_member(request.user, name="admins"):
    return True
return False

This policy is bound to the authenticator validate stage binding. The result: members of the admins group pass through the second door, while regular users go straight in after the password. Note how this works — a failing policy skips the stage, it doesn't stop the login. To enforce MFA, the validation stage must be one that only passes if a device is verified.

The second frequently used pattern is only running a setup stage when the user has no device at all — for example in the enrollment flow.

Expression policy: setup only for those without a device

return not ak_user_has_authenticator(request.user)

#Closing

Key points from this episode:

• The basic login flow: the identification stage finds the user, the password stage validates credentials, the authenticator validate stage checks MFA.
• MFA methods: TOTP, WebAuthn, static OTP, Duo Push, plus SMS and email OTP via custom integrations.
• The duplicate stage enables "one of many ways" login and the passwordless pattern.
• Enrollment and recovery flows keep the MFA device lifecycle healthy.
• MFA is enabled via a policy bound to the authenticator validate stage binding.

Now both building doors are programmed: identity is verified, and MFA secures what matters most. Only one question remains — how can outside applications take advantage of all this? In episode 8, you'll open the third door: creating OAuth2 and OIDC providers in Authentik so external applications can log in with an industry standard.