← 返回筆記列表

Refresh Token 轮换:把重放检测建模为状态机

發布于 來自 半盏灯 最近更新

  • Go
  • JWT
  • 会话管理
  • 安全

先把轮换建模成状态机

只给 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 结尾并在测试代码里加护栏(防止误删真实数据),数据库不可用时跳过集成用例而不是让整套单测失败。