Skip to content
Autentico

Multi-Factor Authentication

When require_mfa is true, all users must complete an MFA step after password authentication before an authorization code is issued.

MFA flow

Section titled “MFA flow”
sequenceDiagram
    actor User
    participant Browser
    participant IdP as Autentico

    User->>Browser: Enter username + password
    Browser->>IdP: POST /oauth2/login
    IdP->>IdP: Credentials valid — create MFA challenge
    IdP->>Browser: 302 → /oauth2/mfa?challenge_id=X
    Browser->>IdP: GET /oauth2/mfa (render MFA page)
    IdP->>Browser: Show TOTP input (or send email OTP)
    User->>Browser: Enter OTP code
    Browser->>IdP: POST /oauth2/mfa (code + challenge_id)
    IdP->>IdP: Validate OTP — mark challenge used
    IdP->>Browser: 302 → redirect_uri?code=AUTH_CODE

The MFA challenge is a short-lived, single-use token (5 minutes). If it expires, the user is redirected back to the login page.

TOTP (Authenticator App)

Section titled “TOTP (Authenticator App)”

TOTP uses time-based one-time passwords compatible with any RFC 6238 authenticator app — Google Authenticator, Authy, 1Password, Bitwarden, and others.

Enrollment happens automatically on first login after MFA is enabled. Users who have not yet set up TOTP are shown a QR code on the MFA page:

  1. Scan the QR code with an authenticator app
  2. Enter the 6-digit code from the app to confirm enrollment
  3. On all future logins, enter the code from the app

The TOTP secret is stored per-user in the database. The QR code is generated server-side — no third-party service is involved.

Issuer name displayed in the authenticator app comes from the theme_title setting.

Email OTP

Section titled “Email OTP”

Email OTP sends a one-time code to the user’s registered email address on each login. No enrollment step is required.

To use email OTP, set:

mfa_method = email

And configure SMTP:

smtp_host = smtp.example.com
smtp_port = 587
smtp_username = [email protected]
smtp_password = your-smtp-password
smtp_from = [email protected]

Enabling MFA

Section titled “Enabling MFA”

In the Admin UI: Settings → set require_mfa to true and choose mfa_method.

Via API:

Terminal window
curl -X PUT https://auth.example.com/admin/api/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"require_mfa": "true", "mfa_method": "totp"}'

Trusted devices

Section titled “Trusted devices”

After a successful MFA verification, users can check “Trust this device” to skip MFA on future logins from the same browser. See Trusted Devices for MFA bypass on recognized devices.