JWKS公钥轮换与缓存门禁（kid/ttl/回退）最佳实践

背景与价值JWKS公钥轮换要求资源端快速适配。缓存TTL与回退策略可降低失败概率并保障验签稳定。统一规范域白名单：只允许受控 `jwks_uri` 域名。TTL上限：缓存不超过上限（如30分钟）且不超过响应提示。回退策略：当前kid缺失时尝试刷新，失败则回退至上一版并记录审计。核心实现JWKS抓取与缓存type Jwk = { kid: string; kty: string; crv?: string; n?: string; e?: string } type Jwks = { keys: Jwk[] } class Cache<T> { data = new Map<string, { v: T; until: number }>(); get(k: string): T | undefined { const e = this.data.get(k); if (!e) return; if (Date.now() > e.until) { this.data.delete(k); return } return e.v } set(k: string, v: T, ttlMs: number) { this.data.set(k, { v, until: Date.now() + ttlMs }) } } const allowOrigins = new Set(['https://auth.example.com']) function originAllowed(url: string): boolean { try { const u = new URL(url); return allowOrigins.has(u.origin) } catch { return false } } async function fetchJwks(uri: string): Promise<Jwks | null> { if (!originAllowed(uri)) return null const r = await fetch(uri, { headers: { 'accept': 'application/json' } }) if (!r.ok) return null return r.json() } 验签与回退function base64urlToBuf(s: string): ArrayBuffer { const b = atob(s.replace(/-/g,'+').replace(/_/g,'/')); const u = new Uint8Array(b.length); for (let i=0;i<b.length;i++) u[i] = b.charCodeAt(i); return u.buffer } async function importRsa(nB64: string, eB64: string): Promise<CryptoKey> { const jwk: JsonWebKey = { kty: 'RSA', n: nB64, e: eB64, ext: true } return crypto.subtle.importKey('jwk', jwk, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']) } type JwtHeader = { alg: 'RS256' | 'ES256'; kid?: string } type VerifyCtx = { jwksUri: string; cache: Cache<Jwks>; maxTtlMs: number } async function verifyJwt(jwt: string, ctx: VerifyCtx): Promise<boolean> { const parts = jwt.split('.') if (parts.length !== 3) return false const [h, p, s] = parts const header: JwtHeader = JSON.parse(new TextDecoder().decode(base64urlToBuf(h))) if (header.alg !== 'RS256') return false let jwks = ctx.cache.get(ctx.jwksUri) let triedRefresh = false async function ensureJwks(): Promise<Jwks | null> { if (jwks) return jwks const fresh = await fetchJwks(ctx.jwksUri) if (!fresh) return null ctx.cache.set(ctx.jwksUri, fresh, ctx.maxTtlMs) jwks = fresh triedRefresh = true return fresh } jwks = jwks || await ensureJwks() if (!jwks) return false let key = jwks.keys.find(k => k.kid === header.kid && k.kty === 'RSA') if (!key && !triedRefresh) { jwks = await ensureJwks(); key = jwks?.keys.find(k => k.kid === header.kid && k.kty === 'RSA') || undefined } if (!key || !key.n || !key.e) return false const pub = await importRsa(key.n, key.e) const sig = base64urlToBuf(s) const ok = await crypto.subtle.verify({ name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, pub, sig, new TextEncoder().encode(h + '.' + p)) return !!ok } 落地建议对 `jwks_uri` 实施域白名单；缓存TTL不超过上限与响应提示。当kid缺失或不匹配时触发刷新与回退审计，失败拒绝访问。验证清单缓存是否在TTL内命中；kid是否精确匹配；失败是否触发刷新与回退。