Openapi-specification: Mixing of concepts in securitySchemes OAS3

[jblazek]

I'm looking at the securitySchemes options and seems like the section is overloading concepts.

I get Bearer is a scheme, but OAuth2 is the standard that defines the Bearer scheme, so should I use both in my spec?

Additionally, having OpenID which is a layer over OAuth2 makes this more confusing.

Basically, I'm having my clients authenticate using OpenID to get a OAuth2 Bearer (access) token which is used for authorization.

It seems like I would need 3 items in securitySchemas (Bearer, OAuth2, and OpenID) to represent this.

[pleothaud]

Hi Joe,

1. While Bearer is today the only existing mechanism to transmit an access_code to the Resource Server (i.e. the only token_type in the IANA OAuth Parameters registry, see https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-types) other options were once foreseen, like MAC Access Authentication (see https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-05, expired draft today).

So adding to the OAuth definition (flows) Security Scheme an HTTP Bearer Security Scheme stating that the access_token must be transmitted as a Bearer token in the Authorization header has definitely some value for future compatibility with non yet existing mechanisms.

1. OpenID Connect is not (only) "a layer over OAuth2" in the sense of an extra Authentication functionality on top of an existing OAuth2 Authorization server delivering access_token to this or that Resource Server.

Actually OpenID Connect is an authentication protocol using OAuth2 flows as the mechanism to trigger the end-user (Resource owner) authentication against an OpenID Connect Provider(OIDC OP, acting as an OAuth 2 Resource Server) so that a Client Application, the OIDC Relying Party (RP, the OAuth2 Client) is assured of the end-user identity and can access this end-user profile.

a. In your case it seems that the OIDC Provider and the OAuth2 Authorization Server are the same entity.

In this case yes, you can mix both functionalities and in the initial Authorization request you can pass at the same time :
- the openid scope that will trigger authentication and the retrieval of the id_token
- the business scopes corresponding to the business operations you want the OAuth2 Authorization Server

In this case, the access_token you retrieve at the Client in the end is at the same time
- an access_token to the user_info OIDC endpoint where the API (Resource Server) can obtain the end-user profile
- an access_token to the API (Resource Server) itself, access_token that this API Server should verify against the Authorization Server using its Token Introspection (RFC 7662) endpoint (named introspection_endpoint in the Authorization Server metadata as defined by https://tools.ietf.org/html/draft-ietf-oauth-discovery-10)

Note that there is overlap between these two calls (user_info and introspection_endpoint)

b. But it doesn't have to be like this, and you can use separate OIDC Provider (like Google) and OAuth2 Authorization Server.

When you delegate Authentication to Google OIDC implementation, you don't expect (and you don't want!) Google to be able to take an authorization decision for your end-users and your APIs, you just want Google to authenticate your end-user and give you his profile when authenticated.

So in this case the "OIDC" access_token your Client will retrieve from Google will just let your Client
- be sure that the requester is authenticated properly
- know who this end-user is and what is his profile through the id_token you retrieve during the process
- have potentially some more profile info by invoking the OIDC Provider user_info endpoint (call requiring the "OIDC" access_token)

Then your Client might have to send another Authorization request to another Authorization Server to obtain another "OAuth2" access_token to access the target API, using the id_token as a JWT used as Authorization Grant (as described in RFC 7523 - JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants)

Another solution (more elegant) can be to use OAuth2 Token Exchange (https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-12) to exchange directly the retrieved id_token against an access token to the requested API

c. So as you can see, to take these use-cases into account you definitely need to be able to define at the same time an OAuth2 configuration as well as an OpenID Connect configuration.

Hope it helps,

Phil

[darrelmiller]

How you describe your security schemes depends on how much information you want to embed into your OpenAPI description.

If all you want to do is identify that you are using standard RFC7235 based auth, then use the http type and if you happen to be using the bearer scheme you can say that.

However, if you want to convey to your API consumer what the Authserver, token server URLs are, and the supported flows, then you can choose to do that with the more specific oauth2 type.

If you happen to have an OpenIdConnect discovery endpoint, and you are ok with consumers getting all the necessary configuration directly from there, then use the openIdConnect type. If you have some consumers that don't know how to consumer an OpenIDConnect discovery endpoint then you might want to include both a openIdConnect type and a oauth2 type.

The support for bearer tokens with the http type was really just for people who want to borrow the bearer scheme for non-oauth2 scenarios.

[jblazek]

@darrelmiller your comment makes sense then. I can understand how my API would support multiple schemes, and while bearer and oauth2 might be overloaded I see the intention of what it is supposed to represent.

In my cases, I started with oauth2 and defined scopes, but I'm converting it to openIdConnect.