Enhancing specification to describe token presentation mechanisms for OAuth 2.0

[alex-feel]

Issue Description

During a recent discussion in #2867, it became apparent that the OpenAPI Specification lacks explicit guidelines on how clients should present access tokens to resource servers, especially considering the OAuth 2.0 authorization framework. This issue was highlighted in the context of OAuth 2.0's defined grant flows and the need for specifying how access tokens, once obtained, are used for resource access.

Relevant Discussion Points

• OAuth 2.0 Grant Flows: The specification allows defining OAuth 2.0 flows, like the implicit flow, requiring the authorizationUrl. However, it stops short of detailing how the obtained access tokens should be presented to the resource server.

• Access Token Presentation: The OAuth 2.0 specification mentions the use of the HTTP "Authorization" request header field with an authentication scheme for the access token type. Yet, "typically" does not encompass all possible scenarios, like the requirement for the Demonstration of Proof-of-Possession at the Application Layer (DPoP), which requires additional headers.

• OpenAPI Specification Limitation: The current OpenAPI Specification does not support specifying the method of presenting an access token to a resource server. This limitation was acknowledged in a community call discussion.

Proposal for Enhancement

Given the diversity in access token types and presentation methods (e.g., Bearer tokens, DPoP), there is a clear need for the OpenAPI Specification to allow documenting the exact mechanism of access token presentation for a secured endpoint.

Suggested Improvements:

1. Extend the securitySchemes Object: Introduce new fields within the securitySchemes object to specify the required headers or methods for presenting access tokens, including non-standard approaches.

2. Community Engagement: Invite contributions and discussions from the OpenAPI community, through TDC calls, workflows sig, or security sig, to refine and agree upon the proposed enhancements.

Conclusion

Enhancing the OpenAPI Specification to include explicit guidelines on access token presentation mechanisms would greatly aid in the accurate and comprehensive documentation of APIs, fostering better interoperability and understanding of secured API endpoints. I look forward to contributing to this discussion and helping drive the necessary changes.

[alex-feel]

@LasneF @lornajane Based on feedback and aiming for flexibility in specifying authentication schemes, I propose the following adjustment to the scheme attribute in the OpenAPI Specification for 3.2 target branch:

<a name="securitySchemeScheme"></a>scheme | `string` | `http`, `oauth2` | **REQUIRED** for `http`, **OPTIONAL** for `oauth2`. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1).  The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).

This revision aims to maintain the required status for http scheme while introducing flexibility for oauth2.

Would this approach be preferable, or should we consider adding a new optional field specifically for oauth2 to avoid ambiguity?

I'm looking forward to the community's input to refine this proposal further. If this approach meets the community's approval, I will proceed to create a new PR targeting the 3.2 branch to incorporate these changes.