Skip to main content

Email authenticator setup stage

authentik: 2025.2.0+

The Email Authenticator Setup stage registers an email-based authenticator for the current user, enabling one-time codes to be sent via email during subsequent authentications.

Overview​

During enrollment, the user supplies an email address if one is not already known, then confirms ownership by entering a one-time code.

The enrolled email address can later be used with the Authenticator Validation stage.

Configuration options​

  • Use global connection settings: use authentik's global email configuration instead of stage-specific SMTP settings.
  • SMTP host: SMTP server hostname for stage-specific email delivery.
  • SMTP port: SMTP server port.
  • SMTP username: optional SMTP username.
  • SMTP password: optional SMTP password.
  • Use TLS: enable STARTTLS for the SMTP connection.
  • Use SSL: enable SMTPS for the SMTP connection.
  • Timeout: SMTP connection timeout in seconds.
  • From address: sender address used for enrollment emails.
  • Token expiry: how long the one-time code stays valid.
  • Subject: subject line for the enrollment email.
  • Template: email template used for the one-time code email. See Custom templates below.
  • Authenticator type name: optional friendly name shown to the user in self-service settings.
  • Configuration flow: optional authenticated flow that lets users enroll this authenticator from user settings.

For SMTP requirements and global email delivery settings, see Email configuration.

Custom templates​

This stage supports custom email templates in the same way as the Email stage. Mount your custom templates into authentik's template directory, and they will appear in the stage's Template dropdown.

For the full mounting instructions (Docker Compose and Kubernetes), a list of available template variables, and an example template, see Custom templates in the Email stage documentation.

info

If a custom template does not appear in the Template selector, check the worker container logs. Templates are discovered when the stage configuration form loads.

Flow integration​

Use this stage in an enrollment or user-settings flow where the user should add an email authenticator.

To use the enrolled address during login, add an Authenticator Validation stage to the authentication flow and allow the Email device class.

Notes​

  • If Use global connection settings is enabled, configure the global email settings first. See the installation docs for Docker Compose and Kubernetes.
  • This stage is separate from the general-purpose Email stage, which is used for email verification and recovery.
  • If the user already has an email address on their account, authentik can use that address during enrollment instead of prompting for a new address.