Convert JwkSet for "jwks_uri" endpoint

[l3ender]

We are using JJWT for handling signing of our JWTs. We are wanting to expose public key information in a "jwks_uri" as part of our oauth metadata.

We see this repo's readme shows the library's support of JWKs are meant for this very purpose:

For example, an identity web service may expose its RSA or Elliptic Curve Public Keys to 3rd parties in the JWK format.

We are creating a JWK set like following:

PublicKey publicKey = getSigningPublicKey();
PublicJwk<PublicKey> publicJwk = Jwks.builder().key(publicKey).build();
JwkSet jwks = Jwks.set().add(publicJwk).build();

However, we are falling short on how to convert these JJWT objects to the required output mentioned in the JWKS endpoint spec. It seems like reinventing the wheel to manually process the JJWT objects to convert to custom objects for the endpoint response; our guess is there is a way to handle this conversion/output, but we haven't yet found how this is accomplished.

If it makes a difference, we are using ES256 keys (ECDSA using P-256 and SHA-256).

Could someone please advise on how it can be done? Thank you!

[lhazlewood]

Hi @l3ender !

This is a good question, as it may not be readily obvious that JwkSet is an an interface that extends Map<String, Object>, which is intended to reflect that it is ultimately a JSON Object.

All that's necessary is to return the JwkSet instance (jwks in your above code example) directly to the serializer that serializes objects to JSON.

For example, if using Spring Boot, you could have something like:

@RestController
public class TestController {

    @GetMapping(value = "/jwks", produces = "application/jwk-set+json")
    public JwkSet getJwks() {
         PublicKey publicKey = getSigningPublicKey();
         PublicJwk<PublicKey> publicJwk = Jwks.builder().key(publicKey).build();
         JwkSet jwks = Jwks.set().add(publicJwk).build();
         return jwks; // <-- Spring will marshall a Map<String, Object> directly to JSON
    }
}

If not using Spring or something similar, you can use Jackson or your JSON marshaller of choice to do it directly. A quick/easy way to do this is to use JJWT's jjwt-jackson module in compile scope and use the JacksonSerializer directly. For example:

JacksonSerializer serializer = new JacksonSerializer(myApplicationObjectMapper);
serializer.serialize(jwks, httpResponse.getOutputStream());

These are just two quick/rough examples that hopefully gives you some ideas. Basically, anything you use to render JSON from a Map<String,Object> should work by passing the jwks instance directly.

Hopefully that helps, but if not, please let us know!

[l3ender]

Thank you very much for the quick and helpful response!

After your response, we looked through the readme and code closer and see info on the library's JacksonSerializer (#976 was also helpful). We were previously using the more generic approach of serialization using ObjectMapper like so:

(Our application isn't able to expose a direct Spring controller endpoint and is called in such a manner that there is no HttpResponse; it's a gRPC-based app in which we need to generate a JSON string to send to response.)

ObjectMapper mapper; // our application mapper
String jwksJson = mapper.writeValueAsString(jwks);

However, this resulted in the following error and so we thought it wasn't possible:

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: No serializer found for class io.jsonwebtoken.impl.lang.RedactedSupplier and no properties discovered to create BeanSerializer (to avoid exception, disable SerializationFeature.FAIL_ON_EMPTY_BEANS) (through reference chain: io.jsonwebtoken.impl.security.DefaultJwkSet["keys"])

We are able to update our code to the following and have it work:

JacksonSerializer<JwkSet> serializer = new JacksonSerializer<>(mapper);
ByteArrayOutputStream baos = new ByteArrayOutputStream(); // from apache commons-io
serializer.serialize(jwks, baos);
String jwksJson = baos.toString(StandardCharsets.UTF_8); // produces desired output

Looking closer at #976, I think our confusion is the same: we believe it would be more intuitive to have a way to take an existing ObjectMapper instance and be able to configure JJWT related modules onto it (rather than dropping to raw serializer logic). Thoughts?

We're also curious how JJWT is able to work by default in your Spring example: how is Jackson able to serialize the objects if there is no application-wide configuration of JJWT into Spring's ObjectMapper config?

Thanks again!

[lhazlewood]

Ah, dang, I see the problem now, thank you for linking to #976, that was the clue I needed to remember the issue affecting you in this case.

The problem you're seeing is a result of the following:

The RedactedSupplier serialization exception should only surface when encountering private or secret key material (and the ObjectMapper has not been configured with the JJWT module), because that supplier concept helps ensure that private/secret information isn't accidentally leaked in applications. In other words, you want that exception when such secret material is present because it likely means a serialization attempt is happening when you probably don't want it to.

