Authdog multi-factor authentication adds a TOTP authenticator check after primary sign-in. MFA is configured per environment and enrolled per user.
Supported factor
The current MFA challenge supports six-digit, time-based one-time passwords from standard authenticator apps. Enrollment uses an otpauth:// configuration with these parameters:
- Algorithm: SHA-1
- Digits: 6
- Period: 30 seconds
- Verification window: previous, current, or next 30-second period
Email one-time codes used by Magic Auth are a primary sign-in method, not the TOTP second factor described here. SMS, push approval, and WebAuthn security keys are not currently documented as supported MFA factors.
Enable MFA for an environment
- Open the Authdog console.
- Select the project and environment.
- Open authentication settings and enable Multi-factor authentication.
- Enroll a test user before enforcing MFA across production users.
The environment setting controls whether the sign-in flow applies the MFA gate. The user must also have an active TOTP enrollment. Keep development and production settings separate; each Authdog environment has isolated configuration and users.
MFA configuration and enrollment currently use the Authdog console and Authdog-hosted account flows. Management GraphQL operations visible in console traffic are internal APIs and are not supported for external integrations. No public REST endpoint for MFA enrollment is documented at this time.
Enroll a user
Enrollment follows a prepare-then-verify sequence:
- Authdog generates an inactive TOTP secret and ten backup codes.
- The user scans the configuration with an authenticator app.
- The user enters the current six-digit code.
- Authdog verifies the code and activates the TOTP secret and backup codes.
Do not consider enrollment complete until verification succeeds. Store the displayed backup codes in a secure password manager; treat each as an authentication secret. Authdog returns backup codes during enrollment, but the current hosted sign-in challenge accepts authenticator TOTP codes. Test the recovery process before relying on backup codes operationally.
Sign-in behavior
After successful primary authentication, Authdog can defer issuing the normal access and refresh cookies. It sets a short-lived MFA-pending state and redirects the user to the hosted MFA screen. The user enters an authenticator code; only successful verification completes sign-in and issues session cookies.
The pending state is bound to the environment and contains the original continuation details. A missing, expired, or wrong-environment state sends the user back to sign-in. Failed codes generate authentication failure activity; successful completion generates MFA sign-in activity.
Your application should not call the hosted /api/v1/mfa/verify route directly. It relies on Authdog-managed pending cookies and is part of the hosted identity flow, not a public management API.
Reset MFA for a user
If a user loses authenticator access:
- Verify their identity through a support process outside the compromised factor.
- In the console, open the user in the correct environment.
- Disable the user's MFA.
- Have the user enroll a new authenticator.
- Review audit logs for unexpected sign-ins or administrative changes.
Disabling MFA deactivates the active TOTP secret and its associated backup codes. Treat a reset as a privileged account-recovery action; limit who can perform it and retain evidence of approval.
Security and operations
- Never log TOTP secrets, QR payloads, current codes, or backup codes.
- Require TLS and use the Authdog-hosted flow so pending state stays in protected cookies.
- Keep server clocks synchronized; TOTP depends on time.
- Alert on repeated
MFA_SIGNIN_FAILUREactivity. - Test user lockout and administrator reset procedures.
- Do not describe MFA as phishing-resistant. TOTP codes can be relayed by phishing sites.
- Validate the final Authdog session on the backend; the MFA screen alone is not authorization.