Enhancing specification to describe token presentation mechanisms for OAuth 2.0

[alex-feel]

Issue Description

During a recent discussion in https://github.com/OAI/OpenAPI-Specification/discussions/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.