When using OAuth 2.0, how do you describe the exact mechanism that should be used to authorize requests to a resource server?

[alex-feel]

OpenAPI allows you to specify an OAuth security scheme type and a list of scopes required to request an endpoint (resource server). It might look like this:

components:
  securitySchemes:
    oAuthSample:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://api.example.com/oauth2/authorize
          scopes:
            read_pets: read pets in your account
            write_pets: modify pets in your account

paths:
  /pets/{petId}:
    patch:
      summary: Updates a pet in the store
      security: 
        - oAuthSample: [write_pets]
      ...

Source: https://swagger.io/docs/specification/authentication/oauth2/.

How, from such a specification, you can understand how exactly a client should be authorized on a resource server on behalf of an user? Should it just be stated in a text documentation, or is there a standardized way provided by OpenAPI?

Or maybe it's better to formulate the question as follows - how in OpenAPI to specify the type of an access token from the options defined here https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-types, that is issued by an authorization server and, as a result, explain how the token is used for authorization on a resource server?

P.S. This question was originally asked on Stackoverflow.

[webron]

It's all in the flow... or rather in the flows field. OAuth2 defines 4 main grant flows, and in the example you provided, the implicit flow is being used. For each one of the flows, the spec requires you to specific different types of URLs that are used for the authorization. In the case of the implicit flow, only the authorizationUrl needs to be specified.

Take a look at the quick overview and you can dive into deeper details from there as needed.

[alex-feel]

@webron, how can specifying the path to the endpoint that allows you to get an access token help you understand exactly how you need to present the received access token to the resource server? For example, how does the client understand that it just needs to send an access token in the Authorization: Bearer <access_token> header, or does it need to do it some other way?

[webron]

That's described in how those OAuth2 flows work (in the OAuth2 spec). We're aware that some implementations deviate from following those flows, but at the moment there's no way to define those 'exceptions'.

[alex-feel]

@webron, OAuth2 flows do not describe how a client should present the received access token to a resource server, OAuth2 flows only describe how a client receives the access token and nothing more. At the same time, there is an Accessing Protected Resources section in the standard, which says the following:

The method in which the client utilizes the access token to authenticate with the resource server depends on the type of access
token issued by the authorization server. Typically, it involves using the HTTP "Authorization" request header field [RFC2617] with an authentication scheme defined by the specification of the access token type used, such as [RFC6750].

Typically does not mean exactly, that is, there are different options. For example, the server may require Demonstration of Proof-of-Possession at the Application Layer (DPoP), which means that the client needs to send an additional header. In other words, the OAuth standard does not provide a clear mechanism for presenting an access token to a resource server. Hence my question - how to document this mechanism with OpenAPI?

It turns out that OpenAPI does not support the ability to specify a way to present an access token to a resource server? If so, why not just add to OpenAPI the ability to specify for an endpoint, along with the scope that is required for successful requests to it, a way to provide an access token to that endpoint?

[webron]

Yup, the spec definitely does not provide information about everything. We actually just talked about some aspects of it in the community call. You're welcome to join the discussion next week, whether it's the TDC call, the workflows sig or the security sig and help drive the conversation.

[murthygorty]

Hi @alex-feel , has you

@webron, OAuth2 flows do not describe how a client should present the received access token to a resource server, OAuth2 flows only describe how a client receives the access token and nothing more. At the same time, there is an Accessing Protected Resources section in the standard, which says the following:

The method in which the client utilizes the access token to authenticate with the resource server depends on the type of access
token issued by the authorization server. Typically, it involves using the HTTP "Authorization" request header field [RFC2617] with an authentication scheme defined by the specification of the access token type used, such as [RFC6750].

Typically does not mean exactly, that is, there are different options. For example, the server may require Demonstration of Proof-of-Possession at the Application Layer (DPoP), which means that the client needs to send an additional header. In other words, the OAuth standard does not provide a clear mechanism for presenting an access token to a resource server. Hence my question - how to document this mechanism with OpenAPI?

It turns out that OpenAPI does not support the ability to specify a way to present an access token to a resource server? If so, why not just add to OpenAPI the ability to specify for an endpoint, along with the scope that is required for successful requests to it, a way to provide an access token to that endpoint?

Hi @alex-feel , has your question been answered - I'm tackling this exact issue 2 years later :-)
Need a way to declare extensions (like DPOP) in securityScheme..

[alex-feel]

