A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. It's a standardized way to describe public or private keys (symmetric or asymmetric) in a web-friendly format.

JWKs are fundamental to the JSON Web Token (JWT) ecosystem and are defined in RFC 7517.

Why are JWKs used?

• Standardization: Provides a consistent format for representing cryptographic keys, making it easier for different systems and programming languages to exchange and understand them.
• Interoperability: Facilitates secure communication and authentication between various web services, especially in distributed systems like microservices architectures.
• Key Discovery: When combined into a JSON Web Key Set (JWKS), they allow clients (e.g., resource servers) to dynamically discover the public keys used by an authorization server to sign JWTs. This is crucial for seamless key rotation.

Key Parameters of a JWK

A JWK is a JSON object with several members (key-value pairs) that describe the cryptographic key. Common parameters include:

• kty (Key Type): REQUIRED. Identifies the cryptographic algorithm family used with the key. Common values include:

  • RSA for RSA keys
  • EC for Elliptic Curve keys
  • oct for Octet (symmetric) keys

• use (Public Key Use): OPTIONAL. Indicates the intended use of the public key.

  • sig for signature verification
  • enc for encryption

• key_ops (Key Operations): OPTIONAL. Identifies the operation(s) for which the key is intended to be used. This is an array of strings (e.g., ["verify", "encrypt"]). This parameter is usually mutually exclusive with use for public keys.

• alg (Algorithm): OPTIONAL. Identifies the specific cryptographic algorithm used with the key (e.g., RS256, ES256, A128GCM).

• kid (Key ID): OPTIONAL, but highly RECOMMENDED. A unique identifier for the key. This is critical for key rotation, as the kid in a JWT header allows the verifying party to select the correct public key from a JWKS.

• Key Type Specific Parameters: Depending on the kty value, additional parameters are present:

  • For RSA keys (kty: "RSA"):
    • n (modulus): Base64url-encoded modulus value for the RSA public key.
    • e (exponent): Base64url-encoded exponent value for the RSA public key.
  • For Elliptic Curve keys (kty: "EC"):
    • crv (Curve): The elliptic curve name (e.g., P-256, P-384, P-521).
    • x (X Coordinate): Base64url-encoded X coordinate for the Elliptic Curve public key.
    • y (Y Coordinate): Base64url-encoded Y coordinate for the Elliptic Curve public key.
  • For Symmetric keys (kty: "oct"):
    • k (Key Value): Base64url-encoded symmetric key value.

• x5c (X.509 Certificate Chain): OPTIONAL. An array of Base64-encoded X.509 certificates that can be used to verify the public key.

Example JWK (RSA Public Key for Signing)

{
  "kty": "RSA",
  "kid": "my-rsa-signing-key-2025-06-27",
  "use": "sig",
  "alg": "RS256",
  "n": "qL3U2eB1f_k-qJ2w...",
  "e": "AQAB"
}

.well-known/jwks.json

The use of .well-known/jwks.json as an endpoint for JSON Web Key Sets (JWKS) is indeed a strong and widely adopted convention, specified by RFC 8615, "Well-Known Uniform Resource Identifiers (URIs)".

Here's why this convention exists and why it's generally preferred over a simple /jwks endpoint:

What is .well-known?

The /.well-known/ URI prefix is a standardized way to designate a location on a web server for publishing server-specific information that clients can discover in a predictable manner. It's defined by RFC 8615.

The idea is that if a client (e.g., an application, a library, or even a human) needs to find a specific piece of information about a server (like its public keys, or a security policy), they know to look under the /.well-known/ path.

Why /.well-known/jwks.json is the Convention

1. Standardization and Discoverability:

   • It creates a predictable and discoverable location for JWKS. Any client (e.g., a Spring Security resource server, an OAuth 2.0 client library, a mobile app) that needs to verify JWTs issued by your authorization server knows exactly where to look for the public keys.
   • Without this convention, every authorization server could choose its own arbitrary path (e.g., /keys, /api/v1/jwks, /myAuthServer/publicKeys), forcing clients to be individually configured for each server, leading to significant complexity and integration headaches.

2. Interoperability:

   • This convention is a cornerstone of the OpenID Connect (OIDC) specification. OIDC identity providers are required to publish their configuration metadata, including the JWKS endpoint, under /.well-known/openid-configuration. This further solidifies /.well-known/jwks.json as the standard for key discovery in federated identity systems.
   • Many libraries and frameworks (like Spring Security's OAuth2 Resource Server) are built with the expectation of finding the JWKS at this well-known location, simplifying configuration significantly.

3. Security Considerations:

   • Reduced Configuration Errors: A standardized location means less manual configuration, reducing the chance of human error that could lead to misconfigured security settings.
   • Clear Purpose: The /.well-known/ prefix clearly signals that the content served from this path is for machine-readable, widely discoverable metadata, often security-related.

Why Not Just /jwks?

While technically https://your-auth-server.com/jwks would work, it misses the benefits of the /.well-known/ convention:

• Lack of Standardization: It's an arbitrary path. While you might know it, other developers or third-party clients consuming your JWTs wouldn't, unless you explicitly documented it every single time.
• No Automatic Discovery: Clients or libraries can't "guess" where your JWKS is. They'd need to be manually configured with the full URI for every server.
• Breaks OpenID Connect / OAuth 2.0 Best Practices: If you're building an OIDC provider, deviating from /.well-known/ would make your implementation non-compliant and hinder interoperability with standard OIDC clients.

In essence, /.well-known/ is akin to a globally recognized address book entry for important server information. Using it for JWKS means your authorization server is immediately intelligible to any system that adheres to web standards for key discovery, making your application part of a much larger, more secure, and more interoperable ecosystem.