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

在现代应用安全中，仅靠用户名和密码的单一认证方式已难以抵御暴力破解、撞库等攻击。多因素认证（MFA）通过结合"你知道的"（密码）和"你拥有的"（手机/硬件令牌）来显著提升安全性。TOTP（基于时间的一次性密码） 是MFA中最常见的实现方式，Google Authenticator、Microsoft Authenticator等应用均基于此协议。本文将从实战角度，演示如何在SpringBoot中集成TOTP实现MFA。### 1. TOTP原理与流程TOTP的核心是基于共享密钥 和当前时间戳 生成动态密码。算法流程如下：- 客户端（如Google Authenticator）与服务器预先共享一个Base32编码的密钥。- 每隔30秒，客户端使用HMAC-SHA1对时间计数器（当前Unix时间戳除以30）和密钥进行哈希，取动态截断后的6位数字作为验证码。- 服务器使用相同算法验证用户输入的验证码，同时允许前后一个时间窗口的容错（防止时钟偏差）。整体流程：1. 用户注册/登录时，服务器生成密钥并返回二维码（包含otpauth://协议）。2. 用户将密钥导入认证器App。3. 登录时，用户输入密码+当前验证码，服务器校验。### 2. 项目依赖与配置首先，在pom.xml中添加TOTP相关依赖。我们使用jboss-otp库（轻量且支持标准的TOTP算法），或者直接使用commons-codec和javax.crypto手写算法。这里选用成熟的j256/two-factor-auth库，它无需额外配置即可生成和验证TOTP。xml<dependency> <groupId>com.j256.two-factor-auth</groupId> <artifactId>two-factor-auth</artifactId> <version>1.3</version></dependency>在application.yml中配置TOTP参数（可选，通常使用默认值）：yamltotp: # 时间步长（秒），默认30 time-step-size: 30 # 允许的时钟偏差窗口（前后各2个窗口） allowed-window: 2 # 密钥长度（字节），建议20（160位） secret-size: 20### 3. 核心代码实现#### 3.1 生成密钥与二维码当用户开启MFA时，我们需要生成一个随机密钥，并生成二维码字符串（otpauth://totp/issuer:account?secret=...）。用户用认证器扫描二维码后，服务端保存该密钥（通常加密存储在数据库）。javaimport com.j256.twofactorauth.TimeBasedOneTimePasswordUtil;import java.security.GeneralSecurityException;import java.util.Base64;public class TOTPService { /** * 生成随机密钥（Base32编码） */ public static String generateSecretKey() { // 默认生成20字节的随机数 byte[] secret = new byte[20]; new java.security.SecureRandom().nextBytes(secret); return Base32.encode(secret); // 使用Apache Commons Codec的Base32或自实现 } /** * 生成otpauth URI（用于二维码） * @param issuer 应用名称（如"MyApp"） * @param account 用户标识（如邮箱） * @param secret Base32密钥 */ public static String generateOtpAuthUri(String issuer, String account, String secret) { return String.format("otpauth://totp/%s:%s?secret=%s&issuer=%s", issuer, account, secret, issuer); } /** * 验证用户输入的TOTP码 * @param secret 密钥 * @param code 用户输入的6位验证码 * @param allowedWindow 允许的窗口偏差（例如2表示允许前后2*30秒） */ public static boolean validateCode(String secret, String code, int allowedWindow) { try { // 返回当前时间戳对应的TOTP码（或指定时间） long currentTime = System.currentTimeMillis(); // 使用库的校验函数，它内部处理时间窗口 boolean isValid = TimeBasedOneTimePasswordUtil.validateCurrentNumber( secret, code, allowedWindow, currentTime); return isValid; } catch (GeneralSecurityException e) { throw new RuntimeException("TOTP验证失败", e); } }}注意：Base32编码可使用com.google.common.io.BaseEncoding.base32()（Guava）或自行实现。为避免额外依赖，可手写一个简单的Base32编码器（下文会给出）。#### 3.2 手写Base32编码与解码（简化版）为了减少依赖，我们可以自己实现Base32。以下是一个简洁的实现：javapublic class Base32 { private static final String ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"; public static String encode(byte[] data) { StringBuilder sb = new StringBuilder(); int buffer = 0; int bitsLeft = 0; for (byte b : data) { buffer = (buffer << 8) | (b & 0xff); bitsLeft += 8; while (bitsLeft >= 5) { int index = (buffer >> (bitsLeft - 5)) & 0x1f; sb.append(ALPHABET.charAt(index)); bitsLeft -= 5; } } if (bitsLeft > 0) { int index = (buffer << (5 - bitsLeft)) & 0x1f; sb.append(ALPHABET.charAt(index)); } return sb.toString(); } public static byte[] decode(String base32) { int bits = 0; int buffer = 0; java.util.List<Byte> bytes = new java.util.ArrayList<>(); for (char c : base32.toUpperCase().toCharArray()) { int index = ALPHABET.indexOf(c); if (index == -1) continue; // 忽略非法字符 buffer = (buffer << 5) | index; bits += 5; if (bits >= 8) { bytes.add((byte) ((buffer >> (bits - 8)) & 0xff)); bits -= 8; } } byte[] result = new byte[bytes.size()]; for (int i = 0; i < bytes.size(); i++) result[i] = bytes.get(i); return result; }}#### 3.3 集成到SpringBoot认证流程假设我们有一个用户实体，包含mfaSecret字段（加密存储）。登录时，用户输入密码和TOTP码（如果已启用MFA）。以下是控制器和服务的示例：java@RestController@RequestMapping("/auth")public class AuthController { @Autowired private UserService userService; @PostMapping("/login") public ResponseEntity<?> login(@RequestBody LoginRequest request) { // 1. 验证用户名密码（此处省略） User user = userService.findByUsername(request.getUsername()); if (user == null || !passwordEncoder.matches(request.getPassword(), user.getPassword())) { return ResponseEntity.status(401).body("用户名或密码错误"); } // 2. 如果用户已启用MFA，则必须验证TOTP码 if (user.isMfaEnabled()) { if (request.getTotpCode() == null || request.getTotpCode().isEmpty()) { return ResponseEntity.status(401).body("需要提供TOTP验证码"); } boolean valid = TOTPService.validateCode(user.getMfaSecret(), request.getTotpCode(), totpConfig.getAllowedWindow()); if (!valid) { return ResponseEntity.status(401).body("TOTP验证码无效"); } } // 3. 生成JWT或Session String token = jwtService.generateToken(user); return ResponseEntity.ok(new LoginResponse(token)); } @PostMapping("/mfa/setup") public ResponseEntity<?> setupMfa(@RequestBody SetupMfaRequest request) { // 用户发起开启MFA，生成密钥并返回二维码URI String secret = TOTPService.generateSecretKey(); String otpUri = TOTPService.generateOtpAuthUri("MyApp", request.getUsername(), secret); // 保存secret到数据库（加密） userService.saveMfaSecret(request.getUsername(), secret); return ResponseEntity.ok(new MfaSetupResponse(otpUri)); } @PostMapping("/mfa/verify") public ResponseEntity<?> verifyMfa(@RequestBody VerifyMfaRequest request) { // 用户扫描二维码后，输入验证码以确认开启成功 User user = userService.findByUsername(request.getUsername()); boolean valid = TOTPService.validateCode(user.getMfaSecret(), request.getCode(), totpConfig.getAllowedWindow()); if (valid) { userService.enableMfa(user.getId()); return ResponseEntity.ok("MFA已启用"); } return ResponseEntity.status(400).body("验证码错误，无法启用MFA"); }}#### 3.4 配置类（可选）自定义配置类来读取application.yml中的TOTP参数：java@Configuration@ConfigurationProperties(prefix = "totp")public class TotpConfig { private int timeStepSize = 30; private int allowedWindow = 2; private int secretSize = 20; // getters and setters...}### 4. 前端集成与测试前端（如Vue/React）需要生成二维码。通常使用qrcode库将otpauth://URI渲染为图片。用户使用Google Authenticator扫描后，输入当前动态码完成绑定。测试步骤 ：1. 调用/auth/mfa/setup获取二维码URI，并使用在线工具（如qrcode-monkey）生成二维码，或用代码生成。2. 用手机Google Authenticator扫描二维码。3. 调用/auth/mfa/verify输入App显示的验证码，验证成功即启用。4. 登录时，密码+验证码同时提交。### 5. 安全注意事项- 密钥存储 ：切勿明文存储mfaSecret，应使用AES加密或KMS托管。- 防重放攻击 ：TOTP码在30秒内有效，但同一码在窗口内可重用。建议服务端记录最近使用的码（如Redis缓存），防止重复使用。- 时钟同步 ：服务器和客户端时间偏差可能导致验证失败，可适当增加allowedWindow（如2-3个窗口）。- 会话安全 ：MFA验证成功后，应生成短期会话token，并绑定设备信息。### 6. 总结本文从实战角度出发，完整演示了如何在SpringBoot中集成TOTP实现MFA。我们使用了two-factor-auth库简化算法实现，同时手写了Base32编码器以展示底层原理。核心流程包括：生成密钥、生成二维码URI、用户绑定、登录时校验。通过合理的配置和异常处理，可以轻松将MFA添加到现有SpringBoot应用中，极大提升账户安全性。在实际生产环境中，还需考虑密钥加密存储、防重放机制以及多设备管理，确保系统既安全又易用。希望本文能为你实现MFA提供清晰的参考。