Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions docs/end-user-flows/mfa/configure-mfa.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,11 @@ Follow these steps to enable MFAs in users' Logto sign-in flow:
- [Email verification](/end-user-flows/mfa/email-mfa): A widely accessible method that delivers one-time verification codes to the user's registered email address, suitable for users across all platforms and devices.
2. Backup factors:
- [Backup codes](/end-user-flows/mfa/backup-codes): This serves as a backup option when users can't verify any of the primary factors mentioned above. Enabling this option reduces friction for users' access successfully.
3. Choose if you want to enable **Require MFA**:
- **Enable**: Users will be prompted to set up MFA during the sign-in process which cannot be skipped. If the user fails to set up MFA or deletes their MFA settings, they will be locked out of their account until they set up MFA again.
- **Disable**: Users can skip the MFA setup process during the sign-up flow. They may set up MFA later through your self-service account settings page. [Learn more](/end-user-flows/account-settings/) about implementing a user account settings page. And continue to choose the policy for the MFA setup prompt:
3. Choose the **Require MFA** policy from the dropdown. This policy controls when users must complete MFA during sign-in:
- **Optional MFA**: Let users decide whether to enable MFA for their own account security. Users can skip MFA setup during sign-in and set it up later through your self-service account settings page. [Learn more](/end-user-flows/account-settings/) about implementing a user account settings page.
- **Adaptive MFA**: Apply MFA only when a sign-in appears unusual, so low-risk sign-ins can stay smoother while suspicious sign-ins get extra verification. This mode depends on your existing MFA setup (at least one MFA factor must be enabled), applies to end-user sign-in flows, and does not rely on device fingerprinting or other sensitive personal data.
- **Mandatory MFA**: Require all users to complete MFA on every sign-in. Users who have not set up MFA must complete setup before they can continue.
- When **Optional MFA** or **Adaptive MFA** is selected, configure the MFA setup prompt policy:
- **Do not ask users to set up MFA**: Users will not be prompted to set up MFA during sign-in.
- **Ask users to set up MFA during registration**: New users will be prompted to set up MFA during registration, and existing users will see the prompt at their next sign-in. Users can skip this step, and it won't appear again.
- **Ask users to set up MFA on their sign-in after registration**: New users will be prompted to set up MFA at their second sign-in after registration, and existing users will see the prompt at their next sign-in. Users can skip this step, and it won't appear again.
Expand All @@ -32,7 +34,7 @@ Follow these steps to enable MFAs in users' Logto sign-in flow:
If you need to prompt a user again after they skipped MFA enrollment, reset their skip state so the setup screen appears the next time they sign in. Admins can use the Management API (`PATCH /api/users/{userId}/logto-configs`), and developers building self-service flows can call the Account API (`PATCH /api/my-account/logto-configs`). [Management API reference](https://openapi.logto.io/operation/operation-updateuserlogtoconfigs) · [Account API reference](https://openapi.logto.io/operation/operation-updatelogtoconfig)
:::

<img src="/img/assets/configure-mfa.png" alt="MFA settings" />
<img src="/img/assets/mfa-policy.png" alt="MFA settings (policy)" />

### Organization-level MFA configuration \{#organization-level-mfa-configuration}

Expand All @@ -44,14 +46,14 @@ In the **Multi-factor authentication** section, set **MFA setup prompt for users

### MFA set-up flow \{#mfa-set-up-flow}

Once the MFA is enabled, users will be prompted to set up MFA during the sign-in and sign-up process. Users can choose to skip this setup process if and only if the Require MFA policy is disabled.
Once MFA is enabled, users may be prompted to set up MFA during sign-in and sign-up. Users can skip this setup process only when **Optional MFA** is selected in the **Require MFA** policy.

1. **Visit sign-in or sign-up page**: The user navigates to the sign-in or sign-up page.
2. **Completes sign-in or sign-up**: The user completes the identity verification process within the sign-in or sign-up flow.
3. **Set up MFA primary factor**: The user is prompted to set up their primary MFA factor (either passkey, Authenticator app OTP, SMS code, or email code).
- If multiple primary factors are enabled, they can choose their preferred option.
- If the primary factor is the same as the sign-up identifier (e.g., SMS or email), it will be pre-verified, allowing users to skip the verification step and proceed directly to the next step (e.g., "Add another one 2-step verification" or "Save your backup factors").
- If the Require MFA policy is disabled, they can also skip this step by selecting the "Skip" button.
- If **Optional MFA** is selected in the **Require MFA** policy, they can skip this step by selecting the "Skip" button.
4. **Set up MFA backup factor**: If **Backup codes** are enabled, the user is prompted to save backup codes after successfully configuring their primary authentication factor. Auto generated backup codes will be displayed to the user, which they can download and store securely. User must manually confirm the backup codes to complete the MFA setup process.

<img src="/img/assets/link-mfa.png" alt="MFA set-up flow" />
Expand Down
Binary file removed static-localized/en/img/assets/configure-mfa.png
Binary file not shown.
Binary file added static-localized/en/img/assets/mfa-policy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading