oidcjose

JSON Web Key (JWK)

A JSON Web Key (JWK) is a JSON-based format used for representing cryptographic keys. When multiple JWKs need to be grouped together, they are organized into a JSON Web Key Set (JWKS).

Edit on GitHub

What is a JSON Web Key (JWK)?

A JSON Web Key (JWK) is a JSON-based format used for representing cryptographic keys. It’s widely used in the context of JSON Web Signature (JWS) and JSON Web Encryption (JWE) to validate the integrity and confidentiality of JSON Web Tokens . It is also used in OpenID Connect (OIDC) for identity and access management.

For example, a PEM-encoded ECDSA public key:

…can be represented as a JWK:

{
  "kty": "EC",
  "crv": "P-384",
  "x": "F_xQdbOho2Jw0hgmNPD0VAEPAgkQrfD4f1Qx3y49cUm646fMBX9DYx-43HzXm6Vd",
  "y": "X77uFymz90aO4dBunpTdUzLFRAiT7-IngzZGDrIE-FG6CcqQuRP65r65SUzDOmP5"
}

How does a JWK work?

Since JWK is a JSON-based format, it can carry rich metadata about the key compared to traditional formats like PEM. Here are some common attributes in a JWK:

kty (Key Type): The cryptographic algorithm family used with the key. Common values include RSA, EC, and oct. EC has been marked as “Recommended+” in RFC 7518 .
use (Public Key Use): The intended use of the public key. Common values include sig (signature) and enc (encryption).
key_ops (Key Operations): The key operations supported by the key. Common values include sign, verify, encrypt, and decrypt.
alg (Algorithm): The algorithm intended for use with the key. Depending on the key type, the algorithm may vary. For example, RS256 may be used with an RSA key, while ES256 may be used with an EC key.
kid (Key ID): A unique identifier for the key. It can be used to match a specific key in a set of keys.

Except kty, all other attributes are optional and can be used to provide additional context about the key. According to the value of kty, other attributes may be required or optional. In the above example, the JWK represents an ECDSA key (kty: "EC") with a curve of P-384 (crv: "P-384"). The x and y attributes contain the public key coordinates.

Here’s another non-normative example of an RSA public key JWK:

{
  "kty": "RSA",
  "use": "sig",
  "alg": "RS256",
  "n": "0vx7agoebGcQSuuPiLJXZpt...-TmV4HCA1T8jXg3fE2VbA",
  "e": "AQAB",
  "kid": "2011-04-29-1234"
}

For detailed information about JWK attributes and their meanings, refer to RFC 7517 .

JSON Web Key Set (JWKS)

When multiple JWKs need to be grouped together, they are organized into a JSON Web Key Set (JWKS). A JWKS is a JSON object that contains an array of JWKs. It’s commonly used in the response of the jwks_uri endpoint in OpenID Connect (OIDC) Discovery to provide the public keys for JWT Signing key validation.

Here’s a non-normative example of a JWKS containing two JWKs:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZpt...-TmV4HCA1T8jXg3fE2VbA",
      "e": "AQAB",
      "kid": "2011-04-29-1234"
    },
    {
      "kty": "EC",
      "crv": "P-384",
      "x": "F_xQdbOho2Jw0hgmNPD0VAEPAgkQrfD4f1Qx3y49cUm646fMBX9DYx-43HzXm6Vd",
      "y": "X77uFymz90aO4dBunpTdUzLFRAiT7-IngzZGDrIE-FG6CcqQuRP65r65SUzDOmP5"
    }
  ]
}

In this example, the JWKS contains two JWKs: one RSA key and one EC key. The keys attribute is an array of JWKs, each representing a different key.

What is a JSON Web Key (JWK)?

How does a JWK work?

JSON Web Key Set (JWKS)

See also