But since you're serializing only public keys, this should never be an issue for you, because all public key information is by its nature, well... public (not confidential) and a RedactedSupplier should not be anywhere in the object graph; you should have been able to pass the JwkSet instance directly to your ObjectMapper, without any additional customization or Jackson module configuration, and it should have 'just worked'.

In an overzealous attempt to default to being as safe as possible, I originally coded the JwkSet implementation to just assume that its internal keys array member is secret as a 'catch-all' just-in-case default, which automatically wraps that value for protection in a RedactedSupplier. As a cross-reference, I mentioned that in this comment in issue #976:

Yes, indeed, and this was intentional at the time it was created. The keys parameter was configured as secret as a 'catch all' to indicate that anything it contains might be confidential, just to be safe and ensure something was not accidentally exposed. In retrospect, looking at this now, that was probably too aggressive a default 😅.

I think we can now change that to setSecret(false) since each JWK within the set should always have its own parameters indicated as confidential or not.

Anyway, I think this discussion would be appropriately addressed by fixing #976, so unless you feel otherwise, I don't believe we need to open another ticket.

I thought of potentially opening another ticket to expose the JJWT Jackson Module available as a public static final constant in case anyone wants to reference it explicitly when configuring their own ObjectMapper. However, thinking through this a little more, doing so could make it a lot easier for an application to accidentally expose Secret or Private JWK material outside of a context that requires it, so I'm not so sure that's a good idea.

In the rare circumstance that an application developer does indeed want to marshal secret/private material outside of their application, I think it's probably better to steer them towards using a dedicated JacksonSerializer that does not use their application-wide ObjectMapper to ensure such module registration is localized only to a very specific security context/scenario.

Consequently, for your specific use case, I'd probably recommend changing your sample code to something like this so your application-wide ObjectMapper isn't changed (apache commons isn't necessary):

// WARNING TO THE CASUAL READER. DO NOT DO THIS IF THE JWK SET CONTAINS PRIVATE OR SECRET KEYS:
// (the output stream's internal buffer and the resulting String will contain secret key material that is not guaranteed to be
// cleared from memory (and Strings are placed in the JVM String table)
JacksonSerializer<JwkSet> serializer = new JacksonSerializer<>(); // do not use the `ObjectMapper` constructor arg, 
java.io.ByteArrayOutputStream baos = new java.io.ByteArrayOutputStream();
serializer.serialize(jwks, baos);
String publicJwksOnlyJson = new String(baos.toByteArray(), StandardCharsets.UTF_8);

Or if you do want to use the JacksonSerializer(ObjectMapper) constructor, it's probably best to use an ObjectMapper instance that is very specific to just this context (e.g. a REST jwks_uri endpoint) instead of application-wide (i.e. to avoid the 'exposing JWK material accidentally' scenario described above).

I hope that helps!

[lhazlewood]

P.S. This fix has been merged to master via 0b34b21. It will be in the upcoming 0.12.7 release.

[l3ender]

Thanks again for the responsive and engaging replies!

I'm looking forward to the release with the change. To confirm, we would be able to use the normal/original ObjectMapper logic to convert the JwkSet to JSON? And that dropping to JacksonSerializer is only needed if the set has private keys but a person still wants the set in JSON--is that correct?

Aside from that, in looking at JWKS endpoint spec, we have a few other observations/questions on converting the JJWT objects to output:

1. For setting the public key "use" parameter to sig for our use case: understanding it might not make sense to automatically configure (because it might not be needed for all scenarios), is there an easy way to set this based on the key being public, or logic from a constant/helper method in the library - asking because we see a isSigUse() method that looks related, as well as a constant in DefaultKeyUseStrategy. It's not hard to use a constant in our application, but if there's an easier/better way to accomplish, we'd want to use.
2. Similarly, for the alg parameter, wouldn't this be able to be set automatically by the key? We see helper method to set algorithm, but in our initial looking we were using it as follows:

   PublicKey publicKey = getSigningPublicKey();
   PublicJwk<PublicKey> publicJwk = Jwks.builder().key(publicKey).algorithm(publicKey.getAlgorithm()).build();

Thanks again!

[lhazlewood]

Thanks again for the responsive and engaging replies!

You're welcome! It's a pleasure when encountering quality questions :)

To confirm, we would be able to use the normal/original ObjectMapper logic to convert the JwkSet to JSON? And that dropping to JacksonSerializer is only needed if the set has private keys but a person still wants the set in JSON--is that correct?

Yep, that's it!

