Clarification on JWT Bearer access token from OAuth2 Client Credentials Grant...

[cadethacker]

Hello,
First time building a spec with OpenAPI and appreciate the thoughtfulness of this spec. The changes in OpenAPI3 are really nice.

I'm lost on one point: The endpoints will be secured via Bearer JWT token, that was retrieved via OAuth2 Client Credentials grant. The JWT token will contain a correct audience and optional scopes for more granular authorization. The audience is properly validated when requested and rejected if not authorized already.

Reading this very closely and have some question/clarification, apologies if these are basic :D Be nice, I'm new :D
https://swagger.io/docs/specification/authentication/

Clarification 1. This page above shows a security scheme for both Bearer token AND OAuth2, but to me, those don't feel like different things. They feel like the same thing. The client uses OAuth2 Client Credentials grant to get the jwt access token (aka bearer token) , and passes it on the Authorization header to the API which validates it. So do I put both security schemes? At this point, just leaning toward bearer token. But it is OAuth2.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#jwt-bearer-sample

Clarification 2. The audience claim in the JWT is a key. We require the API, but also envoy (among many other in transit systems) to check the audience. But I am not sure where to specify this except in the comments in the top as to what the value of the audience is required to be. Can I use an extension? I have not quite wrapped my head around those yet... but working on it. x-audience?

https://tools.ietf.org/html/rfc7519#section-4.1.3
https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter#config-http-filters-jwt-authn

Clarification 3. If I need to specify the OAuth2 section the authorizationUrl but that changes per lifecycle. I knew so maybe this is obvious, but not sure how to specify different values per lifecycles. Just two really, QA and PR.

Clarification 4. Is there a spot to list the JWKS? is that what the x-jwks-token-keys maybe?

Anyway, huge thanks! Love the work you all have done. I just hate guessing on stuff like this and figured quicker to ask and get clarification than, guess and get it wrong.

[handrews]

See also:

• Proposal: Add JWT audience in security scheme #3286

which was only closed because it was suggested to try an x-audience field before adding something to 3.2. The closure is not a rejection on the merits!

Here is @emmanuelgautier's PR comment:

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.

[emmanuelgautier]

@cadethacker All different security scheme properties have not impact on security verification. For example, using an OAuth2 Client Credentials or an Authorization Code (with PKCE) flow may have no impact on how you want to verify the token issued if you do not care about the token subject.

However, this security scheme can help to improve documentation and share information with the API consumer on how to obtain API authentication tokens.

Clarification 3. If I need to specify the OAuth2 section the authorizationUrl but that changes per lifecycle. I knew so maybe this is obvious, but not sure how to specify different values per lifecycles. Just two really, QA and PR.

What do you mean about lifecycles?

Clarification 4. Is there a spot to list the JWKS? is that what the x-jwks-token-keys maybe?

If the OpenID Connect Discovery endpoint is filled, this information may be retrieved from this endpoint. In other cases, this field could be added in the Spec as well.

About audience field and the previous JWKS URI, those informations are missing from the specs.

In order to share if this information is used for now, here are some examples with GCP and AWS API Gateway authentication based on OpenAPI files:

• https://cloud.google.com/api-gateway/docs/authenticating-users-jwt (x-google-audiences, x-google-jwks_uri)
• https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration (jwtConfiguration.audience)

@handrews If you are OK with that, I could create a new PR adding the audience and jwks-uri properties. With the previously shown example, I do not think it is experimental but I add an experimental property to true if you prefer to.