SpringBoot中使用TOTP实现MFA（多因素认证）

一、MFA简介

定义：多因素认证（MFA）要求用户在登录时提供​​至少两种不同类别​​的身份验证因子，以提升账户安全性

核心目标：解决单一密码认证的脆弱性（如暴力破解、钓鱼攻击），将账户被盗风险降低​​80%以上；通过组合不同的验证因素，MFA 能够显著降低因密码泄露带来的风险

二、核心原理

MFA通过多步骤验证构建安全屏障：

1. ​​初始验证​​：用户输入用户名和密码（知识因子）
2. ​​二次验证​​：系统要求额外因子（如手机接收OTP码、指纹扫描）
3. ​​动态授权​​：高风险操作（如转账）可触发更多验证（如硬件令牌+生物识别）
4. ​​访问控制​​：所有因子验证通过后，授予最小必要权限

​​安全增强逻辑​​：

• 攻击者即使破解密码（知识因子），仍需突破所有权或生物因子，难度呈指数级增长
• 例如：钓鱼攻击中窃取密码后，因无法获取动态令牌或生物特征而失败

三、主流技术方案与对比

四、TOTP简介

1. 基于时间的一次性密码，动态验证码每30秒更新，基于共享密钥（Secret Key）和当前时间戳通过HMAC-SHA1算法生成6位数字。
2. 优势​​：离线可用、无需短信成本、兼容Google Authenticator等标准应用

五、SpringBoot集成TOTP

a.登录流程图（这里原系统使用 SA-Token，其他逻辑应该也大差不差）

b.代码实现

1.添加Maven依赖

　　　　<dependency> <groupId>com.warrenstrange</groupId> <artifactId>googleauth</artifactId> <version>1.5.0</version> </dependency> <dependency> <groupId>commons-net</groupId> <artifactId>commons-net</artifactId> <version>3.9.0</version> </dependency>

2.Mfz服务类

@Log4j2 @Service public class MfaService { @Lazy @Resource private IotUserService iotUserService; @Resource private RedisUtil redisUtil; private final GoogleAuthenticator gAuth = new GoogleAuthenticator(); /** * 为用户启用MFA，生成密钥和备用码 */ public MfaSetupResult setupMfa(String userId) { GoogleAuthenticatorKey key = gAuth.createCredentials(); String secret = key.getKey(); List<String> backupCodes = generateBackupCodes(); // 加密存储（生产环境需替换为KMS加密） String encryptedSecret = encrypt(secret); log.info(secret + "====二维码生成===" + encryptedSecret); String encryptedBackupCodes = encrypt(String.join(",", backupCodes)); IotUser user = iotUserService.getById(userId); if (user == null) { throw new RuntimeException("用户不存在"); } // 更新数据库  user.setMfaSecret(encryptedSecret); user.setBackupCodes(encryptedBackupCodes); user.setMfaEnabled(1); iotUserService.updateById(user); String qr = "otpauth://totp/" + userId + "?secret=" + secret + "&issuer=IOT_Platform" + "&image=https://iot-dev.xxxxxx.cn/static/img/logo.34793a79.png"; return new MfaSetupResult(qr, backupCodes); } /** * 生成10个备用验证码（一次性使用） */ private List<String> generateBackupCodes() { return new Random().ints(10, 100000, 999999) .mapToObj(code -> String.format("%06d", code)) .collect(Collectors.toList()); } /** * 验证TOTP或备用码 */ public boolean verifyCode(String userId, String code) { IotUser user = iotUserService.getById(userId); if (user == null) { throw new RuntimeException("用户不存在"); } // 1. 获取加密的密钥和备用码 String encryptedSecret = user.getMfaSecret(); String encryptedBackupCodes = user.getBackupCodes(); String secret = decrypt(encryptedSecret); log.info(secret + "校验" + encryptedSecret); List<String> backupCodes = new ArrayList<>( Arrays.asList(decrypt(encryptedBackupCodes).split(",")) ); // 2. 验证TOTP（允许时间偏差） if (gAuth.authorize(secret, Integer.parseInt(code))) { return true; } // 3. 验证备用码 if (backupCodes.contains(code)) { backupCodes.remove(code); // 更新数据库 user.setBackupCodes(encrypt(String.join(",", backupCodes))); iotUserService.updateById(user); return true; } return false; } /** * 开启7天免MFA认证 */ public void setMfaSkip(String userId, String userAgent, String ip) { String deviceHash = DigestUtils.sha256Hex(userAgent + ip).substring(0, 8); String key = "mfa_skip:" + userId + ":" + deviceHash; long expireAt = System.currentTimeMillis() + 7 * 86_400_000L; String value = expireAt + "|" + userAgent; redisUtil.setEx(key, value, 7, TimeUnit.DAYS); } /** * 验证是否已开启免MFA认证 */ public boolean isMfaSkipped(String userId, String userAgent, String ip) { String deviceHash = DigestUtils.sha256Hex(userAgent + ip).substring(0, 8); String key = "mfa_skip:" + userId + ":" + deviceHash; String value = redisUtil.get(key); if (value == null) { return false; } // 验证设备信息一致性（防盗用） String[] parts = value.split("\\|"); long expireAt = Long.parseLong(parts[0]); String storedUserAgent = parts[1]; return expireAt > System.currentTimeMillis() && storedUserAgent.equals(userAgent); } // --- AES加密工具方法 --- private String encrypt(String data) { // 实际实现需使用AES-GCM（此处简化） return Base64.getEncoder().encodeToString(data.getBytes()); } private String decrypt(String encrypted) { return new String(Base64.getDecoder().decode(encrypted)); } }

3.  IP获取工具IpUtils

public class IpUtils { public static String getClientIp(HttpServletRequest request) { // 1. 优先级解析代理头部 String[] headers = {"X-Forwarded-For", "Proxy-Client-IP", "WL-Proxy-Client-IP", "HTTP_CLIENT_IP", "HTTP_X_FORWARDED_FOR"}; for (String header : headers) { String ip = request.getHeader(header); if (isValidIp(ip)) { return parseFirstIp(ip); } } // 2. 直接获取远程地址 String ip = request.getRemoteAddr(); // 3. 处理本地环回地址（开发环境） if ("127.0.0.1".equals(ip) || "0:0:0:0:0:0:0:1".equals(ip)) { try { return InetAddress.getLocalHost().getHostAddress(); } catch (Exception e) { return "127.0.0.1"; } } return ip; } private static boolean isValidIp(String ip) { return ip != null && !ip.isEmpty() && !"unknown".equalsIgnoreCase(ip); } private static String parseFirstIp(String ip) { // 处理多IP场景（如：X-Forwarded-For: client, proxy1, proxy2） return ip.contains(",") ? ip.split(",")[0].trim() : ip; } }

4.登录、Mfa开启、Mfa校验、Mfa二维码以及10个备用一次性code生成（服务类省略）

