MFA Management
Enroll, verify, recover, administer, and integrate AuthOS TOTP multi-factor authentication
AuthOS provides a Beta TOTP-based MFA implementation based on RFC 6238. Use this guide set to enroll a factor, complete login challenges, protect recovery codes, build account-security UI, and recover access safely.
MFA combines something the user knows, such as a password, with something the user has, such as an authenticator application. AuthOS supports QR and manual TOTP enrollment, 10 single-use recovery codes, and recovery-code regeneration.
Prerequisites
Before implementing MFA:
- Install the SDK with
npm install @drmhse/sso-sdk. - Establish an authenticated user session for enrollment and management.
- Install an authenticator application for testing.
- Define and test the recovery and administrative support policy your users will rely on before enabling MFA in production.
Follow the MFA sequence
| Step | Guide | Outcome |
|---|---|---|
| 1 | Enrollment | Check status, generate a TOTP secret, and pair an authenticator application. |
| 2 | Verification | Activate MFA and complete TOTP or backup-code login challenges. |
| 3 | Backup and recovery | Store, regenerate, and use recovery codes without weakening account recovery. |
| 4 | Administration | Disable MFA deliberately and support locked-out users. |
| 5 | UI integration | Assemble the enrollment and management components into an account-security page. |
| 6 | Troubleshooting and security | Handle errors, rate limits, interoperability, and production-readiness checks. |
Checking MFA Status
Start with Enrollment to determine whether the authenticated user already has MFA enabled.
Basic Status Check
The basic SDK example moved to Enrollment.
React Component for MFA Status
The status component moved to Enrollment.
Setting Up TOTP MFA
Continue with Enrollment to generate and display the QR code and manual-entry secret.
Step 1: Generate QR Code
The setup call moved to Enrollment.
Step 2: Display QR Code to User
The complete setup component moved to Enrollment.
Verifying TOTP Code to Enable MFA
Use Verification to activate the factor and present the one-time backup codes.
Verification
The activation example moved to Verification.
Login with MFA
Use Verification to exchange the short-lived pre-authentication token for a full session.
MFA Login Flow
The basic continuation moved to Verification.
Complete Login Form with MFA Support
The MFA-aware React form moved to Verification.
Managing Backup Codes
Use Backup and recovery to regenerate, store, and consume single-use backup codes.
Regenerating Backup Codes
The regeneration flow moved to Backup and recovery.
Backup Codes Management Component
The recovery-code UI moved to Backup and recovery.
Disabling MFA
Use Administration for the consequences, confirmation UI, and support escalation path.
Disable MFA
The self-service call moved to Administration.
Disable MFA Component
The confirmation UI moved to Administration.
Complete MFA Settings Page
Use UI integration to compose status, enrollment, recovery-code, and disable controls.
Authenticator App Integration
See the authenticator application notes for QR format, manual entry, and the interoperability caveat.
Recommended Authenticator Apps
The illustrative application list moved to Enrollment.
QR Code Format
The otpauth:// format moved to Enrollment.
Manual Entry
The fallback procedure moved to Enrollment.
Recovery Flows
Follow Backup and recovery when a user loses an authenticator device or backup codes.
Lost Authenticator Device
The factor-loss flow moved to Backup and recovery.
Lost Backup Codes
The authenticated regeneration flow moved to Backup and recovery.
Backup Code Usage
The single-use login example moved to Backup and recovery.
Best Practices
Review Troubleshooting and security before enabling MFA in production.
Security Considerations
The security controls moved to Troubleshooting and security.
UX Considerations
The user-experience guidance moved to Troubleshooting and security.
Implementation Checklist
The rollout checklist moved to Troubleshooting and security.
Error Handling
Use the MFA error mapping for invalid setup state, expired codes, rate limiting, and server errors.
Next Steps
- Authentication Flows Guide — Learn about OAuth and token management.
- Password Authentication Guide — Implement password-based login.
- User API Reference — Look up MFA user operations.
Pages
MFA Enrollment
Check MFA status and enroll an AuthOS user with a TOTP authenticator application
MFA Verification
Activate a TOTP factor and complete AuthOS MFA login challenges
MFA Backup and Recovery
Protect, regenerate, and use AuthOS MFA backup codes and recover locked-out accounts
MFA Administration
Disable AuthOS MFA deliberately and support users who have lost every recovery factor
MFA UI Integration
Compose AuthOS MFA enrollment, backup-code, and disable controls into an account-security page
MFA Troubleshooting and Security
Handle AuthOS MFA errors, rate limits, recovery risks, and production-readiness checks