we have a few other observations/questions on converting the JJWT objects to output:

1. For setting the public key "use" parameter to sig for our use case: understanding it might not make sense to automatically configure (because it might not be needed for all scenarios), is there an easy way to set this based on the key being public, or logic from a constant/helper method in the library

asking because we see a isSigUse() method that looks related, as well as a constant in DefaultKeyUseStrategy.

isSigUse() and DefaultKeyUseStrategy are just internal helpers used in internal heuristics trying to determine which kind of key may be encountered. If you have the ability to explicitly configure those values, such as an algorithm ID associated with a key, that's always a better approach.

I agree it would be better if those two values (sig and enc) were reflected in an existing JJWT constant so you didn't need to define them in your application - I can't remember why we didn't expose the internal concepts in the public API. So in the meantime, I'd definitely define constants in your application for the one(s) you're going to use.

Also, from a general security best practice (although not required by any of the JWT RFCs), it's always recommended to reserve keys for a single use case, even if they can technically be used for multiple use cases.

For example, you can do both encryption and digital signatures with an RSA key, but ideally, you would only ever do one of them with one RSA key and the other with a different RSA key, and the same key should never be used for both. Cryptanalysts prefer this to avoid potential exposure associated with unrelated security operations (i.e. if one operation is compromised, the other can be as well, so best to just use dedicated keys for everything).

Based on that, you can decide if you specify key usage metadata with a particular key or not. If it is only used in one scenario, and only ever exposed to jwks_uri clients, I don't think it's a problem to set it on that key at the global level. If however, you use that key internally for more than one thing, I personally would not assign usage metadata at a global level, and instead would create a copy/clone of the public JWK and assign it the relevant usage metadata only at the point/context where it is accessed.

All of that said, I have a different opinion about the use parameter. Unless required by a specification or a server/client exchange, I wouldn't use it: it's limited to one of only two standard String values, it's only really relevant for Public Keys, and it cannot support multiple values, so it's rather inflexible. In my opinion, the key_ops parameter is much better suited to flexibility, and the standard operations intentionally match the Web Cryptography API and X.509 Certificate standards, so they have better foundations IMO, and support more behaviors:

Note that the "key_ops" values intentionally match the "KeyUsage"
values defined in the Web Cryptography API
[W3C.CR-WebCryptoAPI-20141211] specification.

Additionally, JJWT allows you to configure what operations are allowed for any given parsed or constructed key via the KeyOperationPolicy concept. Both JwkBuilder and JwkSetBuilder concepts extend the KeyOperationPolicied interface, which allows them to be configured with policies that enforce any constructed key is 'legal' per standard or application requirements.

Policies can be created using the Jwks.policy() builder, referencing constants in the Jwks.OP class, or by creating new values (via Jwks.OP.builder()).

That said, the use field is simpler, and that has merit, but I don't like the ability to configure two fields that ideally represent the same concepts, albeit slightly differently, so I'd use key_ops if I had a choice. I'd prefer to avoid the inevitable confusion and overlap otherwise. Just my opinion 😉.

2. Similarly, for the alg parameter, wouldn't this be able to be set automatically by the key? We see helper method to set algorithm, but in our initial looking we were using it as follows:

   PublicKey publicKey = getSigningPublicKey();
   PublicJwk<PublicKey> publicJwk = Jwks.builder().key(publicKey).algorithm(publicKey.getAlgorithm()).build();

The JWK alg parameter value is normally expected to be a standard JWA algorithm identifier defined in RFC 7518. publicKey.getAlgorithm() would return a Java Security Standard Name, which isn't recognizable outside of Java applications, so those values wouldn't be recommended.

That said, the reason JJWT doesn't set the JWK alg value based on the specified Java key is that the resulting JWK can possibly be used with multiple algorithm contexts (e.g. an HMAC SHA-512 key can be used for HMAC SHA-256 and HMAC SHA-384). Setting the JWK algorithm to a standard JWA ID should, ideally, 'pin' that key to be used only with that algorithm.

This is ordinarily a very good thing in security contexts - i.e. a key should ideally be used only for a single algorithm. But the JWT RFCs don't mandate this, so JJWT doesn't set it automatically.

I suppose we could set it automatically, and if an application developer wanted to use it with different algorithms, they could remove that value (set the JWK algorithm to null, thereby removing the JSON member), but this behavior wouldn't be backwards compatible and would be best implemented only with additional feedback and testing from the larger JJWT user community.

Thanks again!

Happy to help!

[l3ender]

Great info...thank you very much! We'll definitely look into key_ops as well!