CONCEPT Cited by 1 source

JSON Web Key (JWK)¶

Definition¶

A JSON Web Key (JWK) is a JSON representation of a cryptographic key — public, private, or symmetric — standardised by RFC 7517 as part of the JSON Object Signing and Encryption (JOSE) family. A JWK Set (JWKS) is a JSON array of JWKs, typically published by an identity provider (IdP) at a well-known URI so that clients can fetch the IdP's current public keys over HTTPS and verify JWT signatures without any out-of-band key distribution.

JWK is the key-distribution substrate of the JOSE stack: JWT bearer tokens carry a kid (key ID) claim in their header, and the client looks up that kid in the IdP's JWKS to locate the public key that verifies the token's signature (Source: sources/2025-01-20-zalando-json-web-keys-jwk-rotating-cryptographic-keys-at-zalando).

Why it matters¶

JWK makes public-key distribution a web primitive. A JWT is signed by the IdP's private key and verified by any party holding the corresponding public key. Historically, distributing and rotating public keys across a wide client population was the painful part of any PKI. JWKS solves this with:

A well-known URL — e.g. Zalando's https://accounts.zalando.com/.well-known/jwk_uris — that any client can fetch over HTTPS.
A kid-indexed set — each key is addressable, so multiple keys (active + retired) can coexist during rotation windows.
Standard JSON wire format — libraries in every major language parse JWK directly into crypto primitives.
Cache-control headers — clients cache the JWKS; the IdP controls freshness via standard HTTP semantics.

The combination turns key rotation from a coordinated rollout into an operation the IdP performs unilaterally: publish the new public key, wait for caches to pick it up, start signing with the new private key, retire the old one after any tokens it signed have expired (concepts/signing-key-rotation-lifecycle).

Anatomy of a JWK¶

A single JWK is a JSON object with fields that name the key type and carry the public parameters:

{
  "kty": "RSA",
  "kid": "2025-01-20-signing-1",
  "use": "sig",
  "alg": "RS256",
  "n": "0vx7agoebGcQSuuPiLJXZ...",
  "e": "AQAB"
}

kty — key type (RSA, EC, oct).
kid — key ID, the handle JWTs reference from their header.
use — sig for signing, enc for encryption.
alg — algorithm (RS256, ES256, etc.).
n / e (RSA) or x / y / crv (EC) — public parameters.

A JWKS wraps an array of these:

{
  "keys": [
    { "kid": "2025-01-20-signing-1", ... },
    { "kid": "2024-12-15-signing-9", ... }
  ]
}

Multiple entries are the normal steady-state: an IdP mid- rotation advertises both its new key (already published, not yet signing) and its active key (currently signing), and continues to publish any retired keys until the maximum lifetime of tokens they could have signed has elapsed.

Role in OIDC / JWT verification¶

An OpenID Connect identity provider issues JWTs that assert claims about a user or workload. A verifier (another Zalando service, a third-party API, a mobile SDK) needs to answer two questions on every request:

Was this token signed by the IdP I trust? → look up the kid in the IdP's cached JWKS and verify the signature.
Is it still valid? → check exp, iat, iss, aud.

The JWKS endpoint is the link: without it, step 1 requires secure out-of-band key distribution every time a key rotates. With it, step 1 is a cache lookup (hit) or an HTTPS GET (miss) against a standards-mandated endpoint.

Why rotation is non-negotiable¶

"If a signing key's private part is compromised, anyone could forge fake tokens. These tokens could then be used to impersonate users and access sensitive data. Essentially, all tokens signed with the leaked key would become untrustworthy." (Source: sources/2025-01-20-zalando-json-web-keys-jwk-rotating-cryptographic-keys-at-zalando)

The JWK distribution surface makes the rotation itself cheap; the expensive part is the ordering discipline — the five phases and the retirement formula — that ensures clients never see an invalid signature during the transition.

Seen in¶

systems/zalando-oidc-identity-provider — Zalando's customer identity platform IdP publishes its JWKS at accounts.zalando.com/.well-known/jwk_uris and runs an automated, scheduled rotation over that endpoint (patterns/phased-automated-jwk-rotation). The 2025-01-20 article is the canonical instance.