Email verification for MFA

Logto supports email-based multi-factor authentication (MFA) functionality that enhances account security by sending one-time verification codes to users' registered email addresses. Email 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

Email verification is one of the most universally accessible MFA methods. It leverages the widespread availability of email accounts to deliver temporary, one-time verification codes directly to users' email inboxes. Unlike app-based authenticators that require additional software installation, email MFA utilizes existing email infrastructure that is already accessible to virtually all internet users through web browsers, email clients, or mobile apps. This makes it immediately available to users without any special hardware requirements or additional setup beyond having an email account.

Configure email verification for MFA

Step 1: Configure email connector and templates

1. Navigate to Console > Connectors > Email and SMS connectors

2. Select an appropriate email connector (SendGrid, Mailgun, etc.)

3. Configure connection parameters.

4. Set up the email template for MFA with the dedicated usage types:

   • MfaVerification usageType for verifying MFA.
   • BindMFA usageType for binding MFA.
   • Tips: Logto Email Service provides build-in email templates.

5. Refer to Email connectors for provider-specific setup instructions

Step 2: Enable email for MFA

1. Navigate to Console > Multi-factor authentication
2. Enable the "Email verification code" factor. Recommend to use email MFA in combination with other MFA factors (TOTP, passkeys, SMS, 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: Email verification codes cannot be used simultaneously as both a sign-in method (1FA) and an MFA factor (2FA). Choose one authentication flow per email implementation.

2. Sign-up method compatibility: Email 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 email verification twice for the same email address.

3. Password recovery compatibility: While email 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 email verification to reset their password, then use the new password for primary authentication (1FA) followed by the same email method for MFA verification.

Email 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 email MFA from their Account settings page.

The email 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 email address was used as the sign-up identifier and the user already verified it with an email verification code during registration, the system will automatically bind that email 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 email address, the setup behaves the same way as the sign-up identifier case above.

Below are three common email MFA binding scenarios.

Scenario 1: Email address only used for MFA (Typical flow)

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

• If there is only one email 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: Phone number + SMS verification code + Password | MFA: Email verification code + Backup codes

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

Scenario 2: Email verified as the sign-up identifier

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

Examples:

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

Scenario 3: Email verified but multiple primary factors available

If the email address was verified at sign-up (as the sign-up identifier) but the account has multiple primary MFA factors (e.g., email 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: Email address + Email verification code + Password | MFA: Email verification code + Passkeys + Authenticator app OTP + Backup codes

Email MFA verification flows

When a user with email MFA enabled signs in, after successfully completing primary authentication (1FA), they will be prompted to verify their identity using the email 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: Phone number + Password | MFA: Email verification code (last time used) / Authenticator app OTP / Backup codes

Error Handling

1. Email address not bound

   • Error code: session.mfa.mfa_factor_not_enabled
   • Handling: Guide user to bind email address 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