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

一、MFA简介

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

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

二、核心原理

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

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

​​安全增强逻辑​​：

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

三、主流技术方案与对比

认证方式	安全性	用户体验	实施成本	场景
TOTP动态码​​	高	优	低	通用：企业系统、云服务等（推荐首选）
​​短信验证码​	中	中	中	金融支付、社交平台（需运营商集成）
生物识别​​（如人脸、指纹等）	极高	优	高	移动设备、高安全系统
​​硬件令牌​​（如YubiKey）	极高	中	高	金融、政府、军事系统

四、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校验接口

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