How to parse a RFC7517 JWK Set with JJWT?

[TimmFitschen]

I have an OpenID Connect Certificate endpoint returning the following JSON:

{
  "keys": [
    {
      "kid": "key1",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "jki4-Fw66lIy6oHk_YHLReGkdX3QkiizGUQHGeG_xjQUbwlOFejYm-CsMjWEpZcohX0BQVZomnrMCZC_qjNy-Tg5AIFcQZGXehT4kH_DXQZZR4OgT3uKvEEbMEYhZMPj5Bs9--420ONvCLMTU720UXqSF9IrXsuxtRZuaijwkMpQ2t9nIuJ6NKo_CBJHyeVvfLKN3a83Zi-6It6dkiLsOSvhQfbUAsr0NeKAobwmqGt9lT_K_JoLRVqTzFEC-XT7keobMdT9cKba2ML7Yz982Tr5BuGLXZTm7nfPKdk9Bi68HnO82Aas19_D5HJRieW7FqeqwE5MVl6E3IFt8HKblw",
      "e": "AQAB",
      "x5c": [
        "MIICqTCCAZECBgFxOn9tejANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1hY2FkZW1pY2Nsb3VkMB4XDTIwMDQwMjEwNDQyMVoXDTMwMDQwMjEwNDYwMVowGDEWMBQGA1UEAwwNYWNhZGVtaWNjbG91ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAI5IuPhcOupSMuqB5P2By0XhpHV90JIosxlEBxnhv8Y0FG8JThXo2JvgrDI1hKWXKIV9AUFWaJp6zAmQv6ozcvk4OQCBXEGRl3oU+JB/w10GWUeDoE97irxBGzBGIWTD4+QbPfvuNtDjbwizE1O9tFF6khfSK17LsbUWbmoo8JDKUNrfZyLiejSqPwgSR8nlb3yyjd2vN2YvuiLenZIi7Dkr4UH21ALK9DXigKG8JqhrfZU/yvyaC0Vak8xRAvl0+5HqGzHU/XCm2tjC+2M/fNk6+Qbhi12U5u53zynZPQYuvB5zvNgGrNffw+RyUYnluxanqsBOTFZehNyBbfBym5cCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAJ+N/5p1bzHGgBT45cTe23Q3n0j8xogrJKk0LJLmcZTOU2nkcQhZeL4bpw/7eJasgnXCIMk37Ti8xiZKLPhSrRg0BcNIrKmrtA+2x6jDRIc0DoU3P83fM5h4ShUJAW+aKOx7JpV3E0KkOPzHbCRCB2w7oCleZHG9lJAGkcHAQQ01aIfyU3ow66kdAHyB6sAAnRXMf6aogTguqPVB8uAE3VTAWZDiPwyhqo/IVWDMs73bUty8qLDDj4Ei0Q+DcND3WghyeOGm8lCmAzPgl/zzphkQ6P+4Sq1gW06yfVvj862CuY9i6oBTldtAUvjKxCzl+QS8KzQBnB0oUzaFh8vHKYw=="
      ],
      "x5t": "6yqDA3RjYFZrc3DVcyVrvkNiMA0",
      "x5t#S256": "ifr81ikFJWOiNf2FDgW8dSOu5HEajKuwfGIw78G--Jw"
    },
    {
      "kid": "key2",
      "kty": "RSA",
      "alg": "RS512",
      "use": "sig",
      "n": "kKrdBB_DT37-GT75n_HdOSS0wxXIuheahBdJwTCHmB2Uk3IATjOpiFZjB8qAZ5d00AUu-oZrHG2VgnJq1jUiSb-RDYJTwA1lFXKEJu5CZwAB9xlfCFRXqPs9AL3-2l9-i5ajkMbSE10-S3dacwsrCFd-FL7w0428K7DHjtdwA0mWCyZW6nqWc7lutXhIfFlSmo7GY8M9tuMoOAOXOnLa0MYGh6G1jGvK8pNEyBTnKNEWqAIZhH8ENPMLm4vNFkuenFnP5VzcFNppwt3FnVFetnwudFPfEzUeHqyH7EsdOooFbD4IBu1iWXdI09uGCIJ30BJ2Q-OpXLGMur_YhXMb-Q",
      "e": "AQAB",
      "x5c": [
        "MIICqTCCAZECBgGEexA7YjANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1hY2FkZW1pY2Nsb3VkMB4XDTIyMTExNTExMzExMloXDTMyMTExNTExMzI1MlowGDEWMBQGA1UEAwwNYWNhZGVtaWNjbG91ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJCq3QQfw09+/hk++Z/x3TkktMMVyLoXmoQXScEwh5gdlJNyAE4zqYhWYwfKgGeXdNAFLvqGaxxtlYJyatY1Ikm/kQ2CU8ANZRVyhCbuQmcAAfcZXwhUV6j7PQC9/tpffouWo5DG0hNdPkt3WnMLKwhXfhS+8NONvCuwx47XcANJlgsmVup6lnO5brV4SHxZUpqOxmPDPbbjKDgDlzpy2tDGBoehtYxryvKTRMgU5yjRFqgCGYR/BDTzC5uLzRZLnpxZz+Vc3BTaacLdxZ1RXrZ8LnRT3xM1Hh6sh+xLHTqKBWw+CAbtYll3SNPbhgiCd9ASdkPjqVyxjLq/2IVzG/kCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAQ4kzB7EwhUTGSr/IpAQa+viF7uYGxk+Iiec/s+ShfkFLoMPw+y9l5alwvnKAgTI1Pxrjha8Hu2OsCtGtu8ziJNd65VQiNoFsZp71WGq0+7+Zcqmk182CmjqoN+io7yfgg7N5/VygquHIY3aNB4riruQrbR33fQ49mjpZIM2eohU1teycfpwPCObTRGg5jZg+iUREy01k+QZplxgOqgyqrtTDUKoxZr8WwAWjlCBWyylOT5eEA/777yObYogmfrpNovo+dw1szaHB4BGfX1S522UUfRDAMtOTsjfCnusYEZsMUWXJe46ZLSYJsmIpGw4UwSC7I371elrC/dTzCSREpQ=="
      ],
      "x5t": "PwDhZrjmydYTXbB3skSdfamw5Xk",
      "x5t#S256": "44mNK5ARKWGn8S7R0tfEeJ6SVqpLp73VSeQeG2wMATE"
    }
  ]
}

