用于多因素认证 (MFA) 的短信验证
Logto 支持基于短信的多因素认证 (MFA) 功能,通过向用户注册的手机号发送一次性验证码来增强账户安全性。短信 MFA 作为第二认证 (Authentication) 因子,可以与其他 MFA 因子(如 TOTP、通行密钥、备用码)结合,为用户提供灵活的双因素认证 (Authentication) 选项。
概念
短信验证,也称为手机号验证,是最易用的 MFA 方法之一。它利用手机的普及性,通过短信将临时的一次性验证码直接发送到用户设备。与需要额外安装软件的应用认证器不同,短信 MFA 利用每部手机都自带的消息基础设施,无需任何设置即可立即为用户提供服务。
配置用于 MFA 的短信验证
步骤 1:配置短信连接器和模板
- 进入 控制台 > 连接器 > 邮箱与短信连接器
- 选择合适的短信连接器(Twilio、SMS Aero 等)
- 配置连接参数
- 使用专用用途类型设置 MFA 的短信模板
MfaVerification
用于 MFA 验证BindMFA
用于绑定 MFA
- 测试连接器功能,确保消息能正常送达
- 参考 短信连接器 获取特定服务商的设置说明
步骤 2:启用短信 MFA
- 进入 控制台 > 多因素认证 (MFA)
- 启用“短信验证码”因子。建议将短信 MFA 与其他 MFA 因子(TOTP、通行密钥、备用码)结合使用,以降低对单一因子的依赖。
- 配置你偏好的 MFA 策略(必需或可选)
- 保存配置更改
-
登录方式限制:短信验证码不能同时作为 登录方式 (1FA) 和 MFA 因子 (2FA) 使用。每个短信实现请选择一种认证 (Authentication) 流程。
-
注册方式兼容性:短信验证码可以同时用于注册方式和 MFA。Logto 会根据你选择的 MFA 策略优化终端用户注册流程,避免对同一手机号重复要求短信验证。
-
找回密码兼容性:虽然短信验证码可以同时用于 忘记密码 和 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:短信验证码 + 通行密钥 + 认证器应用 OTP + 备用码
邮箱 + 邮箱验证码 + 密码
| MFA:短信验证码 + 通行密钥 + 认证器应用 OTP + 备用码

场景 2:手机号作为注册标识符已验证
如果手机号是注册标识符,并且用户在注册时已通过短信验证码验证,系统会自动将该号码绑定为 MFA 因子——无需额外验证。
示例:
注册:手机号 + 短信验证码 + 密码
| MFA:短信验证码 + 备用码

场景 3:手机号已验证但有多个主因子
如果手机号在注册时已验证(作为注册标识符),但账户有多个主 MFA 因子(如短信加通行密钥或认证器应用),界面会提示用户“添加另一个两步验证”。用户可选择添加其他因子或跳过;提示也会明确说明已启用 MFA。
示例:
注册:手机号 + 短信验证码 + 密码
| MFA:短信验证码 + 通行密钥 + 认证器应用 OTP + 备用码
手机号 + 短信验证码 + 密码
| MFA:短信验证码 + 通行密钥 + 认证器应用 OTP + 备用码

短信 MFA 验证流程
启用短信 MFA 的用户登录时,成功完成主认证 (Authentication)(1FA)后,将被提示使用短信验证码作为第二认证 (Authentication) 因子(2FA)验证身份。
如有多个 MFA 因子,用户可从已配置的因子中选择。系统会根据 配置 MFA 中指定的优先级顺序决定优先提示哪个 MFA 因子。
示例:
登录:邮箱地址 + 密码
| MFA:短信验证码(上次使用)/ 认证器应用 OTP / 备用码
邮箱地址 + 密码
| MFA:短信验证码(上次使用)/ 认证器应用 OTP / 备用码

错误处理
-
手机号未绑定
- 错误码:
session.mfa.mfa_factor_not_enabled
- 处理方式:引导用户先绑定手机号
- 错误码:
-
验证码错误
- 错误码:
verification_code.code_mismatch
- 处理方式:提示用户重新输入,限制重试次数
- 错误码:
-
验证码已过期
- 错误码:
verification_code.expired
- 处理方式:提示用户重新获取验证码
- 错误码:
-
发送频率超限
- 错误码:
connector.rate_limit_exceeded
- 处理方式:显示等待时间,限制重新发送
- 错误码: