Refresh Token 轮换:把重放检测建模为状态机
先把轮换建模成状态机
只给 refresh token 设一个长过期时间,泄露之后就是 7 天的攻击窗口。一次登录对应一个令牌族(family_id),每次刷新都在族内生成新会话,旧会话被标记为「已轮换」。数据库只存 refresh token 的 SHA-256 摘要,不存明文。
| 状态 | 字段 | 再次出现时 |
|---|---|---|
| 有效 | revoked_at IS NULL AND replaced_by_jti IS NULL |
正常刷新 |
| 已轮换 | replaced_by_jti 非空 |
判定重放 → 整族吊销 |
| 已吊销 | revoked_at 非空 |
只返回「令牌已吊销」 |
// 创建会话时只传 token_hash,仓储层不接收也不存储 refresh 明文
CreateSession(ctx, session) error
区分后两种状态不是学究:用户登出后客户端重试旧凭证是很常见的时序,一律当成重放会把其它设备一起踢下线;而一个已成功轮换的令牌再次出现,则说明它很可能被复制走了,是强得多的泄露信号。
原子轮换靠一条带条件的 UPDATE
把状态转换交给数据库,而不是「先查后改」:
func markRotated(ctx context.Context, jti, replacedByJTI string, usedAt time.Time) error {
// WHERE 条件要求 revoked_at IS NULL 且 replaced_by_jti IS NULL
res := db.Model(&RefreshToken{}).
Where("jti = ? AND revoked_at IS NULL AND replaced_by_jti IS NULL", jti).
Updates(map[string]any{
"replaced_by_jti": replacedByJTI,
"rotated_at": usedAt,
})
// RowsAffected == 0 → 已被轮换或吊销 → 按重放处理
}
并发的两个刷新请求里,只有一个能影响 1 行;另一个拿到 0 行,不能继续签发令牌,必须按重放处理。把这件事放在应用层用锁实现,跨实例就会失效;放在一条 UPDATE 的 WHERE 里,数据库替你保证。
重放检测应当可配置开关。关掉它等于承认「旧 refresh 可以无限重用」,只在排查期间临时关闭。
整族吊销要覆盖「还没过期的旧 access token」
access token 和 refresh 会话是两个独立的 jti,且每次刷新都会签发新的 access token。只拉黑当前 jti 会留下一个窗口:用户手上更早但仍未过期的同族 access token 依然可用,最长一个 access 有效期(常见 15 分钟)—— 「手机丢了要立刻下线」就不成立。
因此黑名单是双维度的:
| 维度 | 键示例 | 场景 |
|---|---|---|
| 单个令牌 | auth:bl:<jti> |
当前设备登出 |
| 整个令牌族 | auth:blf:<family> |
重放、下线设备、退出其它设备、禁用账号 |
// 鉴权是热路径:两个维度必须用多键 EXISTS 合并为一次缓存往返
func isAccessRevoked(ctx context.Context, jti, familyID string) (bool, error)
会话缓存的 TTL 要收敛在 60 秒内:缓存副本并不知道数据库已经把它吊销了,短 TTL 才能把吊销延迟控制住;登出、改密、强制下线这些要求立即生效的路径则主动删缓存。
改密为什么不需要遍历所有会话
改密与重置密码都在事务里做两件事:密码版本号 +1、吊销该用户全部 refresh 会话。access token 的载荷带 ver,鉴权时与数据库当前值一比就知道过期,无需扫一遍会话表;再叠加按族拉黑,旧的 access token 也立刻作废。
事务是权威状态的边界,缓存只加速检查。不要假设数据库与缓存共享原子事务:失效顺序要设计成可重试的,并且即使缓存写入失败,数据库的会话校验仍必须能挡住旧凭证。这也是缓存整体关闭时功能依然应该完整的原因 —— 会话校验、轮换、重放检测、令牌族吊销都走数据库,只有黑名单能力降级。
集成测试要专门打并发分支
集成测试应起一个完整应用实例(httptest + 带 Cookie 罐的客户端),跑整条链路:
注册 → 密码错误(防枚举) → 登录 → 访问受保护资源 → 刷新(轮换)
→ 新令牌可用 → 重放旧令牌 → 整族吊销 → 登出 → 令牌立即失效
→ 改密 → 旧令牌失效 → 旧密码不可用 → 审计落库校验
单测覆盖不了「两个刷新请求同时到达,只有一个成功」这类事实,它必须由真实数据库的条件 UPDATE 来证明。测试库名建议以 _test 结尾并在测试代码里加护栏(防止误删真实数据),数据库不可用时跳过集成用例而不是让整套单测失败。