JWKS and JWK selection

When a JSON Web Key Set provider is configured to be used in a mapping, the keys in the set will be consulted when trying to verify a JWS or when decrypting a JWE.

Since there are potentially multiple JWKS and multiple keys per key set, reducing the number of processed keys by filtering is recommended. By doing so, only a selection of keys is processed for the verification or decryption of the given token instead of all available keys.

The gateway uses a 2-stage filtering process to reduce the number of processed keys:

  • Stage 1 – JWKS are filtered by their Issuer information.
  • Stage 2 – The individual keys of the selected JWKS are finally filtered according to their key properties.
 
Info

JSON Web Key Sets (JWKS) can have two sources:

  • They can be locally configured.
  • They can be configured to be dynamically fetched from a remote source using a Service URL.

Stage 1 – JWKS issuer selection

The issuer information is used to restrict the number of JWKS processed for a mapping. Because issuer information is optional, JWKS referenced by a mapping are selected as follows:

  • JWKS without issuer information are always selected.
  • JWKS with issuer information are selected only if the issuer information matches the iss claim of the JWT being processed.

JWKS whose issuer information does not match the iss claim are not considered.

Example

Assume a mapping references four JWKS providers:

  1. Local JWKS with issuer information local_issuer_name
  2. Local JWKS without issuer information
  3. Remotely fetched JWKS with issuer information remote_issuer_name
  4. Remotely fetched JWKS without issuer information

The following request scenarios are possible:

  • JWT with iss == local_issuer_name
    • Selected JWKS: 1, 2, and 4
  • JWT with iss == remote_issuer_name
    • Selected JWKS: 2, 3, and 4
  • JWT without an iss claim
    • Selected JWKS: 2 and 4
  • JWT with an iss claim that does not match any configured issuer information
    • Selected JWKS: 2 and 4

Stage 2 – Property selection mechanism

Using JWK properties, the key selection filter can further reduce the number of keys that have to be tried for the two JWT types JWS and JWE.

Keys are filtered out when:

  • The optional “use” property does not match the JWT type.
  • The optional “key_ops” does not contain the relevant value of the JWT type.
  • The optional “alg” property in its header does not match the “alg” property of the JWT.
  • The JWTs optional “kid” property in its header does not match the keys “kid” property.
 
Notice

The property selection mechanism only uses a limited number of properties specified for JWT.

The following table adds more detailed information about the properties and their possible values:

Property name

Description

Possible values

"use"
  • It states the intended use for the public key.
  • This property is optional.
  • “sig” – for signing or verifying
"key_ops"
  • This property is an array that can have entries of different values.
  • The array values define the key operations that may be performed with that property.
  • This property is optional.

Only two values are relevant:

  • “verify” – to verify JWS'
  • “decrypt” – to decrypt JWEs
"alg"
  • This property specifies the cryptographical algorithm the JWT is intended to be used with.
  • This property is optional.
  • JWE/JWS and JWKs must use the same “alg”-value.
  • JWEs with the “alg” property “dir” require symmetric keys. In addition, the key length must match the “enc” key value of the JWE.
  • Supported JWKS algorithms
"kid"
  • The key ID identifies the key and may be present in the JWT's header.
  • This property is optional.
  • JWE/JWS and JWKs must have the same “kid”.

JWKS format example

A JWKS is a set of JWK and has the following format:

 
Example
{ 
  "keys": <array_of_jwk> 
}

Here is an example with two JWK entries:

 
Example
{ 
  "keys": [ 
    { 
      "kty": "RSA", 
      "n": "AJdfpzpkSaMpiyKgsqbr9n1jpnA12vZy8NntcQgxg-oh8N2Lhmdt0ks3i08s4WC7tod6irhXBwdp5QHyRZDODbIzWtJMOk94vZYp9AKJNpoeqdmbe0zLISmzBanRYRNZhMBkRCQCqob2i3urm-RE09HLTT_wvMxLNFuxwTl_gF3hTK4wcjOLkAky8cDbu0NX[...]", 
      "e": "AQAB", 
      "kid": "iPz_o1_uG8p-RmrpR-MX3dO9lDvwMPjmZ-WEWvLn8QM" 
    }, 
    { 
      "kty": "EC", 
      "x": "APWNl5usaFe3K3O1tQh3bwlQBKgHPuSHZ9O9NvK7uyK2", 
      "y": "HwCd34E8zm0hjnT0c71gBmHv--ABAjFDKBu4dI2-o-w", 
      "crv": "P-256", 
      "kid": "NqFC-b4dDXt3Tmah70rYEkn8JpuPcOS19avwqyRQgqA", 
      "alg": "ES256" 
    } 
  ] 
}