编程 JWT 签名密钥轮换:先发公钥再切签名,缓存窗口没等够日志里全是 no applicable key found

2026-11-20 00:04:34

JWT 签名密钥轮换:先发公钥再切签名,缓存窗口没等够日志里全是 no applicable key found

本篇只讲非对称签名密钥的分发侧:kid 与 JWKS 缓存。不讲 AES-GCM 密文代际,也不讲列加密的 key_version。

现象:新 kid 签的 token 全被拒

轮换 JWT 签名密钥最简单的做法是换一对 keypair,重启 issuer。然后 API 侧 401 刷屏,日志里常见:

  • jose:no applicable key found in the JSON Web Key Set
  • jwks-rsa:No KID specified and JWKS endpoint returned more than 1 key
  • jose:multiple matching keys found in the JSON Web Key Set

这些报错和「伪造 token」的表现一样,所以第一反应通常是怀疑被攻击。实际是自己把 rollout 顺序做反了。

关键点:kid 和 JWKS 不是 rollout 协议,它们只定义了 key identity 和 discovery。传播要靠你自己排时间线。

验证方的缓存时长才是 C

设:

  • C = 任一验证方(含 JWKS 端点前面的 Nginx/CDN)可能持有旧密钥集的最长时间
  • L = 你签发 token 的最长有效期
  • S = 允许的时钟偏差

顺序必须是:

  1. 先用旧钥签名
  2. 把新公钥发布进 JWKS
  3. 等满 C
  4. 再切换签名钥
  5. 再等 L+S+C
  6. 才从 JWKS 移除旧钥

具体例子:ASP.NET Core 的 ConfigurationManager 默认 12 小时刷新元数据,JWKS 前面挂 1 小时 Nginx 缓存,access token 1 小时,skew 5 分钟 → C = 13 小时。周一早上把新公钥发布,周一晚上才切签名,周二早上才移除旧钥。窗口以天计,代价只是密钥集里多一把 key。

常见库的默认值(来自源码或打印常量):

库缓存时长未知 kid 时刷新强制刷新
jose 6.2.13 createRemoteJWKSet10 分钟每 30 秒最多一次jwks.reload()
jwks-rsa 4.1.010 分钟,按 kid 缓存每次未命中都刷(开 rateLimit 后每分钟 10 次)重建客户端
PyJWT 2.15.1 PyJWKClient300 秒每 30 秒最多一次get_jwk_set(refresh=True)
keyfunc v3.8.2(Go)每小时后台刷新每 5 分钟最多一次Storage().KeyDelete(ctx, kid)
Nimbus JOSE+JWT 10.105 分钟,提前 30 秒每 30 秒最多一次重建 JWKSource
Microsoft.IdentityModel 8.23.0(ASP.NET Core)12 小时每 5 分钟最多一次RequestRefresh(),自身也限流 5 分钟
go-oidc v3.21.0 RemoteKeySet不过期每次未命中都刷,单飞重启进程

Spring Security 7.1.1 用 Nimbus 的 JWKSourceBuilder,但 JwkSetUriJwtDecoderBuilder 里 refreshAheadCache(false) + rateLimited(false),只剩 5 分钟缓存。

两个反直觉的推论

  1. 已知 kid 永远不触发刷新。从 JWKS 里删掉密钥,不会让验证方立刻拒绝——它按 kid 命中了缓存,缓存自然过期前根本不回源。「未命中即刷新」的逻辑看不见「删除」。

  2. 未知 kid 会触发刷新,但验证方会限速。任何人构造随机 kid 都能逼你的 API 回源 JWKS,所以库都设了冷却。于是「先签后发」的故障会自我延长:验证方刷新没找到新钥 → 进入 30 秒/5 分钟冷却 → 期间用新钥签的 token 全部拒绝,即使你马上把公钥补发上去。

kid 的四条规则

  • 唯一且永不复用。 RFC 7517 §4.5。跨时间复用比同一集合内重复更糟:按 kid 缓存的验证方会一直保存旧钥,而 jose 只在没有任何 key 匹配时才刷新,匹配到 key 但验签失败不刷新——缓存过期前,新钥签的 token 全部失败。
  • 不含验证方需要信任的信息。 kid 跟着未验签的 header 到达。用随机值、2026-11-b 日期标签或 RFC 7638 JWK 指纹。
  • 始终发送。 没有 kid 时验证方只能逐个试或放弃:jwks-rsa 直接报 No KID specified and JWKS endpoint returned more than 1 key。所以「两把 key 的 JWKS + 不带 kid 的 token」刚好会在每次轮换期间出故障。
  • 与 alg 配对发布。 RFC 8725 §3.1 要求密钥绑定单一算法。

JWKS 端点的 Cache-Control 不是性能参数

max-age 决定共享缓存替验证方挡住多久,也就决定了第 2 步至少得等多久。max-age=3600 意味着发布后必须等 1 小时才能切签名。加 stale-if-error(RFC 5861):端点挂了继续用最后一份正常密钥集,而不是让每个请求验签失败。

不要让端点以 200 返回空密钥集或错误页:jwks-rsa 报 The JWKS endpoint did not contain any signing keys;非 200 时 jose 报 Expected 200 OK from the JSON Web Key Set HTTP response。URL 永远不要变。

紧急轮换是另一个问题

计划内轮换优化连续性;密钥泄露时优化的是「伪造 token 还能被接受多久」。

顺序反过来:

  1. 立刻发布不含泄露密钥、含新钥的集合并切签名(部分验证方会短暂拒绝新 token,这是代价)
  2. 强制验证方刷新(调 reload()/RequestRefresh(),go-oidc 只能重启)
  3. 清 CDN 缓存
  4. 把泄露密钥签过的一切视为可疑

注意:轮换签名钥不会让已签发的自包含 JWT 立刻失效。resource server 离线验签的话,只要它还信任那把钥、token 没过期,就继续通过。要更强保证得靠更短 TTL、撤销表、introspection、audience 收紧。

观测项

按 kid 聚合的验签失败、unknown kid 突增、JWKS 拉取失败与延迟、签发实例之间的 active kid 分歧、退役后仍在请求旧钥的验证方。没有这些指标,你不知道重叠窗口是保守还是短得危险。

检查清单:

  • 集合里每把 key 都有唯一 kid、alg、use=sig
  • token 总带 kid
  • 新钥提前 C 发布才用于签名
  • 旧钥在最后一次签名后至少保留 L+S+C
  • 端点 Cache-Control 有 stale-if-error 且 URL 固定
  • 知道每个验证方的缓存时长与强制刷新方式
  • 紧急流程演练过
复制全文 生成海报 密钥轮换 JWT JWKS OIDC 鉴权

推荐文章

程序员茄子在线接单