no applicable key found in the JSON Web Key Set

jose (JavaScript) — JWKSNoMatchingKey, code ERR_JWKS_NO_MATCHING_KEY

含义

jose 查遍了你提供的 JSON Web 密钥集，没有找到可以用来验证这个令牌的密钥。只有同时满足以下所有条件的密钥才符合要求：`kid` 等于令牌头部的 `kid`（如果令牌中有的话）；`kty` 与令牌的 `alg` 相符；`alg`（如果存在）等于令牌的 `alg`；`crv` 匹配（ES256 对应 P-256）；`use` 不存在或为 `"sig"`；`key_ops`（如果存在）包含 `"verify"`。这里没有执行任何密码学运算——失败发生在密钥选择阶段。

原因

• 颁发者轮换了签名密钥

  常见

  新令牌带有新的 `kid`，而缓存的或硬编码的密钥集中还没有它。这是最常见的原因，通常恰好从轮换的那一分钟开始出现；之后重启过的服务能正常工作，较早启动的服务则会失败。

• 密钥集属于另一个颁发者或环境

  常见

  生产环境中用了预发布环境的 JWKS URL、另一个租户的 JWKS，或者从文档中复制来的密钥集。每个 `kid` 看起来都合理，但没有一个匹配。

• 密钥元数据与令牌矛盾

  偶见

  JWK 中写的是 `alg: "RS256"`，而令牌使用的是 ES256；或者 EC 密钥在 P-384 曲线上，而令牌使用的是 ES256（要求 P-256）。即使 `kid` 匹配，jose 也会跳过这类密钥，因为 JWK 元数据存在的意义，正是防止把密钥用于其他算法。

• 密钥被标记为用于加密

  偶见

  以 `use: "enc"` 发布的密钥，或者 `key_ops` 中不含 `"verify"` 的密钥，都不是签名验证密钥。有些提供商会在同一个密钥集中发布这两类密钥；只有 `sig` 密钥才能验证令牌。

• JWKS 的本地副本从未刷新

  偶见

  `createLocalJWKSet` 会一直使用你传入的密钥。如果密钥集是在部署时从文件或环境变量中读取的，下一次轮换后它就会悄无声息地过时。

修复方法

1. 1.

   把令牌的 kid 与已发布的密钥对比

   解码受保护头部，并列出已发布的密钥及其 `kid`、`alg`、`kty`、`crv` 和 `use`。如果密钥集中没有这个 `kid`，问题就出在轮换或用错了密钥集；如果有，就检查元数据字段。

   # kid and alg the token asks for
   python3 -c 'import base64,json,sys; h=sys.argv[1].split(".")[0]; print(json.loads(base64.urlsafe_b64decode(h + "=" * (-len(h) % 4))))' "$TOKEN"
   # kid, alg, kty, crv, use of every key the issuer publishes
   curl -s https://issuer.example.com/.well-known/jwks.json | jq '.keys[] | {kid, alg, kty, crv, use}'

2. 2.

   获取颁发者的 JWKS，而不是固定密钥

   `createRemoteJWKSet` 会缓存密钥，并在令牌指定了它没见过的 `kid` 时重新获取密钥集，因此能自动跟上轮换，同时又不会接受任意密钥。

   import { createRemoteJWKSet, jwtVerify } from "jose";
   
   // Fetches the JWKS, caches it, and refetches when a token names an unknown kid
   // (at most once per cooldownDuration, 30 s by default).
   const jwks = createRemoteJWKSet(new URL("https://issuer.example.com/.well-known/jwks.json"));
   const { payload } = await jwtVerify(token, jwks, {
     algorithms: ["ES256"],
     issuer: "https://issuer.example.com",
   });

3. 3.

   发布元数据一致的密钥

   如果颁发者由你运营，确保每个签名密钥都有唯一的 `kid`、`use: "sig"`，以及与它所签名的令牌相符的 `alg` 和 `crv`。先发布新密钥，再开始用它签名。

   {
     "keys": [
       { "kty": "EC", "crv": "P-256", "kid": "2026-10", "use": "sig", "alg": "ES256",
         "x": "…", "y": "…" }
     ]
   }

← 浏览完整的签名错误库