Spring Boot 3.x 落地 MFA 的核心是保障流程稳、准、可运维：需自定义 AuthenticationSuccessHandler 拦截跳转、用 Redis 存储带 TTL 的 MFA 会话状态、抽象 MfaVerificationService 统一管理多因子、改造 RememberMeServices 防绕过、安全生成与审计备份码并实现设备信任机制。
在 Spring Boot 3.x 环境中落地多因素认证（MFA），不是加个依赖、配几个类就能跑通的事。真正卡住团队的，是那些流程断点难定位、状态丢失无痕迹、多种因子混用时逻辑打架的问题。核心不在“有没有 MFA”，而在“MFA 能不能稳、准、可运维”。
认证流程中断：密码通过后不跳 MFA 页面
这是最常见却最容易误判的问题。表面看是前端没跳转，实则根因在 Spring Security 6.x 的认证模型已从“单次完成”转向“分阶段委托”。默认 UsernamePasswordAuthenticationFilter 在成功后直接调用 SecurityContextRepository.save()，中间态被跳过。
- 必须自定义 AuthenticationSuccessHandler，在此处拦截并判断用户是否已启用 MFA，未完成则重定向至 /mfa/challenge，同时将原始认证对象存入 HttpSession 或 Redis（带 TTL）
- 禁用默认的 SavedRequestAwareAuthenticationSuccessHandler，它会优先跳转到 saved request，覆盖 MFA 流程
- 确保 /mfa/** 路径在 HttpSecurity 中被明确配置为 permitAll，且不被其他 filter 预先拦截
用户中间状态丢失：HTTP 无状态下如何记住“已过第一因子”
JWT 场景下尤其棘手——Token 一旦签发就不可变，无法动态追加 MFA 完成标记；Session 场景下又怕节点漂移导致状态不一致。
- 推荐方案：引入轻量级 MFA Session Store，用 Redis 存储 {mfa_session_id: {userId, firstFactorTime, mfaMethod, challengeId}}，有效期设为 5–10 分钟，与前端倒计时同步
- 避免把 MFA 状态塞进 JWT 主体，否则每次验证都要重新签发 Token，破坏无状态性；也不建议用 Cookie 存 session ID，易被 XSS/CSRF 利用
- 每次 MFA 请求（如校验 TOTP）必须携带该 mfa_session_id，并做服务端校验：是否存在、是否超时、是否归属当前用户
多种因子混用时逻辑混乱：TOTP、短信、邮件怎么统一管理
不同因子验证方式差异大：TOTP 是时间+密钥哈希，短信/邮件是随机码+时效+次数限制，硬件令牌甚至需要外部 PKI 交互。硬编码 if-else 必然失控。
- 抽象出 MfaVerificationService 接口，定义 verify(String sessionId, String code) 和 sendChallenge(String userId, String method) 两个核心方法
- 按 method 类型注册不同实现：TotpMfaService、SmsMfaService、EmailMfaService，用 Spring 的 @Qualifier 或策略模式路由
- 用户选择因子的动作要落库（如 user_mfa_preferences 表），包含 method、绑定时间、是否启用、最后使用时间；禁用某因子时需主动失效其关联的密钥或手机号
“记住我”与 MFA 冲突：Remember-Me 绕过第二因子
Remember-Me Cookie 恢复的是完整 Authentication，若该 Authentication 已含 Authorities，Spring Security 就不会再触发 MFA 流程。
- 关键改造：自定义 RememberMeServices，重写 autoLogin 方法，在构建 RememberMeAuthenticationToken 前，强制检查用户是否启用了 MFA；若启用，则返回 null 或抛出 MfaRequiredException，交由异常处理器跳转至 MFA 页面
- Remember-Me Token 本身不应代表“完全可信”，而应视为“可信任的第一因子凭证”，第二因子仍需每次会话独立验证
- 对已登录用户启用 MFA 后，需立即使所有现存 Remember-Me Token 失效（清空 persistent_logins 表对应记录）
备份码与设备信任机制：既要安全又要可用
备份码不是随便生成一串数字存数据库就行。它是一次性、强绑定、可审计的安全凭证。
- 备份码生成：用 SecureRandom 生成 16 位字母+数字组合（避免 0/O/1/l），每用户预生成 10 条，SHA-256 加盐哈希后入库，明文仅返回给用户一次（前端展示后即销毁）
- 设备信任：用 HTTP User-Agent + IP 段（非精确 IP）+ 设备指纹（Canvas/WebGL Hash）生成设备标识，存入 trusted_devices 表；启用“信任此设备”需用户二次确认（如输入 MFA 码），且信任有效期最长 30 天
- 所有备份码使用后立即标记 used = true，并记录使用时间与 IP；同一备份码重复使用应触发告警
不复杂但容易忽略。
