Scopes for jwt-based security scheme

[muhmud]

Would it be possible for something like https://github.com/swagger-api/swagger-node/issues/481 with it's use of "x-security-scopes" be standardised so that it could be reported through swagger-ui?

If the array in the Security Requirements could be populated with scopes for a new security definition of "jwt", that might be one way to do it.

Thanks,

[hkosova]

Possibly related: https://github.com/OAI/OpenAPI-Specification/issues/1366

[MikeRalphson]

My one hesitation in reusing the scopes array as-is for JWT and ApiKey securityScheme types is that scopes is a well-defined concept in oAuth2 which we would be co-opting for other securityScheme types. E.g. RFC7519 does not mention the concept of scopes. ApiKey securityScheme types really only have the concept of scopes for the bearer http scheme where something like an oAuth2 token is being used (e.g. the GitHub example cited).

This potential confusion could be addressed by having a roles map for non-oAuth2/openIdConnect securityScheme types and allowing the array value of the security requirement object to contain either scope or role values as appropriate.

[MikeRalphson]

Feedback on any potential confusion in reusing the term scopes gratefully received...

[whitlockjc]

I was just thinking of something similar. scopes are common in JWT and OIDC, though there is no mention of scopes in the their specs when it comes to their JWT claim name or value content. For example, Auth0 uses the scope claim and its value is a space-delimited list of scopes, whereas Okta uses the scopes claim and its value is an array of scopes. I personally think that with OIDC being identity management on top of OAuth, allowing scopes to be used by oauth2 and openIdConnect makes sense. I would even argue that any place a JWT could be used (apiKey, http, oauth2 and openIdConnect) for authn, scopes should be usable.

[TomFrost]

Chiming in support here, 15 months later. We're using OpenAPI3 to define the API spec for an internal platform with its own internal user/password authentication that provides JWT access and refresh tokens. The access tokens define the scopes that the user can access, and I have no official way to call this out in our api spec. The scopes functionality really needs to not be artificially walled off from Bearer tokens or any other scheme where a JWT could be used.

Edit: Realized after posting that this has been formalized in the 3.1.0 spec, which at the time of this writing is in RC1. Non-OAuth2/OIDC schemes can now use "roles" in the same way the aforementioned use scopes. They're not defined at the security scheme level as scopes are, but can be specified in the global-level or path-specific security block.