 @Override public LoginResult login(LoginParam loginParam, HttpServletRequest request) { IotUser iotUser = this.getOne(new LambdaQueryWrapper<IotUser>().eq(IotUser::getAccount, loginParam.getAccount()) .eq(IotUser::getStatus, 0)); // 校验用户是否存在 if (ObjectUtil.isNull(iotUser)) { throw new ServiceException(IotUserExceptionEnum.LOGIN_ERROR); } // 验证账号密码是否正常 String requestMd5 = SaltUtil.md5Encrypt(loginParam.getPassword(), iotUser.getSalt()); String dbMd5 = iotUser.getPassword(); if (dbMd5 == null || !dbMd5.equalsIgnoreCase(requestMd5)) { throw new ServiceException(IotUserExceptionEnum.LOGIN_ERROR); } // 账号被冻结 if (iotUser.getStatus().equals(1)) { throw new ServiceException(IotUserExceptionEnum.ACCOUNT_FREEZE_ERROR); } // 密码校验成功后登录，一行代码实现登录  StpUtil.login(iotUser.getUserId()); StpUtil.getSession().set(Constants.USER_INFO_KEY, userDto(iotUser)); /** 获取当前登录用户的Token信息 */ SaTokenInfo saTokenInfo = StpUtil.getTokenInfo(); LoginResult loginResult = new LoginResult(); loginResult.setToken(saTokenInfo.getTokenValue()); loginResult.setMfaEnabled(iotUser.getMfaEnabled()); // 开启了MFA认证 if (iotUser.getMfaEnabled() == 1) { String ua = request.getHeader("User-Agent"); String ip = IpUtils.getClientIp(request); log.info("登录请求IP：" + ip); if (mfaService.isMfaSkipped(iotUser.getUserId(), ua, ip)) { // 触发免验证：激活安全会话 StpUtil.openSafe( 7 * 24 * 60 * 60); } else { loginResult.setNeedMfa(true); } } return loginResult; } @Override public VerifyResult verify(MfaVerifyParam verifyParam, HttpServletRequest request) { if (ObjectUtil.isNull(verifyParam.getCode())) { throw new ServiceException("验证码不能为空"); } if (ObjectUtil.isNull(verifyParam.getRemember())) { verifyParam.setRemember(false); } String userId = StpUtil.getLoginIdAsString(); // 1. 验证TOTP/备用码 if (!mfaService.verifyCode(userId, verifyParam.getCode())) { throw new ServiceException("验证码无效"); } // 2. 若选择免认证7天，更新数据库 if (Boolean.TRUE.equals(verifyParam.getRemember())) { String userAgent = request.getHeader("User-Agent"); String ip = IpUtils.getClientIp(request); log.info("MFA验证请求IP：" + ip); mfaService.setMfaSkip(userId, userAgent, ip); } // 3. 激活SA-Token安全会话（7天或一次性） StpUtil.openSafe(verifyParam.getRemember() ? 7 * 24 * 60 * 60 : 120); VerifyResult verifyResult = new VerifyResult(); verifyResult.setToken(StpUtil.getTokenValue()); verifyResult.setMsg("验证成功"); return verifyResult; } @Override public MfaSetupResult qrCode() { String userId = StpUtil.getLoginIdAsString(); return mfaService.setupMfa(userId); } @Override public void openMfa() { String userId = StpUtil.getLoginIdAsString(); IotUser iotUser = this.getById(userId); if (ObjectUtil.isNull(iotUser)) { throw new ServiceException("用户不存在"); } iotUser.setMfaEnabled(1); this.updateById(iotUser); }

5.Mfa校验入参类

@Data public class MfaVerifyParam { /** * Mfa动态、一次性备用代码 */ private String code; /** * 当前机器近7天是否跳过Mfa校验 */ private Boolean remember; }

6.控制类

@RestController public class IotPlatFormAuthController { @Resource private IotUserService iotUserService; /** * @description: 登录 * @param: [loginParam] * @return: com.honyar.core.model.response.ResponseData * @author: zhouhong */ @PostMapping("/auth/login") public ResponseData login(@RequestBody LoginParam loginParam, HttpServletRequest request) { return new SuccessResponseData(iotUserService.login(loginParam, request)); } /** * @description: 开启MFA * @param: [] * @return: com.honyar.core.model.response.ResponseData * @author: zhouhong */ @PostMapping("/auth/mfa/openMfa") public ResponseData openMfa() { iotUserService.openMfa(); return new SuccessResponseData(); } /** * @description: 获取MFA二维码 * @param: [] * @return: com.honyar.core.model.response.ResponseData * @author: zhouhong */ @PostMapping("/auth/mfa/qrcode") public ResponseData qrCode() { return new SuccessResponseData(iotUserService.qrCode()); } /** * @description: MFA验证 * @param: [verifyParam] * @return: com.honyar.core.model.response.ResponseData * @author: zhouhong */ @PostMapping("/auth/mfa/verify") public ResponseData verify(@RequestBody MfaVerifyParam verifyParam, HttpServletRequest request) { return new SuccessResponseData(iotUserService.verify(verifyParam, request)); } /** * @description: 登出 * @param: [] * @return: com.honyar.core.model.response.ResponseData * @author: zhouhong */ @PostMapping("/auth/logout") public ResponseData logout() { iotUserService.logout(); return new SuccessResponseData(); } }

c.演示

1.调用登录接口

说明：登录返回当前用户是否已经开启Mfa，当用户已经开启mfa（mfaEnable=1）并且needMfa（需要进行mfa）时需要前端拉起mfa校验页面调用mfa校验接口进行二次校验；当mfaEnable=1并且needMfa=false时，说明当前设备已经开启7天面mfa校验，直接登录成功进入系统；当mfaEnable=0时，说明用户为开启mfa，则引导用户调用接口先开启mfa（数据库用户mfaEnable字段置为1即可），然后再调用mfa校验接口进行mfa校验，如果用户选择不开启则直接登录成功进入系统。

2.调用mfa二维码、备用一次性code生成接口

说明：调用这个接口后前端根据 qrUrl信息生成一个二维码，并且同时浏览器下载备用code 到本地，用户使用Authenticator APP进行扫码添加用户，然后再使用 Authenticator 里面生成的code调用校验Mfa接口校验成功后进入系统；第二次用户直接从Authenticator获取code进行二次认证即可

3.调用Mfa校验接口

说明：校验成功后进入系统

本文来自博客园，作者：Tom-shushu，转载请注明原文链接：https://www.cnblogs.com/Tom-shushu/p/19009537