Two-Factor Authentication

auth.twoFactor enables TOTP-based two-factor authentication (time-based one-time passwords). Users add a second factor with an authenticator app (Google Authenticator, 1Password, Authy, …) and enter a rotating code at sign-in.

auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true

Enabling 2FA

The simplest form is a boolean — enable with defaults:

auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true

For control over the issuer name, backup codes, and code format, use the object form:

auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
    digits: 6
    period: 30

Configuration

auth.twoFactor accepts either a boolean or a configuration object.

Backup Codes

When backupCodes: true, users receive a set of single-use recovery codes during 2FA enrollment — essential when they lose access to their authenticator device. Delivery is customizable via the twoFactorBackupCodes email template:

auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
  emailTemplates:
    twoFactorBackupCodes:
      subject: Your MyApp recovery codes
      text: 'Keep these recovery codes safe: $code'

Enrollment Flow

1. The user signs in with email and password as usual.
2. They enroll in 2FA — the app shows a TOTP secret (typically as a QR code) labeled with issuer.
3. They scan it into an authenticator app, which begins generating codes every period seconds.
4. On subsequent sign-ins, after the password step they enter the current digits-length code.
5. If enabled, backup codes provide a recovery path when the device is unavailable.

Related Pages

• Email & Password — the strategy 2FA depends on.
• Email Templates — the twoFactorBackupCodes template.
• Sessions — sessions issued after the second factor succeeds.
• Authentication Overview — the auth block in context.