docs: correct auth jwt role requirements

[fairclothjm]

Description

This PR fixes the documentation to clearly state the Auth jwt plugin's behavior. For jwt roles, the bound_audiences parameter is required if the JWT's aud claim is present and must match at least one of the aud claims on the token.

There are a few issues at play here:

• the Auth JWT docs used to clearly mark the expectations. However, this PR incorrectly changed the API doc for bound_audiences.
• In 1.16.3, the plugin fixes a bug and security issue where the aud claim on the token is not checked if it is a string.

References

From https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3

The "aud" (audience) claim identifies the recipients that the JWT is
intended for. Each principal intended to process the JWT MUST
identify itself with a value in the audience claim. If the principal
processing the claim does not identify itself with a value in the
"aud" claim when this claim is present, then the JWT MUST be
rejected.

Relates #27343
Relates #25791

[github-actions]

CI Results:
All Go tests succeeded! ✅

[github-actions]

Build Results:
All builds succeeded! ✅

[thyton]

LGTM. Appreciate you taking this on!

I have one minor comment around clarifying the expected behavior after 1.16.3.

[thyton]

Suggested change

	ignore token `aud` claims that were not a list of strings.
	ignore token `aud` claims that were not a list of strings. Starting from 1.16.3,
	it would ignore token `aud` claims that are not a single audience string or a list of strings.

I think we should state what changed from 1.16.3. My wording might be confusing here.

[fairclothjm]

I think the previous sentence makes that clear. Maybe we can get the education team's input on this? That said, I think your wording should say something like

Starting from 1.16.3, token aud claims can be a single string or a list of strings and they must match at least one of the role's bound_audiences.

But then maybe the next paragraph should be reworked?

cc @schavis

[thyton]

I think saying this could be misleading.

Starting from 1.16.3, token aud claims can be a single string or a list of strings

The value type of aud in JWT claims follows the specification of JWT, which changed to allow string type independently prior to 1.16.3. I believe users had been sending login requests with single string aud. We didn't include that type into our invalidation logic until 1.16.3.

[fairclothjm]

Ok, how about I change the wording of the paragraph to this:

JWT auth roles of type "jwt" require the bound_audiences claim to match at
least one of the JWT's aud claims. The JWT's aud claim can be a single string
or a list of strings as per RFC 7519 Section 4.1.3. Prior to 1.16.3, the JWT auth method
would ignore token aud claims that were not a list of strings.

[thyton]

Looks great!

[fairclothjm]

@schavis I reverted the change to the website/content/docs/upgrading/upgrade-to-1.16.x.mdx file to match the current formatting of the rest of the file. I checked the Vercel preview with the Warning tag and it didn't look correct. It makes it look like the Auth JWT info is part of the LDAP section above it but that isn' the intent. See the attached screenshot:

[fairclothjm]

This PR will need some updates in light of some recent decisions around the code changes. Converting to draft until I get this reworked.

[thyton]

LGTM.