Skip to main content

Authenticator Validation stage

This stage validates an already configured Authenticator Device. This device has to be configured using any of the other authenticator stages:

You can select which device classes are allowed.

Using the Not configured action, you can choose what happens when a user does not have any matching devices.

  • Skip: Validation is skipped and the flow continues
  • Deny: Access is denied, the flow execution ends
  • Configure: This option requires a Configuration stage to be set. The validation stage will be marked as successful, and the configuration stage will be injected into the flow.

By default, authenticator validation is required every time the flow containing this stage is executed. To only change this behavior, set Last validation threshold to a non-zero value. (Requires authentik 2022.5) Keep in mind that when using Code-based devices (TOTP, Static and SMS), values lower than seconds=30 cannot be used, as with the way TOTP devices are saved, there is no exact timestamp.

Options​

Require more than one MFA method​

To require users to enroll more than one MFA method and validate with each method on every login, add multiple Authenticator Validation stages to the same authentication flow.

Configure each authenticator validation stage with a different set of allowed Device classes, and set Not configured action to Configure.

Example: require both TOTP and WebAuthn​

To require both TOTP and WebAuthn:

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Create a TOTP setup stage and a WebAuthn setup stage if you do not already have them.
  3. Navigate to Flows and Stages > Stages and create an Authenticator Validation stage for TOTP:
    • Set Device classes to totp.
    • Set Not configured action to Configure.
    • Set Configuration stages to your TOTP setup stage.
  4. Create a second Authenticator Validation stage for WebAuthn:
    • Set Device classes to webauthn.
    • Set Not configured action to Configure.
    • Set Configuration stages to your WebAuthn setup stage.
  5. Navigate to Flows and Stages > Flows and open your authentication flow.
  6. On the Stage Bindings tab, bind both validation stages to the flow in the order that you want users to enroll them.

On first sign-in, users who do not yet have one of the required methods are prompted to configure it before the flow continues. On later sign-ins, each validation stage checks only the device classes configured on that stage.

Require at least two enrolled MFA methods of any type​

If you want to require users to enroll at least two different MFA methods, regardless of which types they choose, use an Expression Policy to count the enrolled device classes for the user.

To enforce this requirement:

  1. Log in to authentik as an administrator and open the authentik Admin interface.
  2. Navigate to Customization > Policies and create an Expression Policy.
  3. Add an expression like the following to count the user's confirmed authenticator types:
from authentik.stages.authenticator import devices_for_user

pending_user = request.context.get("pending_user")
if not pending_user or not pending_user.pk:
    return False

device_types = {
    device.__class__.__name__.lower().replace("device", "")
    for device in devices_for_user(pending_user, confirmed=True)
}

return len(device_types) >= 2
  1. Bind the policy to the flow or stage binding that controls whether the user can continue without enrolling another authenticator.

Allow users to choose from multiple enrollment methods​

If you select multiple Configuration stages on a single validation stage, users can choose which authenticator to enroll for that requirement.

Less-frequent validation​

You can configure this stage to only ask for MFA validation if the user hasn't authenticated themselves within a defined time period. To configure this, set Last validation threshold to any non-zero value. Any of the user's devices within the selected classes are checked.

Passwordless authentication​

caution

Firefox has some known issues regarding TouchID (see https://bugzilla.mozilla.org/show_bug.cgi?id=1536482)

Passwordless authentication currently only supports WebAuthn devices, which support passkeys, security keys, and biometrics. For an alternate passwordless setup, see Password stage, which supports other types.

If you want users to authenticate with a passkey via the browser's built-in passkey/autofill UI on the Identification screen ("conditional UI" / passkey autofill), configure it in the Identification stage. This requires a discoverable credential (aka resident key).

To configure passwordless authentication, create a new Flow with the designation set to Authentication.

As the first stage, add an Authenticator validation stage with the WebAuthn device class allowed. After this stage you can bind any additional verification stages. As the final stage, bind a User login stage.

Users can either access this flow directly via its URL, or you can modify any Identification stage's Passwordless flow setting to add a direct link to this flow.

Logging​

Logins that used Passwordless authentication have the auth_method context variable set to auth_webauthn_pwl, and the device used is saved in the arguments. Example:

{
    "auth_method": "auth_webauthn_pwl",
    "http_request": {
        "args": {
            "query": ""
        },
        "path": "/api/v3/flows/executor/test/",
        "method": "GET"
    },
    "auth_method_args": {
        "device": {
            "pk": 1,
            "app": "authentik_stages_authenticator_webauthn",
            "name": "test device",
            "model_name": "webauthndevice"
        }
    }
}

WebAuthn Device type restrictions​

Optionally restrict which WebAuthn device types can be used to authenticate.

When no restriction is set, all WebAuthn devices a user has registered are allowed.

These restrictions only apply to WebAuthn devices created with authentik 2024.4 or later.

Automatic device selection​

If the user has more than one device, the user is prompted to select which device they want to use for validation. After the user successfully authenticates with a certain device, that device is marked as "last used". In subsequent prompts by the Authenticator validation stage, the last used device is automatically selected for the user. Should they wish to use another device, the user can return to the device selection screen.