Proposal: Add JWT audience in security scheme

[emmanuelgautier]

As described in the JWT RFC and in the OpenId Connect spec for example, audience must be verified.

A client can request the audience during an OAuth 2.0 authorization flow, so having audience in the OpenAPI can be convenient. This audience documentation can also be used to add more documentation about the API security strategy and ensure the security is enforced.

[darrelmiller]

This would be a good suggestion to trial as an x- to see the demand for this and the value it can bring. It would also be good to bring this proposal along with other JWT related issues.

[handrews]

@emmanuelgautier since @darrelmiller suggested trying this out as an x- field first, I'm going to close this for now. There is an issue already tracking this topic:

• Clarification on JWT Bearer access token from OAuth2 Client Credentials Grant... sig-security#29

which mentions an x-audience, so if that's already being done and there's evidence that it's being used and working, please feel free to re-submit this PR and point to where it's being used. We will also keep the issue open for consideration in 3.2 or some later 3.x with other JWT issues, as we have several that have been filed. But it does not seem like there's enough consensus to add this to the spec yet.

[emmanuelgautier]

Thanks @darrelmiller and @handrews both for your review and sorry if I missed a submission process. This is my first contribution to the spec.

As suggested, more comments will be added then in the following issue about tokens here: OAI/sig-security#29.

[handrews]

@emmanuelgautier no worries about missing the process- we're coming out of a bit of a hibernation period and we're working on documenting our current processes through our Contributor Guidance Project. So you didn't miss anything that you should have been able to figure out right now- we're working on it!