"audience" behaviour of JwtSecurityToken, JwtPayload confusing

[mgillis]

Due to these lines:

azure-activedirectory-identitymodel-extensions-for-dotnet/src/System.IdentityModel.Tokens.Jwt/JwtPayload.cs

Lines 115 to 117 in cc6d48f

	// if could be the case that some of the claims above had an 'aud' claim;
	if (!string.IsNullOrEmpty(audience))
	AddClaim(new Claim(JwtRegisteredClaimNames.Aud, audience, ClaimValueTypes.String));

The behaviour can be confusing, and some implementations of refresh tokens that I have seen (and is promulgated in a few tutorials out there) will pass in issuer, audience, etc., along with previous claims (from a deserialized JwtSecurityToken) to the JwtSecurityToken constructor. The resulting new token will have everything overwritten except for the audience claim, which will be a list with one new element added.

To be more clear:
If you call the constructor once with audience = "users", and claims = null, everything is fine;
If you call the constructor a second time with audience = "users" and claims including { "aud", "users" } you will end up with { "aud", ["users, "users'] }. etc.
After many refreshes of a long-lasting chain of tokens, the "aud" list can be very, very long, eventually causing problems (e.g. HTTP header size too big)

I am not saying the implementation is incorrect, and it's clear in the RFC that aud can be a list, but I suggest the documentation should be improved to clarify this behaviour. For example, instead of "a claim will be added", you could write "a claim will be added, appended to any 'aud' claims already in 'claims', if present."

The three places this documentation is copied are:

azure-activedirectory-identitymodel-extensions-for-dotnet/src/System.IdentityModel.Tokens.Jwt/JwtPayload.cs

Line 80 in cc6d48f

/// <param name="audience">If this value is not null, a { aud, 'audience' } claim will be added</param>

azure-activedirectory-identitymodel-extensions-for-dotnet/src/System.IdentityModel.Tokens.Jwt/JwtPayload.cs

Line 67 in cc6d48f

/// <param name="audience">If this value is not null, a { aud, 'audience' } claim will be added</param>

azure-activedirectory-identitymodel-extensions-for-dotnet/src/System.IdentityModel.Tokens.Jwt/JwtSecurityToken.cs

Line 193 in cc6d48f

/// <param name="audience">If this value is not null, a { aud, 'audience' } claim will be added</param>