I assume this is a RFC7517 JWK Set.

I am trying to parse this as a io.jsonwebtoken.security.JwkSet using the Gson deserializer implementation.

Maven dependencies:

    <dependency>
      <groupId>io.jsonwebtoken</groupId>
      <artifactId>jjwt-api</artifactId>
      <version>0.12.6</version>
    </dependency>
    <dependency>
      <groupId>io.jsonwebtoken</groupId>
      <artifactId>jjwt-impl</artifactId>
      <version>0.12.6</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.jsonwebtoken</groupId>
      <artifactId>jjwt-gson</artifactId>
      <version>0.12.6</version>
      <scope>runtime</scope>
    </dependency>

However, this test fails:

  @Test
  void testJwkSetParsing() {
    String jwkSetJson =
        "{'keys':[{'kid':'key1','kty':'RSA','alg':'RS256','use':'sig','n':'jki4-Fw66lIy6oHk_YHLReGkdX3QkiizGUQHGeG_xjQUbwlOFejYm-CsMjWEpZcohX0BQVZomnrMCZC_qjNy-Tg5AIFcQZGXehT4kH_DXQZZR4OgT3uKvEEbMEYhZMPj5Bs9--420ONvCLMTU720UXqSF9IrXsuxtRZuaijwkMpQ2t9nIuJ6NKo_CBJHyeVvfLKN3a83Zi-6It6dkiLsOSvhQfbUAsr0NeKAobwmqGt9lT_K_JoLRVqTzFEC-XT7keobMdT9cKba2ML7Yz982Tr5BuGLXZTm7nfPKdk9Bi68HnO82Aas19_D5HJRieW7FqeqwE5MVl6E3IFt8HKblw','e':'AQAB','x5c':['MIICqTCCAZECBgFxOn9tejANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1hY2FkZW1pY2Nsb3VkMB4XDTIwMDQwMjEwNDQyMVoXDTMwMDQwMjEwNDYwMVowGDEWMBQGA1UEAwwNYWNhZGVtaWNjbG91ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAI5IuPhcOupSMuqB5P2By0XhpHV90JIosxlEBxnhv8Y0FG8JThXo2JvgrDI1hKWXKIV9AUFWaJp6zAmQv6ozcvk4OQCBXEGRl3oU+JB/w10GWUeDoE97irxBGzBGIWTD4+QbPfvuNtDjbwizE1O9tFF6khfSK17LsbUWbmoo8JDKUNrfZyLiejSqPwgSR8nlb3yyjd2vN2YvuiLenZIi7Dkr4UH21ALK9DXigKG8JqhrfZU/yvyaC0Vak8xRAvl0+5HqGzHU/XCm2tjC+2M/fNk6+Qbhi12U5u53zynZPQYuvB5zvNgGrNffw+RyUYnluxanqsBOTFZehNyBbfBym5cCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAJ+N/5p1bzHGgBT45cTe23Q3n0j8xogrJKk0LJLmcZTOU2nkcQhZeL4bpw/7eJasgnXCIMk37Ti8xiZKLPhSrRg0BcNIrKmrtA+2x6jDRIc0DoU3P83fM5h4ShUJAW+aKOx7JpV3E0KkOPzHbCRCB2w7oCleZHG9lJAGkcHAQQ01aIfyU3ow66kdAHyB6sAAnRXMf6aogTguqPVB8uAE3VTAWZDiPwyhqo/IVWDMs73bUty8qLDDj4Ei0Q+DcND3WghyeOGm8lCmAzPgl/zzphkQ6P+4Sq1gW06yfVvj862CuY9i6oBTldtAUvjKxCzl+QS8KzQBnB0oUzaFh8vHKYw=='],'x5t':'6yqDA3RjYFZrc3DVcyVrvkNiMA0','x5t#S256':'ifr81ikFJWOiNf2FDgW8dSOu5HEajKuwfGIw78G--Jw'},{'kid':'key2','kty':'RSA','alg':'RS512','use':'sig','n':'kKrdBB_DT37-GT75n_HdOSS0wxXIuheahBdJwTCHmB2Uk3IATjOpiFZjB8qAZ5d00AUu-oZrHG2VgnJq1jUiSb-RDYJTwA1lFXKEJu5CZwAB9xlfCFRXqPs9AL3-2l9-i5ajkMbSE10-S3dacwsrCFd-FL7w0428K7DHjtdwA0mWCyZW6nqWc7lutXhIfFlSmo7GY8M9tuMoOAOXOnLa0MYGh6G1jGvK8pNEyBTnKNEWqAIZhH8ENPMLm4vNFkuenFnP5VzcFNppwt3FnVFetnwudFPfEzUeHqyH7EsdOooFbD4IBu1iWXdI09uGCIJ30BJ2Q-OpXLGMur_YhXMb-Q','e':'AQAB','x5c':['MIICqTCCAZECBgGEexA7YjANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1hY2FkZW1pY2Nsb3VkMB4XDTIyMTExNTExMzExMloXDTMyMTExNTExMzI1MlowGDEWMBQGA1UEAwwNYWNhZGVtaWNjbG91ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJCq3QQfw09+/hk++Z/x3TkktMMVyLoXmoQXScEwh5gdlJNyAE4zqYhWYwfKgGeXdNAFLvqGaxxtlYJyatY1Ikm/kQ2CU8ANZRVyhCbuQmcAAfcZXwhUV6j7PQC9/tpffouWo5DG0hNdPkt3WnMLKwhXfhS+8NONvCuwx47XcANJlgsmVup6lnO5brV4SHxZUpqOxmPDPbbjKDgDlzpy2tDGBoehtYxryvKTRMgU5yjRFqgCGYR/BDTzC5uLzRZLnpxZz+Vc3BTaacLdxZ1RXrZ8LnRT3xM1Hh6sh+xLHTqKBWw+CAbtYll3SNPbhgiCd9ASdkPjqVyxjLq/2IVzG/kCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAQ4kzB7EwhUTGSr/IpAQa+viF7uYGxk+Iiec/s+ShfkFLoMPw+y9l5alwvnKAgTI1Pxrjha8Hu2OsCtGtu8ziJNd65VQiNoFsZp71WGq0+7+Zcqmk182CmjqoN+io7yfgg7N5/VygquHIY3aNB4riruQrbR33fQ49mjpZIM2eohU1teycfpwPCObTRGg5jZg+iUREy01k+QZplxgOqgyqrtTDUKoxZr8WwAWjlCBWyylOT5eEA/777yObYogmfrpNovo+dw1szaHB4BGfX1S522UUfRDAMtOTsjfCnusYEZsMUWXJe46ZLSYJsmIpGw4UwSC7I371elrC/dTzCSREpQ=='],'x5t':'PwDhZrjmydYTXbB3skSdfamw5Xk','x5t#S256':'44mNK5ARKWGn8S7R0tfEeJ6SVqpLp73VSeQeG2wMATE'}]}"
            .replace("'", "\"");
    JwkSet jwkSet = Jwks.setParser().build().parse(jwkSetJson);
    assertNotEquals("keys", String.join("", jwkSet.keySet()));
    assertTrue(jwkSet.containsKey("key1"));
    assertTrue(jwkSet.containsKey("key2"));
    assertEquals(2, jwkSet.keySet().size());
  }

