SMS verification for MFA

Logto supports SMS-based multi-factor authentication (MFA) functionality that enhances account security by sending one-time verification codes to users' registered phone numbers. SMS MFA serves as a second authentication factor and can be combined with other MFA factors (such as TOTP, passkeys, backup codes) to provide users with flexible two-factor authentication options.

Concepts

SMS verification, also referred to as Phone Number verification, is one of the most accessible MFA methods. It leverages the ubiquity of mobile phones to deliver temporary, one-time verification codes directly to users' devices via text messages. Unlike app-based authenticators that require additional software installation, SMS MFA utilizes the existing messaging infrastructure that comes standard with every mobile device, making it immediately available to users without any setup requirements.

Configure SMS verification for MFA

Step 1: Configure SMS connector and templates

1. Navigate to Console > Connectors > Email and SMS connectors
2. Select an appropriate SMS connector (Twilio, SMS Aero, etc.)
3. Configure connection parameters.
4. Set up the SMS template for MFA with the dedicated usage types.
   • MfaVerification usageType for verifying MFA.
   • BindMFA usageType for binding MFA.
5. Test the connector functionality to ensure proper message delivery
6. Refer to SMS connectors for provider-specific setup instructions

Step 2: Enable SMS for MFA

1. Navigate to Console > Multi-factor authentication
2. Enable the "SMS verification code" factor. Recommend to use SMS MFA in combination with other MFA factors (TOTP, passkeys, backup codes) to reduce single-factor dependency.
3. Configure your preferred MFA policy (required vs. optional)
4. Save your configuration changes

Important usage considerations:

1. Sign-in method limitation: SMS verification codes cannot be used simultaneously as both a sign-in method (1FA) and an MFA factor (2FA). Choose one authentication flow per SMS implementation.

2. Sign-up method compatibility: SMS verification codes can be used simultaneously for both sign-up method and MFA. Logto will optimize the end-user registration flow based on your selected MFA policy to avoid requiring SMS verification twice for the same phone number.

3. Password recovery compatibility: While SMS verification codes can be used simultaneously for both Forgot password and MFA, this combination is not recommended. This configuration reduces MFA security effectiveness, as users could potentially bypass MFA by using forgot password SMS verification to reset their password, then use the new password for primary authentication (1FA) followed by the same SMS method for MFA verification.

SMS MFA setup flows

The MFA setup prompt can appear during user registration or after sign-in, depending on your configured MFA policy. Users may also enable SMS MFA from their Account settings page.

The SMS MFA setup flow is affected by the following factors:

• Number of MFA primary factors: If there are multiple primary factors, the user must choose one to configure. Primary factors are MFA methods other than backup codes.
• Backup codes enabled: When enabled, backup codes are generated automatically after the primary MFA factor is configured; the user is prompted to save them.
• Sign-up identifier configuration: If the phone number was used as the sign-up identifier and the user already verified it with an SMS verification code during registration, the system will automatically bind that number as an MFA factor and no further verification is required. If other primary factors exist, the UI will surface an “Add another 2-step verification” option (the user may skip it), which also clearly indicates that MFA is enabled.
• Existing user data: When an existing user sets up MFA after signing in, they must first complete primary authentication and then proceed with MFA setup. If the account already contains a verified primary phone number, the setup behaves the same way as the sign-up identifier case above.

Below are three common SMS MFA binding scenarios.

Scenario 1: Phone number only used for MFA (Typical flow)

When the phone number is not one of the sign-up identifiers, and only for MFA, follow the standard setup sequence:

• If there is only one SMS MFA factor, show the setup UI for that factor directly.
• If there are multiple primary MFA factors, show a "Set up MFA" list page and let the user choose which factor to configure.

Examples:

Sign-up: Email + Email verification code + Password | MFA: SMS verification code + Backup codes

Sign-up: Email + Email verification code + Password | MFA: SMS verification code + Passkeys + Authenticator app OTP + Backup codes

Scenario 2: Phone verified as the sign-up identifier

If the phone number is the sign-up identifier and the user has already verified it with an SMS code during registration, the system will auto-bind that number as an MFA factor — no additional verification is needed.

Examples:

Sign-up: Phone number + SMS verification code + Password | MFA: SMS verification code + Backup codes

Scenario 3: Phone verified but multiple primary factors available

If the phone number was verified at sign-up (as the sign-up identifier) but the account has multiple primary MFA factors (e.g., SMS plus passkeys or authenticator apps), the UI will prompt the user with “Add another 2-step verification”. The user may choose to add another factor or skip; the prompt also communicates that MFA is already enabled.

Examples:

Sign-up: Phone number + SMS verification code + Password | MFA: SMS verification code + Passkeys + Authenticator app OTP + Backup codes

SMS MFA verification flows

When a user with SMS MFA enabled signs in, after successfully completing primary authentication (1FA), they will be prompted to verify their identity using the SMS verification code as the second authentication factor (2FA).

If multiple MFA factors are available, users can select from their configured factors. The system determines which MFA factor to prompt first based on the priority order specified in Configure MFA.

Examples:

Sign-in: Email address + Password | MFA: SMS verification code (last time used) / Authenticator app OTP / Backup codes

Error Handling

1. Phone number not bound

   • Error code: session.mfa.mfa_factor_not_enabled
   • Handling: Guide user to bind phone number first

2. Incorrect verification code

   • Error code: verification_code.code_mismatch
   • Handling: Prompt user to re-enter, limit retry attempts

3. Verification code expired

   • Error code: verification_code.expired
   • Handling: Prompt user to request new verification code

4. Sending rate limit exceeded

   • Error code: connector.rate_limit_exceeded
   • Handling: Show wait time, limit resending