Replies: 12 comments 8 replies
-
It's all in the flow... or rather in the Take a look at the quick overview and you can dive into deeper details from there as needed. |
Beta Was this translation helpful? Give feedback.
-
Hi @alex-feel , has you
Hi @alex-feel , has your question been answered - I'm tackling this exact issue 2 years later :-) |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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). |
Beta Was this translation helpful? Give feedback.
-
Great to know @handrews! thanks so much for the additional insights - I can completely understand. |
Beta Was this translation helpful? Give feedback.
-
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:
|
Beta Was this translation helpful? Give feedback.
-
thanks agaiin @handrews - Highly recommend going the 'issue' route to simplify. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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 :) |
Beta Was this translation helpful? Give feedback.
-
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). |
Beta Was this translation helpful? Give feedback.
-
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:
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.
Beta Was this translation helpful? Give feedback.
All reactions