A single audience value gets converted into a set with one entry

[devdanylo]

Describe the bug

In the scenario when we first build claims with DefaultClaimsBuilder and then pass them to JwtBuilder, a single audience value gets converted somewhere on the way from String to Set<String>. This is a breaking change for the APIs, which expect a string audience value.

To Reproduce
Steps to reproduce the behavior:

1. Build claims:

var claims = new DefaultClaimsBuilder().audience().single("https://login.salesforce.com").build();

2. Check the type of the claim value of in Debugger (must be String):
   
3. Create a JWT builder with the claims object:

var jwtBuilder = Jwts.builder().claims(claims);

4. Check again the type of the claim value in Debugger (see jwtBuilder; this time it's Set<String>):
   

Expected behavior
In case of using audience().single(...) the type of the audience claim should stay String after calling claims(...) on the JWT builder.

Workaround
Note, if setting the claim directly on the JWT builder, the type is preserved:

var jwtBuilder = Jwts.builder().audience().single("https://login.salesforce.com");

[lhazlewood]

Just for some background context for the current (0.12.0+) behavior:

The single-string audience claim was implemented in JJWT before JWT RFC 7519 was finalized, and the RFC draft spec used at the time when implementing JJWT said aud was a single StringOrURI value, e.g. see RFC 7519, draft 5, section 4.1.5

The RFC spec committee later changed the aud data type to be, in the general/normal/standard case a JSON array of StringOrURI values, but then they said it may also be a single StringOrURI (non-array) value, presumably to ensure existing usages could still be supported. See the now-finalized RFC 7519, Section 4.1.3.

This poses a frustrating challenge for Java libraries that are strongly-typed, where people don't like their data types changing randomly.

So, starting in 0.12.0, we added the .audience() builder to help support this odd 'type-changing' use case, and the parser will always 'normalize' a single value into a Set<String> so the app developer doesn't have to perform weird type conversion logic/checks in their application code.

Based on the reported behavior, the problem at the moment is that the .claims(claims) method - which is called after using an .audience() builder - treats the object as a Map<String,?>, and just uses standard claim-to-value logic for each Map entry, and the standard behavior is to treat aud as a JSON array per the finalized RFC.

In other words, the 'last call wins' as to the behavior seen.

Based on this it seems as if generic claim, put, putAll logic should explicitly check for the aud special case, and if a single string, delegate the .audience().single(String) method instead of the simple map direct 'put'.

As you've indicated, there is a workaround for this for applications - just call the .audience() builder after general claims are set, but I do understand how that's less desirable than it 'just working' regardless of method call order.

We'll use this ticket to track the work to implement this special case logic. Thank you for opening it!

[gomesar9]

Sorry but, I don't get how can I build a JWT with a single String AUD. Is it possible now? or just legacy copy supports?

[lhazlewood]

Sorry but, I don't get how can I build a JWT with a single String AUD. Is it possible now? or just legacy copy supports?

@gomesar9 It's possible in JJWT 0.12.4 and later via:

Jwts.builder().claims().audience().single("test").and()...

[gomesar9]

Oh, okay. My editor still point it as "deprecated".
I've tried with .put("aud", "test") and work for now, but I will use the designed method.
Thanks for your time.

[lhazlewood]

Oh, okay. My editor still point it as "deprecated".

It is indeed deprecated to discourage its use; application developers shouldn't be using the single String value approach anymore - it was a legacy behavior and the finalized RFC recommends a String array.

Ideally all applications should change to the String array approach when possible because 1) it is more flexible, allowing multiple recipients and 2) reduces complexity since recipients would no longer need to always perform the "Is it a String? Or array of Strings?" type conversion/checking logic.