JSON Web Key Set (JWKS)

JWKS endpoints are often exposed at a standardized, well-known location to enable dynamic discovery. The OpenID Connect Discovery specification defines the jwks_uri endpoint, typically found at /.well-known/openid-configuration. Clients can automatically discover this URL to fetch the latest keys, facilitating seamless key rotation and deployment.

• Common endpoint path: /.well-known/jwks.json.
• Allows clients to adapt to key changes without manual reconfiguration.
• Essential for scalable, multi-tenant identity systems.

A JSON Web Token (JWT) is the primary payload validated using keys from a JWKS. It is a compact, URL-safe token format defined in RFC 7519 that encodes a set of claims as a JSON object. JWTs are used as access tokens and ID tokens in OAuth 2.0 and OpenID Connect.

• Structure: A JWT consists of three Base64Url-encoded parts separated by dots: Header.Payload.Signature.
• Signing: The signature is created using the algorithm specified in the header (e.g., RS256) and a private key. The corresponding public key, published in the JWKS, is used for verification.
• Use Case: When a client receives a JWT from an authorization server, it fetches the server's JWKS to find the correct public key to verify the token's signature and integrity.

A JSON Web Key (JWK) is the individual cryptographic key object defined in RFC 7517 that makes up a JWKS. A JWKS is simply a JSON object with a keys member, whose value is an array of JWKs.

• Key Properties: A JWK contains metadata such as the key type (kty), the public key material (e.g., n and e for RSA), the intended use (use), and a unique key identifier (kid).
• Key Types: Common kty values include RSA and EC (Elliptic Curve).
• Key Identifier (kid): This is a crucial field used by clients to select the correct JWK from the set that matches the kid claim in the JWT header.

OpenID Connect Discovery (OIDC Discovery), defined by the OpenID Connect standard, is the mechanism by which clients dynamically discover the endpoints and configuration of an OpenID Provider, including the location of its JWKS.

• Discovery Document: Clients fetch a well-known configuration document from a standard endpoint (e.g., /.well-known/openid-configuration).
• JWKS URI: This document contains the jwks_uri property, which is the HTTPS URL from which the client can retrieve the provider's current public keys in JWKS format.
• Automation: This process eliminates the need for manual key distribution and allows for seamless key rotation, as clients always query the published jwks_uri.

JSON Web Signature (JWS), defined in RFC 7515, is the underlying standard for producing signed JWTs. A JWT is essentially a JWS with a registered claim set as its payload.

• Signing Process: JWS defines how to create a digital signature or MAC over the JWT's header and payload.
• Algorithms: The JWT header specifies the alg (algorithm), such as RS256 (RSA Signature with SHA-256) or ES256 (ECDSA P-256 with SHA-256). The public key needed to verify this signature is published as a JWK.
• Detached vs. Compact Serialization: JWTs use the compact serialization of JWS, which produces the familiar three-part string. The JWKS provides the keys to validate this serialization.

While JWKS enables local signature validation, the OAuth 2.0 Token Introspection endpoint (RFC 7662) provides an alternative, centralized method for a resource server to check the active state of a token.

• Remote Validation: The resource server sends the token to the authorization server's introspection endpoint, which returns a JSON response indicating if the token is active and its associated metadata (scopes, client ID, etc.).
• Comparison to JWKS: JWKS validation is stateless and faster but only confirms the token was properly signed and is unexpired. Introspection is stateful and can immediately reflect revocation events.
• Hybrid Approach: Many systems use JWKS for fast, initial signature validation and fall back to introspection for high-value operations or when immediate revocation checks are required.