Skip to main content

Password stage

The Password stage prompts the current pending_user for a password and validates it against one or more configured backends.

About the password stage​

Use this stage in authentication or password-change flows when a user should prove possession of a password.

The stage supports authentik's built-in password database, app passwords, LDAP-backed passwords, and Kerberos-backed passwords.

Configuration options​

  • Backends: select one or more password backends to test in order.
    • User database + standard password
    • User database + app passwords
    • User database + LDAP password
    • User database + Kerberos password
  • Failed attempts before cancel: how many failed password submissions are allowed before the flow is canceled. This only ends the flow; the user can restart the flow immediately.
  • Failed attempts before lockout: Enterprise Lock password login after this many consecutive failed attempts, until an administrator unlocks it. LDAP and Kerberos users can be exempt as described below. Set this option to 0 to disable lockout.
  • Last-attempt warning message: Enterprise Warning shown when the user has one attempt remaining. Leave this blank to show no warning.
  • Lockout message: Enterprise Message shown when the user's password has been locked. Leave this blank to show a generic authentication error instead.
  • Allow show password: show a button that reveals the entered password.
  • Configuration flow: optional authenticated flow that lets users configure or change their password from user settings.

Password lockout Enterprise​

Set Failed attempts before lockout above 0 to lock password login after that many consecutive failed attempts. The count belongs to the user and persists across flows and sessions. Successful password validation or a password change clears the count.

Lockout applies in Password stages, including those embedded in an Identification stage. A locked password is rejected even when correct. App passwords submitted through these stages are also rejected. App passwords used outside these stages, such as for OAuth2 client credentials, are unaffected. Existing sessions and authentication methods that bypass password validation, such as passwordless flows, are unaffected.

Service accounts and internal service accounts are exempt. When the corresponding backend is selected, lockout also exempts LDAP users if any LDAP source is enabled, and Kerberos users linked to an enabled Kerberos source. An external source outage can look like an incorrect password.

The default response is a generic authentication error. Optional Last-attempt warning message and Lockout message settings provide more detail. A lockout message is shown only after the flow reaches its configured attempt limit.

Anyone who knows a username can trigger automatic lockout by submitting incorrect passwords. Consider adding a CAPTCHA stage or reputation policy to limit abusive attempts.

Lock or unlock a password​

In the Admin interface, go to Directory > Users, select a user, and click Lock password login or Unlock password login. Both actions require permission to view the user and reset their password, granted globally or for that user. The same permissions apply when targeting your own account.

These actions are available for users with a password device, which authentik creates the first time a password is set. Deactivated users can also have their passwords locked. Changing or resetting a password clears its failure count but preserves its lock. Unlock password login separately to allow it again.

An Enterprise license is required to create new locks, automatically or manually. Existing locks remain enforced without a valid license, and unlocking remains available. Lock and unlock actions create authenticator_locked and authenticator_unlocked audit events. Their authenticator context identifies the device; filter on authenticator.model_name equal to passworddevice to select password locks.

Manage locks through the API​

Use the user's password_device ID with POST /api/v3/authenticators/password/{id}/lock/ or POST /api/v3/authenticators/password/{id}/unlock/. The ID is available from the users API and is null when the user has no password device. The same user permissions and license requirements apply as in the Admin interface.

Flow integration​

This stage is typically bound after an Identification stage and before an Authenticator Validation or User Login stage.

If the Identification stage has its Password stage option set, the password prompt is rendered as part of the identification step and the Password stage should not also be bound separately in the same flow.

Notes​

tip

Service accounts have automatically generated app passwords. Those can be viewed from the service account's user settings or from the admin interface.

Passwordless patterns​

There are two common ways to avoid prompting for a password:

  • Use an Authenticator Validation stage with WebAuthn for a dedicated passwordless flow.
  • Conditionally skip the Password stage by binding a policy to its stage binding.

If you want users to be able to pick a passkey from the browser's passkey/autofill UI without entering a username first, configure Passkey autofill (WebAuthn conditional UI) in the Identification stage. This is separate from configuring a dedicated passwordless flow, and can be used alongside normal identification flows.

Dynamically skip a Password stage​

This setup keeps a normal identification flow, but skips the Password stage for users who already have a supported authenticator configured.

To configure this setup:

  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. Configure the expression so that it returns True only when the Password stage should run. Use one of the expressions below, depending on the authenticator type.
  4. Navigate to Flows and Stages > Flows and open your authentication flow.
  5. Open the Stage Bindings tab, expand the Password stage binding, and bind the Expression Policy there. Do not bind it to the flow itself or directly to the stage object. For more background, see Bind a policy to a stage binding.
  6. On the Password stage binding, enable Evaluate when stage is run. Disable Evaluate when flow is planned unless the user is already known before the flow starts. See Planning and stage policies.

WebAuthn​

from authentik.stages.authenticator_webauthn.models import WebAuthnDevice

pending_user = request.context.get("pending_user")
if not pending_user:
    return True

return not WebAuthnDevice.objects.filter(user=pending_user, confirmed=True).exists()

Or for Duo:

from authentik.stages.authenticator_duo.models import DuoDevice

pending_user = request.context.get("pending_user")
if not pending_user:
    return True

return not DuoDevice.objects.filter(user=pending_user, confirmed=True).exists()

Because the expression already returns whether the Password stage should run, you do not need to enable Negate Result on the policy binding.

If the Password stage binding has more than one policy attached, review its Policy engine mode carefully:

  • With only this policy attached, either mode works.
  • If multiple policies are attached, all requires every policy to pass before the Password stage runs.
  • If multiple policies are attached, any runs the Password stage when any bound policy passes.

Default authentication flow​

The built-in default-authentication-flow already includes a policy binding on its Password stage, default-authentication-flow-password-stage, which controls whether the Password stage should appear.

If you add a second policy to that same Password stage binding, set the stage binding's Policy engine mode to all so both the built-in policy and your Expression Policy must pass before the Password stage runs.

Keep Evaluate when stage is run enabled on that binding. In the default blueprint, this is already configured.