Hi @murthygorty,

Unfortunately, my question about documenting the presentation of an access token to a resource server using OpenAPI has not been fully resolved yet. The OpenAPI Specification (OAS) does allow for specifying OAuth2 security schemes and the required scopes for accessing an endpoint. However, the specification does not directly address how to document the exact method for presenting an access token, such as the use of standard Authorization: Bearer headers or methods involving Proof-of-Possession (DPoP) tokens.

This gap in the OpenAPI Specification means there isn't a standardized way to document these details within the framework of OAS directly. Some workarounds involve using extensions (x-fields) or detailed descriptions within the documentation to explain the authentication process and any specific requirements, like DPoP. However, these are not formal parts of the specification and may not be ideal for the automatic generation of client libraries or documentation.

[murthygorty]

Thank you so much for the response @alex-feel -> I am also enquiring this through another other standards body, CAMARA. There may be opportunity for one of the bodies to standardize the x-field extension within the scope of that body; for example, DPOP RFC can specify the field and that would be considered standard (as an idea)...

Like you identified OAS doesnt seem to have an appetite for this currrently.

[handrews]

@murthygorty

Like you identified OAS doesnt seem to have an appetite for this currrently.

It's more that we're trying to sort out or process and get moving on defining 3.0.4, 3.1.1, 3.2.0, and 4.0.0 (a.k.a. Moonwalk) simultaneously, when we've never previously managed multiple release lines. We're not uninterested, it's just that spec work is volunteer work and we have an immense amount to do right now just organizing what's already been checked in and then figure out what else needs to be done before we publish each of those releases.

You can look for the TDC meeting agenda issues to see what we're actively working on each week (I think they now get updated with the recordings, or if the time zone works for you, anyone is welcome to join the call).

[murthygorty]

Great to know @handrews! thanks so much for the additional insights - I can completely understand.

[handrews]

Also I'm realizing this is a "Discussion" rather than an "Issue"... we're trying to sort out what each of these things is used for. I think someone enabled discussions a couple of years ago and kind of forgot about it. We recently did a huge push to classify issues and close out ones that were stale in some way, but haven't yet done that for discussions. Some relevant things tracking this effort are:

• 2024 New Year's Cleaning meta-issue #3516
• Use community repo for governance, info, & user/dev help questions #3561
• Use projects for focused, short-term work with a specific audience #3610
• 3.x minor release approach #3529
• 3.x.y patch release approach #3528
• Define criteria for filing/closing issues vs discussions #3518

[murthygorty]

thanks agaiin @handrews - Highly recommend going the 'issue' route to simplify.
Discussion == issue towards clearer documentation :-)

[AxelNennker]

I suggest someone, @murthygorty ?, summarizes this "discussion" and creating a new issue, and if possible a pr to https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md in branch v3.0.4-dev.
And then add the topic to the community meeting?!

[alex-feel]

Thought about creating an issue, there is a special functionality in discussions to create an issue from a discussion. Let me do it.

[alex-feel]

It's here #3612.

[alex-feel]

I'm going to create PR, need some time.

[alex-feel]

After an extensive and detailed analysis of the standards involved, I've created a PR to implement the proposed changes regarding the OAuth 2.0 authorization mechanisms in the OpenAPI Specification. Interestingly, the solution turned out to be simpler than I initially thought. However, reaching this conclusion was no small feat—it required a solid 6 hours of meticulous review and consideration. I believe these updates will significantly clarify and enhance the way we describe authorization mechanisms, particularly around the use of different types of tokens like Bearer and DPoP. Here's the link to the PR for those interested in reviewing the changes: #3613.

I appreciate any feedback or contributions to ensure we've covered all bases and that the proposed modifications align well with both current standards and practical implementation needs.

[lornajane]

Thanks @alex-feel ! I'll echo what @handrews said about volume of work to do vs available volunteer time, but I'm very happy to see progress in this area and while nothing happens overnight, having strong support for good OAuth2 in OpenAPI will be excellent. I appreciate the constructive discussion and pull request :)

[alex-feel]

@lornajane, I'm grateful for your efforts and fully understand the volume of work that lies ahead of you. Should any revisions or changes to the PR be required, I am at your service.

[handrews]

I'm going to close this in favor of issue #3612 (note that the PR raised was deemed worthy of further exploration but needed to find the right release branch and have other details resolved- the issue is a better place to finish that discussion).