Authdog multi-factor authentication adds a TOTP authenticator check after primary sign-in. MFA is configured per environment and enrolled per user.
Supported factor
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 Authdog console.
- Select project and environment.
- Open authentication settings and enable Multi-factor authentication.
- Enroll test user before enforcing MFA across production users.
Environment setting controls whether sign-in flow applies MFA gate. User must also have active TOTP enrollment. Keep development and production settings separate; each Authdog environment has isolated configuration and users.
MFA configuration and enrollment currently use 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 inactive TOTP secret and ten backup codes.
- User scans configuration with authenticator app.
- User enters current six-digit code.
- Authdog verifies code and activates TOTP secret and backup codes.
Do not consider enrollment complete until verification succeeds. Store displayed backup codes in secure password manager; treat each as authentication secret. Authdog returns backup codes during enrollment, but current hosted sign-in challenge accepts authenticator TOTP codes. Test recovery process before relying on backup codes operationally.
Sign-in behavior
After successful primary authentication, Authdog can defer issuing normal access and refresh cookies. It sets short-lived MFA-pending state and redirects user to hosted MFA screen. User enters authenticator code; only successful verification completes sign-in and issues session cookies.
Pending state is bound to environment and contains original continuation details. Missing, expired, or wrong-environment state sends user back to sign-in. Failed codes generate authentication failure activity; successful completion generates MFA sign-in activity.
Your application should not call hosted /api/v1/mfa/verify route directly. It relies on Authdog-managed pending cookies and is part of hosted identity flow, not public management API.
Reset MFA for a user
If user loses authenticator access:
- Verify identity through support process outside compromised factor.
- In console, open user in correct environment.
- Disable user's MFA.
- Have user enroll new authenticator.
- Review audit logs for unexpected sign-ins or administrative changes.
Disabling MFA deactivates active TOTP secret and associated backup codes. Treat reset as 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 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 final Authdog session on backend; MFA screen alone is not authorization.