Multi-Factor Authentication (MFA)
MFA adds verification to a supported login or step-up flow. Choose the tenant’s login method, enrollment policy and recovery process together; an enabled setting alone does not prove that every application performs the required challenge.
A pending step-up credential is not a completed application session. Do not grant access until the challenge completes and the application receives the appropriate authenticated credential. SMS 2FA is unavailable while magic-link login is enabled.
TOTP (Authenticator App)
TOTP uses a shared secret and a time-based code. Enroll through the user’s authenticated account settings, scan the displayed secret with an authenticator and confirm a generated code before considering enrollment complete.
The current API uses the authenticator route family:
| Request | Purpose |
|---|---|
GET /api/user/2fa/authenticator | Read authenticator state |
GET /api/user/2fa/authenticator/setup | Obtain enrollment information in the authenticated user context |
POST /api/user/2fa/authenticator | Complete the supported enrollment action |
DELETE /api/user/2fa/authenticator | Request removal through the authenticated settings flow |
These are not /api/user/2fa/totp/* endpoints. Follow the UI’s enrollment sequence; do not log the secret or QR-code payload.
Recovery codes
Keep recovery material outside the device used for the second factor. Test the deployed recovery flow with a dedicated test account and verify that used codes cannot be reused. Do not assume a particular number of recovery codes from an older screenshot or guide.
SMS OTP
SMS requires a configured delivery provider, tenant support and a verified phone. The service uses six-digit codes with a five-minute lifetime, a 30-second resend cooldown and a five-attempt limit per code.
Phone enrollment starts at POST /api/user/phone/set, followed by POST /api/user/phone/verify. Enabling SMS 2FA uses POST /api/user/2fa/sms/enable; it returns 409 SMS_2FA_UNAVAILABLE when magic-link login is enabled. Read the SMS OTP guide for the exact sequence and response handling.
WebAuthn / Passkeys
Use the passkey enrollment guide for the browser’s registration and authentication ceremonies. A passkey requires a supported browser and authenticator, and the relying-party configuration must match the deployed origin.
Test the actual devices your users have, including recovery after a device is lost. Enabling a factor flag does not create a WebAuthn credential.
Step-Up Authentication
Prefer hosted login to reconstructing challenge handling in each application. The hosted flow carries the pending state through verification. Verify the issued credential again at your API and apply tenant/resource authorization independently.
For an RS256 bearer-token API, the runnable verification example includes valid and invalid signed fixtures. It does not validate MFA assurance or DPoP proofs; those require the corresponding policy checks.
Console Configuration
- Choose the primary login method in a test tenant.
- Enroll a permitted second factor with a dedicated test user.
- Test successful verification, wrong codes, expiry, replay, recovery and an unenrolled user.
- Verify that pending credentials fail at protected application routes.
- Test lost-device recovery and administrative access before enforcing the policy for everyone.
Adaptive MFA (Risk-Based)
Risk-based policies depend on the configured evaluation and challenge flow. Do not assume fixed risk thresholds, automatic factor combinations or particular acr/amr claims from a generic integration guide. Validate the effective policy and tokens for your application before treating them as evidence of a required assurance level.
Next step
Review authentication settings or request an Auris integration demo using your enrollment, recovery and access-control requirements.