身份认证与应用安全 / 系统课时
保存 Refresh Token 状态
保存 Refresh Token 状态
Refresh Token 生命周期长于 Access Token,仅靠客户端持有无法做到即时撤销。本节把它设计成“客户端保存原令牌、服务端保存可校验状态”的模式,并落地用户、过期时间、撤销状态和必要设备信息。
学习目标
- 设计可撤销、可过期的 Refresh Token 服务端记录
- 使用令牌摘要而不是明文保存敏感凭证
- 根据用户、设备和撤销状态判断一次刷新是否仍然有效
为什么要保存服务端状态
Access Token 通常有效期较短,可以保持无状态;Refresh Token 往往存活数天甚至数周,一旦泄露,如果服务端完全不记录状态,就很难在用户退出登录、改密或发现异常设备后立即让它失效。
服务端记录的核心作用不是重复保存 JWT 内容,而是提供一个可控的“开关”。客户端提交原始 Refresh Token,服务端先计算摘要,再用摘要定位记录并检查用户、过期时间和撤销状态。

设计状态表
示例以 MySQL 8 为例。token_hash 唯一定位一枚 Refresh Token,revoked_at 为空表示尚未主动撤销;device_id 只保存稳定的设备标识,不直接把 IP 或完整 User-Agent 当成身份依据。
CREATE TABLE refresh_token (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
token_hash CHAR(64) NOT NULL UNIQUE,
user_id BIGINT NOT NULL,
expires_at DATETIME(6) NOT NULL,
revoked_at DATETIME(6) NULL,
device_id VARCHAR(128) NULL,
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
INDEX idx_refresh_token_user_id (user_id),
INDEX idx_refresh_token_expires_at (expires_at)
);预期结果:数据库成功创建 refresh_token 表,并建立令牌摘要唯一约束以及用户、过期时间索引。过期记录是否立即物理删除属于清理策略,但校验时始终必须检查 expires_at。
写入令牌时只保存摘要
下面是片段示例,假定 Spring Boot 已配置 JdbcTemplate 数据源且上面的表已经存在。调用方负责生成高熵 Refresh Token,本类只负责计算摘要并写入状态。
package com.example.auth;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.sql.Timestamp;
import java.time.Instant;
import java.util.HexFormat;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
@Service
public class RefreshTokenStore {
private final JdbcTemplate jdbcTemplate;
public RefreshTokenStore(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
public void save(long userId, String rawToken, Instant expiresAt, String deviceId) {
String tokenHash = sha256(rawToken);
jdbcTemplate.update(
"INSERT INTO refresh_token(token_hash, user_id, expires_at, device_id) VALUES (?, ?, ?, ?)",
tokenHash,
userId,
Timestamp.from(expiresAt),
deviceId
);
}
static String sha256(String value) {
try {
byte[] digest = MessageDigest.getInstance("SHA-256")
.digest(value.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(digest);
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException("SHA-256 unavailable", e);
}
}
}这样数据库泄露时不会直接暴露可重放的原始 Refresh Token。前提是令牌本身必须具有足够随机性;生产环境还可以使用带服务端密钥的 HMAC 摘要,进一步隔离数据库记录与实际凭证。
可直接在 MySQL 中验证“同一原令牌得到同一摘要并能命中记录”:
INSERT INTO refresh_token(token_hash, user_id, expires_at, device_id)
VALUES (
SHA2('demo-refresh-token', 256),
42,
DATE_ADD(CURRENT_TIMESTAMP(6), INTERVAL 30 DAY),
'browser-main'
);
SELECT user_id,
revoked_at IS NOT NULL AS revoked,
device_id
FROM refresh_token
WHERE token_hash = SHA2('demo-refresh-token', 256);预期输出:
+---------+---------+--------------+
| user_id | revoked | device_id |
+---------+---------+--------------+
| 42 | 0 | browser-main |
+---------+---------+--------------+校验时同时看过期与撤销
一次 Refresh Token 可以继续使用,至少要同时满足:摘要能查到记录、revoked_at 为空、expires_at 晚于当前时间,并且对应用户仍允许登录。任一条件失败,都不应继续签发新的 Access Token。
主动退出当前设备时,可以只给这一条记录写入 revoked_at;用户改密或触发高风险事件时,可以按 user_id 批量撤销该用户的全部有效记录。这样“退出一台设备”和“让全部会话失效”可以使用同一套状态模型实现。
设备信息保持最小化
设备信息用于帮助用户识别会话和执行定向撤销,不应成为脆弱的强认证条件。IP 会变化,User-Agent 也可能升级或伪造,因此更适合保存应用生成的稳定 device_id,再配合创建时间、最近使用时间等非敏感信息展示。
如果产品允许多设备登录,还应限制单用户有效 Refresh Token 的数量,并在新登录成功后清理过旧会话。服务端状态记录的价值就在于:Refresh Token 即使尚未自然过期,也能被明确、可审计地终止。