【亲测免费】 Java 时间基一时密码（TOTP）库安装与配置指南

2026-01-21 05:07:34作者：牧宁李

项目基础介绍与主要编程语言

项目名称: java-totp
主要编程语言: Java
本项目是由Samuel Stevens开发的一个Java库，旨在实现基于时间的一次性密码（Time-based One-Time Password，简称TOTP），用于多因素认证。它使得开发者能够轻松集成Google Authenticator等应用所使用的那种动态验证码功能到自己的系统中。项目遵循MIT许可证，适用于Java 8及以上版本的环境。

项目关键技术与框架

核心算法: 使用HMAC-SHA1作为默认加密散列函数，也支持SHA256和SHA512。
依赖管理: 支持Maven和Gradle，便于集成到现代Java项目中。
Spring Boot集成: 提供了TOTP Spring Boot Starter，简化在Spring Boot项目中的部署。
二维码生成: 利用ZXing库来生成QR码，以便于用户的手机认证应用扫码添加账号。

安装与配置步骤

准备工作

确保你的开发环境已经设置了以下内容：

Java: 确保已安装Java 8或更高版本。
IDE: 如IntelliJ IDEA或Eclipse，任选其一。
构建工具: Maven或者Gradle。

详细安装步骤

1. 添加项目依赖

如果你的项目是基于Maven的，打开pom.xml文件并添加以下依赖：

<dependencies>
    <!-- 添加java-totp依赖 -->
    <dependency>
        <groupId>dev.samstevens.totp</groupId>
        <artifactId>totp</artifactId>
        <version>1.7.1</version>
    </dependency>
</dependencies>

对于Gradle项目的build.gradle文件，添加如下代码：

dependencies {
    compile 'dev.samstevens.totp:totp:1.7.1'
}

2. 配置Spring Boot（可选）

如果你的项目是Spring Boot，可以通过引入TOTP Spring Boot Starter自动配置。首先，在你的pom.xml中加入对应的Starter依赖，并按照文档中的【Using Java-TOTP with Spring Boot】部分进行配置。

3. 生成和验证TOTP密码

生成共享密钥：利用提供的API生成一个共享密钥，用于与用户设备配对。

import dev.samstevens.totp.secret.DefaultSecretGenerator;
String secret = new DefaultSecretGenerator().generate();

生成QR码：基于这个密钥生成一个QR码，供用户扫描设置MFA。

import dev.samstevens.totp.qr.QrData;
import dev.samstevens.totp.qr.ZxingPngQrGenerator;

// 创建包含应用信息的QrData对象
QrData data = new QrData.Builder()
    .label("your-email@example.com")
    .secret(secret)
    .issuer("YourAppName")
    .build();

// 生成QR码图片数据
QrGenerator generator = new ZxingPngQrGenerator();
byte[] qrImageData = generator.generate(data);

验证一次性密码：用户输入的TOTP密码需要验证。

import dev.samstevens.totp.code.DefaultCodeGenerator;
import dev.samstevens.totp.code.DefaultCodeVerifier;
import dev.samstevens.totp.time.SystemTimeProvider;

DefaultCodeGenerator codeGenerator = new DefaultCodeGenerator();
DefaultCodeVerifier verifier = new DefaultCodeVerifier(codeGenerator, new SystemTimeProvider());

boolean isValid = verifier.isValidCode(secret, "USER_ENTERED_CODE_HERE");