安全無憂！在 Spring Boot 3.3 中輕松實現 TOTP 雙因素認證
作者：編程疏影
本 TOTP 注冊系統通過結合現代前端技術與穩健的后端架構，成功實現了高效、安全的用戶注冊流程。系統的設計充分考慮了安全性與用戶體驗，確保用戶在注冊過程中能夠快速獲取所需信息，而不影響安全標準。
隨著互聯網的快速發展，網絡安全問題日益嚴峻。傳統的用戶名和密碼認證方式已經無法滿足現代應用對安全性的要求，因此雙因素認證（2FA）成為了提升安全性的有效手段。雙因素認證不僅要求用戶輸入密碼，還需通過第二種方式進行身份驗證，例如手機生成的動態驗證碼。
時間同步一次性密碼（TOTP）是一種基于時間的雙因素認證方式，它通過算法生成短期有效的驗證碼。用戶在登錄時，需要輸入從手機應用（如 Google Authenticator）獲取的 TOTP 代碼。由于 TOTP 代碼每 30 秒更新一次，即使攻擊者獲取了用戶的密碼，沒有有效的 TOTP 代碼，也無法登錄賬戶。
本文將詳細介紹如何在 Spring Boot 3.3 中實現基于 TOTP 的雙因素認證，涵蓋從依賴配置、服務實現到前端展示的完整過程。
什么是 TOTP？
TOTP（Time-based One-Time Password）是一種用于雙因素認證的算法，它基于當前時間和用戶的共享秘密（密鑰）生成一次性密碼。TOTP 主要遵循以下步驟：
- 密鑰生成：在用戶賬戶創建時生成一個共享密鑰，并與用戶的身份綁定。該密鑰通常以 Base32 編碼格式存儲。
- 時間戳使用：TOTP 使用當前時間戳，將時間分成固定的時間段（例如，30 秒）。每個時間段生成一個唯一的 TOTP 密碼。
- 動態密碼生成：通過將共享密鑰和當前時間戳作為輸入，使用 HMAC-SHA1 或類似算法生成一次性密碼。
- 驗證過程：在用戶登錄時，服務器端也使用相同的共享密鑰和當前時間戳生成 TOTP 密碼，并與用戶輸入的密碼進行比對。
這種機制保證了每次登錄時生成的密碼都是唯一且短暫的，極大地提升了賬戶的安全性。
運行效果：
若想獲取項目完整代碼以及其他文章的項目源碼，且在代碼編寫時遇到問題需要咨詢交流，歡迎加入下方的知識星球。
項目依賴配置
首先，在 pom.xml 中添加所需的依賴：
<?xml versinotallow="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.4</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.icoderoad</groupId>
<artifactId>totp-authentication</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>totp-authentication</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
</dependency>
<dependency>
<groupId>dev.samstevens.totp</groupId>
<artifactId>totp</artifactId>
<version>1.7.1</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>配置文件
接下來，我們在 application.yml 中配置所需的屬性：
server:
port: 8080
totp:
time-step: 30
length: 6生成和配置密鑰
生成密鑰服務類
package com.icoderoad.totp.service;
import org.springframework.stereotype.Service;
import dev.samstevens.totp.secret.DefaultSecretGenerator;
import dev.samstevens.totp.secret.SecretGenerator;
@Service
public class SecretService {
private final SecretGenerator secretGenerator = new DefaultSecretGenerator();
public String generateSecret() {
// 生成安全的隨機 base32 編碼字符串
return secretGenerator.generate();
}
}屬性配置類
package com.icoderoad.totp.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import lombok.Data;
@Data
@Component
@ConfigurationProperties(prefix = "totp")
public class TotpProperties {
private int timeStep = 30; // 默認值為 30 秒
private int length = 6; // 默認值為 6 位
}配置 TOTP 生成器
package com.icoderoad.totp.service;
import com.icoderoad.totp.config.TotpProperties;
import dev.samstevens.totp.time.TimeProvider;
import dev.samstevens.totp.time.SystemTimeProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class TotpConfiguration {
private final TotpProperties totpProperties;
public TotpConfiguration(TotpProperties totpProperties) {
this.totpProperties = totpProperties;
}
@Bean
public TimeProvider timeProvider() {
return new SystemTimeProvider(); // 使用系統時間提供者
}
@Bean
public int getTotpLength() {
return totpProperties.getLength();
}
public int getTimeStepInSeconds() {
return totpProperties.getTimeStep();
}
}TOTP 生成和驗證
TOTP 生成服務
package com.icoderoad.totp.service;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.icoderoad.totp.config.TotpProperties;
import dev.samstevens.totp.code.CodeGenerator;
import dev.samstevens.totp.code.DefaultCodeGenerator;
import dev.samstevens.totp.exceptions.CodeGenerationException;
import dev.samstevens.totp.time.SystemTimeProvider;
import dev.samstevens.totp.time.TimeProvider;
@Service
public class TotpGeneratorService {
@Autowired
private TotpProperties totpProperties;
private final CodeGenerator codeGenerator;
private final TimeProvider timeProvider;
@Autowired
public TotpGeneratorService(TimeProvider timeProvider) {
this.timeProvider = timeProvider != null ? timeProvider : new SystemTimeProvider();
this.codeGenerator = new DefaultCodeGenerator(); // 使用默認構造函數
}
public String generateTotp(String secret) {
long counter = getCounter();
try {
return codeGenerator.generate(secret, counter);
} catch (CodeGenerationException e) {
return "";
}
}
private long getCounter() {
long timeStep = totpProperties.getTimeStep();
return timeProvider.getTime() / timeStep;
}
}TOTP 驗證服務
package com.icoderoad.totp.service;
import dev.samstevens.totp.code.CodeVerifier;
import dev.samstevens.totp.code.DefaultCodeVerifier;
import dev.samstevens.totp.code.DefaultCodeGenerator;
import dev.samstevens.totp.exceptions.CodeGenerationException;
import dev.samstevens.totp.time.TimeProvider;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.icoderoad.totp.config.TotpProperties;
@Service
public class TotpVerificationService {
private final DefaultCodeVerifier codeVerifier;
private final TimeProvider timeProvider;
private final TotpProperties totpProperties;
@Autowired
public TotpVerificationService(TimeProvider timeProvider, TotpProperties totpProperties) {
this.totpProperties = totpProperties;
this.timeProvider = timeProvider;
this.codeVerifier = new DefaultCodeVerifier(new DefaultCodeGenerator(), timeProvider);
this.codeVerifier.setTimePeriod(this.totpProperties.getTimeStep()); // 從配置文件中讀取或設置
this.codeVerifier.setAllowedTimePeriodDiscrepancy( this.totpProperties.getLength() ); // 可配置的時間誤差
}
public boolean verifyTotp(String secret, String code) {
return codeVerifier.isValidCode(secret, code);
}
}用戶注冊與 TOTP 集成
UserService 類
package com.icoderoad.totp.service;
import org.springframework.stereotype.Service;
import java.util.HashMap;
import java.util.Map;
@Service
public class UserService {
// 使用 HashMap 模擬用戶存儲（可以替換為數據庫實現）
private final Map<String, String> userSecrets = new HashMap<>();
/**
* 保存用戶的 TOTP 秘密
*
* @param username 用戶名
* @param secret 用戶的 TOTP 秘密
*/
public void saveUserSecret(String username, String secret) {
userSecrets.put(username, secret);
}
/**
* 根據用戶名獲取 TOTP 秘密
*
* @param username 用戶名
* @return TOTP 秘密
*/
public String findSecretByUsername(String username) {
return userSecrets.get(username);
}
// 可以添加更多與用戶相關的方法，如驗證用戶、獲取用戶信息等
}QRCodeGenerator類
package com.icoderoad.totp.generator;
import org.springframework.stereotype.Component;
import dev.samstevens.totp.exceptions.QrGenerationException;
import dev.samstevens.totp.qr.QrData;
import dev.samstevens.totp.qr.ZxingPngQrGenerator;
@Component
public class QRCodeGenerator {
private final ZxingPngQrGenerator qrGenerator;
public QRCodeGenerator() {
this.qrGenerator = new ZxingPngQrGenerator();
}
public byte[] generate(String secret, String username, String issuer, int digits, int period) throws QrGenerationException {
// 創建 QR 數據
QrData qrData = new QrData.Builder()
.label(username)
.secret(secret)
.issuer(issuer)
.digits(digits)
.period(period)
.build();
// 生成 QR 代碼
return qrGenerator.generate(qrData);
}
public String generateQrCodeUrl(String secret, String username, String issuer, int digits, int period) throws QrGenerationException {
byte[] qrCodeBytes = generate(secret, username, issuer, digits, period);
// 將生成的 QR 代碼轉換為 Base64 URL，便于在 HTML 中顯示
return "data:image/png;base64," + java.util.Base64.getEncoder().encodeToString(qrCodeBytes);
}
}RegistrationResponse類
package com.icoderoad.totp.controller;
public class RegistrationResponse {
private final String secret;
private final String qrCodeUrl;
public RegistrationResponse(String secret, String qrCodeUrl) {
this.secret = secret;
this.qrCodeUrl = qrCodeUrl;
}
public String getSecret() {
return secret;
}
public String getQrCodeUrl() {
return qrCodeUrl;
}
}注冊控制器
package com.icoderoad.totp.controller;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import com.icoderoad.totp.dto.UserDto;
import com.icoderoad.totp.generator.QRCodeGenerator;
import com.icoderoad.totp.service.SecretService;
import com.icoderoad.totp.service.UserService;
import dev.samstevens.totp.exceptions.QrGenerationException;
@RestController
public class RegistrationController {總結
本 TOTP 注冊系統通過結合現代前端技術與穩健的后端架構，成功實現了高效、安全的用戶注冊流程。系統的設計充分考慮了安全性與用戶體驗，確保用戶在注冊過程中能夠快速獲取所需信息，而不影響安全標準。總體而言，該系統不僅提升了用戶賬戶的安全性，也通過友好的操作流程增強了用戶的信任感，為未來的擴展和優化打下了堅實基礎。
責任編輯：武曉燕
來源：
路條編程
