JWKS-Builder und -Validator

What a JWK Set is for

A JWK Set is a JSON object with one member, keys, holding an array of public keys as JWKs (RFC 7517 §5). An issuer of tokens — an OpenID Connect provider, an API gateway, your own auth service — publishes it at a URL (the jwks_uri of its OpenID configuration), and every verifier downloads it to find the key that checks a token's signature. The token names the key it was signed with in its header's kid; the verifier picks the key with that kid from the set.

Because the set is fetched by anyone, it must contain public keys only. Everything the builder writes is public; everything the checker flags first is something that should never have been published.

Building a set

Each entry can be a PEM public key, a certificate or a whole chain, a JWK, a JWK Set or an OpenSSH public key line. The builder reads it with the same parsers as the JWK converter and writes the public JWK with:

• kid — the key's own, or its RFC 7638 thumbprint. A thumbprint is computed from the key itself, so the issuer that signs and the set that publishes agree on it without a registry of IDs.
• use — sig for signing keys, enc for key-agreement keys (X25519, X448), unless the input says otherwise. OpenID Connect Discovery 1.0 §3 requires use on every key once a set holds both kinds.
• alg — kept as given, or set to the algorithm the key is usually published with (ES256 for P-256, RS256 for RSA, Ed25519 for Ed25519).
• x5c, x5t#S256 — for a certificate, the chain as base64 DER and the SHA-256 thumbprint of the leaf (RFC 7517 §4.7–4.9). The legacy SHA-1 x5t is added only on request.

A private key pasted by mistake contributes only its public half, and the entry says so; a shared secret (kty oct) is refused outright. Members appear in a conventional order — kty and the key material first, then kid, use, alg and the certificate members — so a diff of two versions of the set stays readable.

What the checker looks for

The set the builder produces is checked the way a verifier will read it, and so is any set you paste in Check a key set mode. The checks fall into three groups.

Things that leak. A private member — d of an EC or OKP key; d, p, q, dp, dq or qi of an RSA key — or a symmetric key in a public set is an error: whoever reads the set can sign tokens as you. Remove it and rotate the key; publishing it once is enough.

Things that break verification. Two keys of the same type with the same kid make key selection ambiguous (RFC 7517 §4.5 asks for distinct values; the same kid on keys of different types is allowed and reported as a note). Several keys without a kid leave verifiers guessing, which OpenID Connect Core §10.1 rules out. An alg that does not fit the key, use sig on an X25519 key, an RSA key below 2048 bits (RFC 7518 §3.3), an expired certificate in x5c, or a chain out of order are all reasons for a library to reject the key.

Things worth knowing. The same key published twice under different kids, RSA1_5 as an alg (RFC 8725 §3.2 recommends RSA-OAEP instead), a self-signed certificate, the SHA-1 x5t, or an x5u URL that a verifier would fetch — the checker reports such URLs but never fetches them.

Rotating keys without downtime

Verifiers cache the set, often for hours. Rotation therefore has three steps: publish the new key next to the old one, wait at least as long as the longest cache, then start signing with the new key; remove the old key once no valid token signed with it can still be in circulation. OpenID Connect Core §10.1.1 describes rotation the same way: add new keys to the set, switch signing to them, and keep recently retired keys published for a while. A thumbprint kid makes the overlap safe: two keys can never collide on an ID. JWKS key rotation without downtime walks through it with cache headers.

The example loads the public key set of RFC 7517 Appendix A.1: an EC P-256 key with use enc and an RSA key with alg RS256. Built as it is, it shows one of the checks at work — a set that mixes signing and encryption keys needs use on every key, and the RSA key has none until the builder labels it.