MFA: Self-Hosted UI

If you intend to self-host the MFA pages, you can either host a dedicated URL route for your MFA enrollment and challenge pages (e.g. /mfa/enroll, /mfa/challenge), or you can handle MFA inline within your existing flow's page by rendering different screens after primary factor authentication (e.g. staying on /login and swapping to an MFA screen).

MFA Enrollment

The MFA enrollment flow varies depending on whether recovery codes are enabled in your MFA policy.

Recovery Codes Disabled

Regardless of which flow triggered enrollment, the sequence is as follows at a high level:

1. The prior flow calls the relevant Wristband Authenticate API (depending on the primary auth factor used).
2. The user is redirected to your application's self-hosted MFA Enrollment Page, along with an MFA token in the query params.
3. Your application calls the Introspect MFA Enrollment Token API to validate the token and retrieve context about the current user.
4. If the user has not yet enrolled a TOTP factor, your application calls the Enroll TOTP Auth Factor API to generate the QR code and secret key before rendering the page.
5. The user scans the QR code with their authenticator app and enters the one-time code. Your application calls the Verify TOTP Auth Factor Challenge API.
6. Your application calls the Verify MFA Enrollment API, passing along the MFA token.
7. Your application redirects the user to the Create Auth Session for MFA Enrollment API, which creates a Wristband Authentication Session for the user.
8. The user then gets redirected to the appropriate location based on what triggered the MFA enrollment flow. The redirect URL resolves in the following order:
   1. If an OAuth 2 authorization request triggered the MFA enrollment flow, the redirect URI specified in the request is returned.
   2. If the MFA enrollment flow was triggered by a workflow with a custom redirect URL configured, the custom redirect URL is returned.
   3. If a client ID was passed to the request that triggers the MFA enrollment flow and a client login URL is defined, the client's login URL is returned.
   4. Otherwise, the application login URL is returned.

Because Wristband already created an Authentication Session for the user during MFA enrollment, the user gains immediate entry into the application without having to re-enter their credentials.

Recovery Codes Enabled

Regardless of which flow triggered enrollment, the sequence is as follows at a high level:

1. The prior flow calls the relevant Wristband Authenticate API (depending on the primary auth factor used).
2. The user is redirected to your application's self-hosted MFA Enrollment Page, along with an MFA token in the query params.
3. Your application calls the Introspect MFA Enrollment Token API to validate the token and retrieve the user context.
4. If the user has not yet enrolled a TOTP factor, your application calls the Enroll TOTP Auth Factor API to generate the QR code and secret key before rendering the page. If the user does not yet have a recovery code, one is also generated at this time.
5. The user scans the QR code with their authenticator app and enters the one-time code. Your application calls the Verify TOTP Auth Factor Challenge API.
6. The user is shown their recovery code and prompted to save it before continuing.
7. Your application calls the Verify MFA Enrollment API, passing along the MFA token.
8. Your application redirects the user to the Create Auth Session for MFA Enrollment API, which creates a Wristband Authentication Session for the user.
9. The user then gets redirected to the appropriate location based on what triggered the MFA enrollment flow. The redirect URL resolves in the following order:
   1. If an OAuth 2 authorization request triggered the MFA enrollment flow, the redirect URI specified in the request is returned.
   2. If the MFA enrollment flow was triggered by a workflow with a custom redirect URL configured, the custom redirect URL is returned.
   3. If a client ID was passed to the request that triggers the MFA enrollment flow and a client login URL is defined, the client's login URL is returned.
   4. Otherwise, the application login URL is returned.

Because Wristband already created an Authentication Session for the user during MFA enrollment, the user gains immediate entry into the application without having to re-enter their credentials.

---

MFA Challenge

When a user who has already enrolled in MFA successfully authenticates with their primary login factor, your application handles the MFA challenge flow.

Using TOTP

Regardless of which flow triggered the challenge, the sequence is as follows at a high level:

1. The prior flow calls the relevant Wristband Authenticate API (depending on the primary auth factor used).
2. The user is redirected to your application's self-hosted MFA Challenge Page, along with an MFA token in the query params.
3. Your application calls the Introspect MFA Challenge Token API to validate the token and retrieve the user context before rendering the page.
4. The user enters the one-time code generated by their authenticator app. Your application calls the Verify MFA Challenge API, passing TOTP as the authFactorType, which returns a redirectUrl upon success.
5. Your application redirects the user to the Create Auth Session for MFA Challenge API using the redirectUrl from the previous step, which creates a Wristband Authentication Session for the user.
6. The user then gets redirected to the appropriate location based on what triggered the MFA challenge flow. The redirect URL resolves in the following order:
   1. If an OAuth 2 authorization request triggered the MFA challenge flow, the redirect URI specified in the request is returned.
   2. If the MFA challenge flow was triggered by a workflow with a custom redirect URL configured, the custom redirect URL is returned.
   3. If a client ID was passed to the request that triggers the MFA challenge flow and a client login URL is defined, the client's login URL is returned.
   4. Otherwise, the application login URL is returned.

Because Wristband already created an Authentication Session for the user during the MFA challenge, the user gains immediate entry into the application without having to re-enter their credentials.

Using Recovery Code

Regardless of which flow triggered the challenge, the sequence is as follows at a high level:

1. The prior flow calls the relevant Wristband Authenticate API (depending on the primary auth factor used).
2. The user is redirected to your application's self-hosted MFA Challenge Page, along with an MFA token in the query params.
3. Your application calls the Introspect MFA Challenge Token API to validate the token and retrieve the user context before rendering the page.
4. The user enters their saved recovery code. Your application calls the Verify MFA Challenge API, passing RECOVERY_CODE as the authFactorType, which returns a redirectUrl upon success. The old code is invalidated and a newly generated recovery code is returned in the same response.
5. The user is shown their new recovery code and prompted to save it before continuing.
6. Your application redirects the user to the Create Auth Session for MFA Challenge API using the redirectUrl from step 4, which creates a Wristband Authentication Session for the user.
7. The user then gets redirected to the appropriate location based on what triggered the MFA challenge flow. The redirect URL resolves in the following order:
   1. If an OAuth 2 authorization request triggered the MFA challenge flow, the redirect URI specified in the request is returned.
   2. If the MFA challenge flow was triggered by a workflow with a custom redirect URL configured, the custom redirect URL is returned.
   3. If a client ID was passed to the request that triggers the MFA challenge flow and a client login URL is defined, the client's login URL is returned.
   4. Otherwise, the application login URL is returned.

Because Wristband already created an Authentication Session for the user during the MFA challenge, the user gains immediate entry into the application without having to re-enter their credentials.