身份认证与应用安全 / 系统课时

保存 Refresh Token 状态

保存 Refresh Token 状态

Refresh Token 生命周期长于 Access Token,仅靠客户端持有无法做到即时撤销。本节把它设计成“客户端保存原令牌、服务端保存可校验状态”的模式,并落地用户、过期时间、撤销状态和必要设备信息。

学习目标

  • 设计可撤销、可过期的 Refresh Token 服务端记录
  • 使用令牌摘要而不是明文保存敏感凭证
  • 根据用户、设备和撤销状态判断一次刷新是否仍然有效

为什么要保存服务端状态

Access Token 通常有效期较短,可以保持无状态;Refresh Token 往往存活数天甚至数周,一旦泄露,如果服务端完全不记录状态,就很难在用户退出登录、改密或发现异常设备后立即让它失效。

服务端记录的核心作用不是重复保存 JWT 内容,而是提供一个可控的“开关”。客户端提交原始 Refresh Token,服务端先计算摘要,再用摘要定位记录并检查用户、过期时间和撤销状态。

Refresh Token 服务端状态与校验关系

设计状态表

示例以 MySQL 8 为例。token_hash 唯一定位一枚 Refresh Token,revoked_at 为空表示尚未主动撤销;device_id 只保存稳定的设备标识,不直接把 IP 或完整 User-Agent 当成身份依据。

sql
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,本类只负责计算摘要并写入状态。

java
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 中验证“同一原令牌得到同一摘要并能命中记录”:

sql
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);

预期输出:

text
+---------+---------+--------------+
| 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 即使尚未自然过期,也能被明确、可审计地终止。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

保存 Refresh Token 状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通