Overview#
JWK Set is a
JSON Object that represents a set of
JSON Web Keys (
JWKs).
JWK Set is a
REQUIRED metadata entry for
OpenID Connect Discovery expressed as a
URI for the
OpenID Connect Identity Provider (IDP)'s
JWK Set document. This contains the signing key(s) the
Relying Party uses to validate signatures from the
OpenID Connect Identity Provider (IDP).
JWK Set for the
OAuth Clientt's
JWK Set (
JWK) document. If the
OAuth Client signs requests to the
Server, it contains the signing key(s) the Server uses to validate signatures from the
OAuth Client. The JWK Set
MAY also contain the
OAuth Client's
JWE keys(s), which are used by the
Server to encrypt
responses to the
OAuth Client.
The
JWK Set MAY also contain the
OpenID Connect Identity Provider (IDP)'s
encryption key(s), which are used by
Relying Partys to encrypt requests to the
OpenID Connect Identity Provider (IDP). When both
JSON Web Signature and
JSON Web Encryption keys are made available, a use (Key Use) parameter value is
REQUIRED for all keys in the referenced
JSON Web Key Set to indicate each key's intended usage.
Although some algorithms allows for the same key to be used for both
JWS and
JWE, doing so is
NOT RECOMMENDED, as it is less secure.
The
JWK x5c parameter
MAY be used to provide X.509 representations of keys provided. When used, the bare key values
MUST still be present and
MUST match those in the
certificate.
The JWK Set JSON Object MUST have a "keys" member, with its value being an JSONArray of JWKs. This JSON object MAY contain whitespace and/or line breaks.
The member names within a JWK Set MUST be unique; JWK Set parsers MUST either reject JWK Sets with duplicate member names or use a JSON parser that returns only the lexically last duplicate member name, as specified in Section 15.12 ("The JSON Object") of ECMAScript 5.1 ECMAScript.
keys" Parameter#
The value of the "keys" parameter is an array of
JSON Web Keys (JWK) values. By default, the order of the
JWK values within the array does not imply an order of preference among them, although applications of JWK Set can choose to assign a meaning to the order for their purposes, if desired.
"kty" (Key Type) Parameter MUST#
The "kty" (key type) parameter identifies the
cryptographic algorithm family used with the key, such as "RSA" or "EC". "kty" values should either be registered in the
IANA Registry "
JSON Web Key Types" established by
JWA or be a value that contains a
Collision-Resistant Name. The "kty" value is a
case-sensitive string. This member
MUST be present in a
JWK.
A list of defined "kty" values can be found in the IANA "JSON Web Key Types" registry established by JWA; the initial contents of this registry are the values defined in Section 6.1 of JWA.
"use" (Public Key Use) Parameter#
The "use" (public key use) parameter identifies the intended use of the public key. The "use" parameter is employed to indicate whether a public key is used for encrypting data or verifying the signature on data.
Values defined by this specification are:
- "sig" (signature)
- "enc" (encryption)
Other values MAY be used. The "use" value is a case-sensitive string. Use of the "use" member is OPTIONAL, unless the application requires its presence.
"key_ops" (Key Operations) Parameter#
The "key_ops" (key operations) parameter identifies the operation(s) for which the key is intended to be used. The "key_ops" parameter is intended for use cases in which public, private, or symmetric keys may be present.
Its value is an array of key operation values. Values defined by RFC 7515 are:
- "sign" (compute digital signature or MAC)
- "verify" (verify digital signature or MAC)
- "encrypt" (encrypt content)
- "decrypt" (decrypt content and validate decryption, if applicable)
- "wrapKey" (encrypt key)
- "unwrapKey" (decrypt key and validate decryption, if applicable)
- "deriveKey" (derive key)
- "deriveBits" (derive bits not to be used as a key)
(Note that the "key_ops" values intentionally match the "KeyUsage" values defined in the Web Cryptography API
W3C.CR-WebCryptoAPI-20141211 specification.)
The "alg" (
algorithm) parameter identifies the
algorithm intended for use with the key. The values used should either be registered in the
IANA "
JSON Web Signature and Encryption Algorithms" registry established by
JWA or be a value that contains a
Collision-Resistant Name. The "
alg" value is a
case-sensitive ASCII string. Use of this member is
OPTIONAL.
"kid" (Key ID) Parameter#
The "kid" (key ID) parameter is used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover. The structure of the "kid" value is unspecified. When "kid" values are used within a JWK Set, different keys within the JWK Set SHOULD use distinct "kid" values. (One example in which different keys might use the same "kid" value is if they have different "kty" (key type) values but are considered to be equivalent alternatives by the application using them.) The "kid" value is a
case-sensitive string. Use of this member is OPTIONAL.
When used with JWS or JWE, the "kid" value is used to match a JWS or JWE "kid" Header Parameter value.
The "x5u" (X.509 URL) parameter is a URI
RFC 3986 that refers to a resource for an X.509
Public Key certificate or
certificate Chain RFC 5280. The identified resource
MUST provide a representation of the
certificate or
certificate Chain that conforms to RFC 5280
RFC 5280 in
PEM-encoded form, with each
certificate delimited as specified in Section 6.1 of RFC 4945
RFC 4945. The key in the first
certificate MUST match the
public Key represented by other members of the
JWK. The protocol used to acquire the resource
MUST provide
integrity protection; an
HTTP GET request to retrieve the certificate
MUST use
TLS RFC 2818 RFC 5246; the identity of the server
MUST be validated, as per Section 6 of RFC 6125
RFC 6125. Use of this member is OPTIONAL.
The "x5c" (
X.509 certificate Chain) parameter contains a chain of one or more PKIX certificates
RFC 5280. The
Certificate Chain is represented as a
JSON array of certificate value strings. Each string in the array is a base64-encoded (Section 4 of
RFC 4648 -- not base64url-encoded) DER
ITU.X690.1994 PKIX certificate value.
The PKIX certificate containing the key value MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The key in the first certificate MUST match the public key represented by other members of the JWK. Use of this member is OPTIONAL.
"x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter#
The "x5t" (
X.509 certificate SHA-1 thumbprint) parameter is a
base64url-encoded
SHA-1 thumbprint (a.k.a. digest) of the
DER encoding of an
X.509 certificate RFC 5280. Note that certificate thumbprints are also sometimes known as certificate fingerprints.
The key in the certificate MUST match the public Key represented by other members of the JWK. Use of this member is OPTIONAL.
There might be more information for this subject on one of the following: