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 = 允许的时钟偏差
顺序必须是:
- 先用旧钥签名
- 把新公钥发布进 JWKS
- 等满 C
- 再切换签名钥
- 再等 L+S+C
- 才从 JWKS 移除旧钥
具体例子:ASP.NET Core 的 ConfigurationManager 默认 12 小时刷新元数据,JWKS 前面挂 1 小时 Nginx 缓存,access token 1 小时,skew 5 分钟 → C = 13 小时。周一早上把新公钥发布,周一晚上才切签名,周二早上才移除旧钥。窗口以天计,代价只是密钥集里多一把 key。
常见库的默认值(来自源码或打印常量):
| 库 | 缓存时长 | 未知 kid 时刷新 | 强制刷新 |
|---|---|---|---|
| jose 6.2.13 createRemoteJWKSet | 10 分钟 | 每 30 秒最多一次 | jwks.reload() |
| jwks-rsa 4.1.0 | 10 分钟,按 kid 缓存 | 每次未命中都刷(开 rateLimit 后每分钟 10 次) | 重建客户端 |
| PyJWT 2.15.1 PyJWKClient | 300 秒 | 每 30 秒最多一次 | get_jwk_set(refresh=True) |
| keyfunc v3.8.2(Go) | 每小时后台刷新 | 每 5 分钟最多一次 | Storage().KeyDelete(ctx, kid) |
| Nimbus JOSE+JWT 10.10 | 5 分钟,提前 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 分钟缓存。
两个反直觉的推论
已知 kid 永远不触发刷新。从 JWKS 里删掉密钥,不会让验证方立刻拒绝——它按 kid 命中了缓存,缓存自然过期前根本不回源。「未命中即刷新」的逻辑看不见「删除」。
未知 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 还能被接受多久」。
顺序反过来:
- 立刻发布不含泄露密钥、含新钥的集合并切签名(部分验证方会短暂拒绝新 token,这是代价)
- 强制验证方刷新(调
reload()/RequestRefresh(),go-oidc 只能重启) - 清 CDN 缓存
- 把泄露密钥签过的一切视为可疑
注意:轮换签名钥不会让已签发的自包含 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 固定
- 知道每个验证方的缓存时长与强制刷新方式
- 紧急流程演练过