跳到主要内容

用于多因素认证 (MFA) 的邮箱验证

Logto 支持基于邮箱的多因素认证 (MFA) 功能，通过向用户注册邮箱发送一次性验证码来增强账户安全性。邮箱 MFA 作为第二认证 (Authentication) 因子，可以与其他 MFA 因子（如 TOTP、通行密钥、备用码）结合，为用户提供灵活的双因素认证 (Authentication) 选项。

概念​

邮箱验证是最为普及的 MFA 方法之一。它利用邮箱账户的广泛可用性，将临时的一次性验证码直接发送到用户的邮箱收件箱。与需要额外安装软件的应用认证器不同，邮箱 MFA 利用现有的邮箱基础设施，几乎所有互联网用户都可以通过网页浏览器、邮箱客户端或移动应用访问。这使得用户无需特殊硬件或额外设置，只要拥有邮箱账户即可立即使用。

配置用于 MFA 的邮箱验证​

步骤 1：配置邮箱连接器和模板

  1. 进入 控制台 > 连接器 > 邮箱和短信连接器

  2. 选择合适的邮箱连接器（SendGrid、Mailgun 等）

  3. 配置连接参数。

  4. 为 MFA 设置 邮箱模板 并指定专用 usageType：

    • MfaVerification 用于 MFA 验证。
    • BindMFA 用于绑定 MFA。
    • 提示：Logto 邮箱服务 提供内置邮箱模板。

  5. 参考 邮箱连接器 获取不同服务商的详细配置说明

步骤 2：启用邮箱 MFA

  1. 进入 控制台 > 多因素认证 (MFA)
  2. 启用“邮箱验证码”因子。建议将邮箱 MFA 与其他 MFA 因子（TOTP、通行密钥、短信、备用码）结合使用，以降低对单一因子的依赖。
  3. 配置你偏好的 MFA 策略（必需或可选）
  4. 保存配置更改
重要使用注意事项:

  1. 登录方式限制：邮箱验证码不能同时作为 登录方式 (1FA) 和 MFA 因子 (2FA) 使用。每个邮箱实现请选择一种认证 (Authentication) 流程。

  2. 注册方式兼容性：邮箱验证码可以同时用于注册方式和 MFA。Logto 会根据你选择的 MFA 策略优化终端用户注册流程，避免对同一邮箱地址重复要求邮箱验证。

  3. 找回密码兼容性：虽然邮箱验证码可以同时用于 忘记密码 和 MFA，但不推荐这种组合。该配置会降低 MFA 的安全性，因为用户可能通过忘记密码邮箱验证重置密码，然后用新密码完成主认证 (1FA)，再用同一邮箱方式进行 MFA 验证。

邮箱 MFA 设置流程​

MFA 设置提示可能出现在用户注册期间或登录后，具体取决于你配置的 MFA 策略。用户也可以在其 账户设置页面 启用邮箱 MFA。

邮箱 MFA 设置流程受以下因素影响：

  • MFA 主因子数量：如果有多个主因子，用户需选择一个进行配置。主因子是除备用码外的 MFA 方法。
  • 启用备用码：启用后，主 MFA 因子配置完成后会自动生成备用码，并提示用户保存。
  • 注册标识符配置：如果邮箱地址作为 注册标识符 并在注册时已通过邮箱验证码验证，系统会自动将该邮箱绑定为 MFA 因子，无需再次验证。如果存在其他主因子，界面会显示“添加另一种两步验证”选项（用户可跳过），同时明确提示 MFA 已启用。
  • 已有用户数据：已有用户在登录后设置 MFA 时，需先完成主认证 (Authentication)，再进行 MFA 设置。如果账户已包含已验证的主邮箱地址，设置流程与上述注册标识符场景一致。

以下是三种常见的邮箱 MFA 绑定场景。

场景 1：邮箱地址仅用于 MFA（典型流程）​

当邮箱地址不是注册标识符，仅用于 MFA 时，按标准设置流程进行：

  • 如果只有一个邮箱 MFA 因子，直接显示该因子的设置界面。
  • 如果有多个主 MFA 因子，显示“设置 MFA”列表页，让用户选择要配置的因子。

示例：

注册：手机号 + 短信验证码 + 密码 | MFA：邮箱验证码 + 备用码
邮箱 MFA 设置流程 1-1

注册：手机号 + 短信验证码 + 密码 | MFA：邮箱验证码 + 通行密钥 + 认证器应用 OTP + 备用码

邮箱 MFA 设置流程 1-2

场景 2：邮箱作为注册标识符已验证​

如果邮箱地址是注册标识符，并且用户在注册时已通过邮箱验证码验证，系统会自动将该邮箱绑定为 MFA 因子——无需额外验证。

示例：

注册：邮箱地址 + 邮箱验证码 + 密码 | MFA：邮箱验证码 + 备用码
邮箱 MFA 设置流程 2

场景 3：邮箱已验证但有多个主因子​

如果邮箱地址在注册时已验证（作为注册标识符），但账户有多个主 MFA 因子（如邮箱加通行密钥或认证器应用），界面会提示用户“添加另一种两步验证”。用户可以选择添加其他因子或跳过；该提示也会明确告知 MFA 已启用。

示例：

注册：邮箱地址 + 邮箱验证码 + 密码 | MFA：邮箱验证码 + 通行密钥 + 认证器应用 OTP + 备用码

邮箱 MFA 设置流程 3

邮箱 MFA 验证流程​

启用邮箱 MFA 的用户登录时，在成功完成主认证 (1FA) 后，会被提示使用邮箱验证码作为第二认证 (Authentication) 因子 (2FA) 验证身份。

如果有多个 MFA 因子可用，用户可以从已配置的因子中选择。系统会根据 配置 MFA 中指定的优先级顺序决定优先提示哪个 MFA 因子。

示例：

登录：手机号 + 密码 | MFA：邮箱验证码（上次使用） / 认证器应用 OTP / 备用码
邮箱 MFA 验证流程

错误处理​

  1. 邮箱地址未绑定

    • 错误码：session.mfa.mfa_factor_not_enabled
    • 处理方式：引导用户先绑定邮箱地址

  2. 验证码错误

    • 错误码：verification_code.code_mismatch
    • 处理方式：提示用户重新输入，限制重试次数

  3. 验证码已过期

    • 错误码：verification_code.expired
    • 处理方式：提示用户重新获取验证码

  4. 发送频率超限

    • 错误码：connector.rate_limit_exceeded
    • 处理方式：显示等待时间，限制重新发送