Apparently, it parses the "keys" attribute as the key id and doesn't recognize that the keys to be parsed are in the array.

Am I using the JJWT library in a wrong way?
Is my jwkSetJson not RFC7517 compliant?
Is this a bug in JJWT?

[lhazlewood]

Hi @TimmFitschen !

There's a minor error in how thetestJwkSetParsing() method is written, and it's likely due to an easy-to-confuse difference between RFC 7517 JSON idioms and Java Map and Set idioms.

(Please excuse the depth of detail below, I'm writing it for any future casual reader that might come across this question regardless of their Java experience).

An RFC 7517 JWK Set is not itself directly a JSON list/array/set of JWKs. It is technically a JSON Object (what we would call in Java a 'map') that has a JSON keys member, and that keys member is itself indeed a JSON array of JWK elements.

The reason for this is that a JSON array has no direct capability of representing metadata for its elements. So a common approach in JSON design (and what the RFC authors chose) is to 'wrap' the array with a JSON Object that can have other members, some of which can have metadata about the array. For example, a JWK Set publisher (e.g. OpenID provider) could publish something like this if they wanted:

{
  "keys": [ {jwk1}, {jwk2}, ..., {jwk8} ],
  "size": 8, // actual count of jwks in the `keys` array
  "href": "https://somewhere.com/openid/jwks/18340239", // link to this JWK Set for repeated retrieval
  "exp": "2025-08-24T12:30:45Z", // unavailable after this point
  "whatever": "anything else that's custom"
}

As you can see, there is the required nested keys member, but there are others that could be helpful to the consumer of the JWK Set JSON document if the publisher desired to include those things. In practice, many (most?) OpenID publishers don't include anything extra beyond the keys member, but it is possible if they chose to do so, which is why it's a JSON Object and not a direct array.

So now for the likely idiom confusion:

JJWT accurately models each of its Java types to be identical to the RFC definitions, which are usually JSON Objects. That means each JJWT type usually extends Map<String, ?> to reflect that the type is, first and foremost a map of RFC-defined JSON key-value pairs, with a bunch of nice type-safe helper methods to facilitate type-safe programming. But you could always still interact with the JJWT object as just a Map<String, ?> if you wanted.

So that means a JJWT JwkSet extends Map<String, ?>.

Bringing that back to the test case, look at the call to jwkSet.keySet():

// ...
assertNotEquals("keys", String.join("", jwkSet.keySet())); // <--- 
// ...

The .keySet() call is defined in the Map interface to return all the keys of the map key/value entry pairs, not any JWK concepts.

In your test JSON, there is only one map key, and that's the keys member. So jwkSet.keySet() above, when printed via toString, just returns the string literal:

[keys]

Using my example JSON above, with all the additional metadata / peer members, jwkSet.keySet() would print instead:

[keys,size,href,exp,whatever]

Now that we know what's going on, you could re-write the test as follows:

var json =  "{'keys':[{'kid':'key1','kty':'RSA','alg':'RS256','use':'sig','n':'jki4-Fw66lIy6oHk_YHLReGkdX3QkiizGUQHGeG_xjQUbwlOFejYm-CsMjWEpZcohX0BQVZomnrMCZC_qjNy-Tg5AIFcQZGXehT4kH_DXQZZR4OgT3uKvEEbMEYhZMPj5Bs9--420ONvCLMTU720UXqSF9IrXsuxtRZuaijwkMpQ2t9nIuJ6NKo_CBJHyeVvfLKN3a83Zi-6It6dkiLsOSvhQfbUAsr0NeKAobwmqGt9lT_K_JoLRVqTzFEC-XT7keobMdT9cKba2ML7Yz982Tr5BuGLXZTm7nfPKdk9Bi68HnO82Aas19_D5HJRieW7FqeqwE5MVl6E3IFt8HKblw','e':'AQAB','x5c':['MIICqTCCAZECBgFxOn9tejANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1hY2FkZW1pY2Nsb3VkMB4XDTIwMDQwMjEwNDQyMVoXDTMwMDQwMjEwNDYwMVowGDEWMBQGA1UEAwwNYWNhZGVtaWNjbG91ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAI5IuPhcOupSMuqB5P2By0XhpHV90JIosxlEBxnhv8Y0FG8JThXo2JvgrDI1hKWXKIV9AUFWaJp6zAmQv6ozcvk4OQCBXEGRl3oU+JB/w10GWUeDoE97irxBGzBGIWTD4+QbPfvuNtDjbwizE1O9tFF6khfSK17LsbUWbmoo8JDKUNrfZyLiejSqPwgSR8nlb3yyjd2vN2YvuiLenZIi7Dkr4UH21ALK9DXigKG8JqhrfZU/yvyaC0Vak8xRAvl0+5HqGzHU/XCm2tjC+2M/fNk6+Qbhi12U5u53zynZPQYuvB5zvNgGrNffw+RyUYnluxanqsBOTFZehNyBbfBym5cCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAJ+N/5p1bzHGgBT45cTe23Q3n0j8xogrJKk0LJLmcZTOU2nkcQhZeL4bpw/7eJasgnXCIMk37Ti8xiZKLPhSrRg0BcNIrKmrtA+2x6jDRIc0DoU3P83fM5h4ShUJAW+aKOx7JpV3E0KkOPzHbCRCB2w7oCleZHG9lJAGkcHAQQ01aIfyU3ow66kdAHyB6sAAnRXMf6aogTguqPVB8uAE3VTAWZDiPwyhqo/IVWDMs73bUty8qLDDj4Ei0Q+DcND3WghyeOGm8lCmAzPgl/zzphkQ6P+4Sq1gW06yfVvj862CuY9i6oBTldtAUvjKxCzl+QS8KzQBnB0oUzaFh8vHKYw=='],'x5t':'6yqDA3RjYFZrc3DVcyVrvkNiMA0','x5t#S256':'ifr81ikFJWOiNf2FDgW8dSOu5HEajKuwfGIw78G--Jw'},{'kid':'key2','kty':'RSA','alg':'RS512','use':'sig','n':'kKrdBB_DT37-GT75n_HdOSS0wxXIuheahBdJwTCHmB2Uk3IATjOpiFZjB8qAZ5d00AUu-oZrHG2VgnJq1jUiSb-RDYJTwA1lFXKEJu5CZwAB9xlfCFRXqPs9AL3-2l9-i5ajkMbSE10-S3dacwsrCFd-FL7w0428K7DHjtdwA0mWCyZW6nqWc7lutXhIfFlSmo7GY8M9tuMoOAOXOnLa0MYGh6G1jGvK8pNEyBTnKNEWqAIZhH8ENPMLm4vNFkuenFnP5VzcFNppwt3FnVFetnwudFPfEzUeHqyH7EsdOooFbD4IBu1iWXdI09uGCIJ30BJ2Q-OpXLGMur_YhXMb-Q','e':'AQAB','x5c':['MIICqTCCAZECBgGEexA7YjANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1hY2FkZW1pY2Nsb3VkMB4XDTIyMTExNTExMzExMloXDTMyMTExNTExMzI1MlowGDEWMBQGA1UEAwwNYWNhZGVtaWNjbG91ZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJCq3QQfw09+/hk++Z/x3TkktMMVyLoXmoQXScEwh5gdlJNyAE4zqYhWYwfKgGeXdNAFLvqGaxxtlYJyatY1Ikm/kQ2CU8ANZRVyhCbuQmcAAfcZXwhUV6j7PQC9/tpffouWo5DG0hNdPkt3WnMLKwhXfhS+8NONvCuwx47XcANJlgsmVup6lnO5brV4SHxZUpqOxmPDPbbjKDgDlzpy2tDGBoehtYxryvKTRMgU5yjRFqgCGYR/BDTzC5uLzRZLnpxZz+Vc3BTaacLdxZ1RXrZ8LnRT3xM1Hh6sh+xLHTqKBWw+CAbtYll3SNPbhgiCd9ASdkPjqVyxjLq/2IVzG/kCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAQ4kzB7EwhUTGSr/IpAQa+viF7uYGxk+Iiec/s+ShfkFLoMPw+y9l5alwvnKAgTI1Pxrjha8Hu2OsCtGtu8ziJNd65VQiNoFsZp71WGq0+7+Zcqmk182CmjqoN+io7yfgg7N5/VygquHIY3aNB4riruQrbR33fQ49mjpZIM2eohU1teycfpwPCObTRGg5jZg+iUREy01k+QZplxgOqgyqrtTDUKoxZr8WwAWjlCBWyylOT5eEA/777yObYogmfrpNovo+dw1szaHB4BGfX1S522UUfRDAMtOTsjfCnusYEZsMUWXJe46ZLSYJsmIpGw4UwSC7I371elrC/dTzCSREpQ=='],'x5t':'PwDhZrjmydYTXbB3skSdfamw5Xk','x5t#S256':'44mNK5ARKWGn8S7R0tfEeJ6SVqpLp73VSeQeG2wMATE'}]}"
                .replace("'", "\"");
        JwkSet jwks = Jwks.setParser().build().parse(json);
        assert "[keys]".equals(String.join("", jwks.keySet()));
        var elements = jwks.getKeys().stream().toList();
        assert elements.get(0).getId().equals("key1");
        assert elements.get(1).getId().equals("key2");
        assert 2 == elements.size();

I hope that helps! Please feel free to follow up with any other questions, or kindly mark the question as answered. Thanks!

[TimmFitschen]

Thanks a lot! One minor remark (I think):

That test still fails for me. I think the containsKey is Java idiom of the Map, so it's true for "kid" not for "key1". This works for me. If you update your answer, I'll accept.

- assert elements.get(0).containsKey("key1");
+ assert elements.get(0).getId().equals("key1");

[lhazlewood]

Thanks a lot! One minor remark (I think):

That test still fails for me. I think the containsKey is Java idiom of the Map, so it's true for "kid" not for "key1". This works for me. If you update your answer, I'll accept.

- assert elements.get(0).containsKey("key1");
+ assert elements.get(0).getId().equals("key1");

Ah, yes, I mistyped that in my local testing - good catch!