JWT kid 未找到 — 密钥轮换导致验签失败

症状

遇到“JWT kid 未找到 — 密钥轮换导致验签失败”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• 验签失败并提示 “Unable to find a signing key that matches the kid”
• 仅在身份提供方轮换密钥后令牌失败
• 轮换期间部分令牌可验签，部分失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

node -e "const t=process.argv[1].split('.')[0]; console.log(JSON.parse(Buffer.from(t,'base64url')))" "$TOKEN"

头部 alg 与 kid 会告知签发方使用的密钥与算法。

步骤 2

curl -s https://idp.example.com/.well-known/jwks.json | jq '.keys[].kid'

若令牌中的 kid 不在 JWKS 中，说明缓存陈旧，需刷新。

常见诱因（按出现频率排序）：

• JWKS 缓存陈旧，缺少新 kid
• 用单一硬编码密钥验签，而非按 kid 选择
• 签名算法与密钥类型不匹配（RS256 对 ES256）

根因

JWT 验签会依据令牌的 kid 从签发方 JWKS 中选择公钥。密钥轮换后，缓存的 JWKS 缺少新 kid，验签找不到匹配密钥而失败，直到缓存刷新。

修复

缓存 JWKS 并按 kid 选择，遇到未知 kid 时先刷新一次再失败，把 alg 与白名单比对，并设置较短 TTL 以便快速感知轮换。

注意：盲目接受令牌 alg 会引发算法混淆攻击；务必将 alg 与密钥绑定的白名单比对。

import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL('https://idp.example.com/.well-known/jwks.json'));

export async function verify(token) {
  const { payload } = await jwtVerify(token, jwks, {
    algorithms: ['RS256'],              // allowlist, tied to the key
    issuer: 'https://idp.example.com/',
    audience: 'api.example.com',
  });
  return payload;
}
// createRemoteJWKSet refreshes automatically on an unknown kid

验证

验证用轮换后密钥签名的令牌并确认成功；验证未知 kid 的令牌触发一次刷新后干净失败。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。