MFA Workflow

The MFA Workflow enables your application to require users to verify their identity using a second factor after successfully authenticating with their primary login factor. It consists of two distinct flows:

• MFA Enrollment: A user sets up their authenticator app for the first time
• MFA Challenge: An already-enrolled user is prompted to enter a verification code during login.

Both flows apply only to users authenticating through the Wristband Identity Provider. Users authenticating via external identity providers are subject to their own provider's MFA enforcement.

---

MFA Enrollment

MFA Enrollment is the process by which a user registers a Time-Based One-Time Password (TOTP) authenticator app with their account, such as Google Authenticator or Authy. Upon completing enrollment, the user is also issued a recovery code if recovery codes are enabled in your MFA policy.

Required Enrollment

When MFA enrollment is set to Required in your MFA policy, the following Wristband flows will automatically prompt users to enroll (if they haven’t already):

• User invite
• Password reset (if immediate login is enabled)
• Login
• Signup

At the API level, the following APIs can return an MFA_ENROLLMENT_REQUIRED status for users who have not yet enrolled:

• Accept New User Invite
• Accept Existing User Invite
• Activate User
• Verify Password for Login
• Reset Password
• Provision Wristband IdP User on Signup
• Verify Magic Link

How your application handles this status depends on your UI approach:

• Wristband-Hosted UI: Wristband automatically redirects the user to the tenant-level MFA enrollment page (e.g. https://tenant1-yourapp-yourcompany.us.wristband.dev/mfa/enroll).
• Self-Hosted UI: Your application is responsible for handling the MFA_ENROLLMENT_REQUIRED status and directing the user to your own enrollment page or flow. The route and presentation are entirely up to you.

Optional Enrollment

When MFA enrollment is set to Optional, enrollment is not triggered automatically. To support self-enrollment, expose that ability in your own UI and call the following APIs:

• Enroll TOTP Auth Factor
• Enroll Recovery Code Auth Factor

Enrollment Pages

When a user is prompted to enroll, they are presented with an enrollment page displaying a QR code to scan with their authenticator app.

If the user is unable to scan the QR code, they can reveal the raw secret key to enter manually into their authenticator app.

After successfully verifying a TOTP code, users with recovery codes enabled are shown their recovery code and prompted to save it before continuing.

ℹ️

Note: Any previous recovery codes are invalidated when a new one is generated.

---

MFA Challenge

When a user who has already enrolled in MFA successfully authenticates with their primary login factor, Wristband issues an MFA challenge requiring them to enter a verification code before an authentication session is created. The user can enter either a valid TOTP code from their authenticator app or, if recovery codes are enabled in your MFA policy, their recovery code. The user has 10 minutes to complete the challenge. Clicking Cancel returns them to the tenant login page.

If the user uses their recovery code to complete the challenge, it is immediately invalidated. The user will then be prompted to save a newly-generated recovery code before continuing.

TOTP Code

By default, the challenge page prompts the user to enter the one-time code generated by their authenticator app. Upon entering a valid code, an authentication session is created and the user is redirected into your application.

Recovery Code

If recovery codes are enabled, a Use Recovery Code link is available on the TOTP challenge page to switch to that method instead. If the user clicks it, the page switches to a recovery code input. A Use One-Time Code link is available to switch back. If recovery codes are not enabled in your MFA policy, this option will not appear.

Upon entering a valid recovery code, it is immediately invalidated and an authentication session is created. The user is then shown a new recovery code and prompted to save it before continuing into the application.