Extend Security Scheme Object to support DPoP token specification

[alex-feel]

In response to evolving security requirements and practices in web API design, and after thorough analysis of the current OpenAPI Specification version 3.0.3 and relevant RFCs, specifically RFC 9449, I am proposing an enhancement to the OpenAPI Specification in the upcoming v3.0.4-dev branch. This proposal is aimed at incorporating a more nuanced approach to token-based authentication, particularly addressing the implementation of Demonstration of Proof-of-Possession (DPoP) tokens.

Proposed Modifications in the PR:

1. Extend the scheme Field's Application: Suggest that the application of the scheme field within the Security Scheme Object includes both http and oauth2 types. This extension is essential for describing the authentication methods with greater accuracy and aligns with the authentication scheme differentiation as described in RFC 9449.

2. Refinement on the Use of bearer and dpop Schemes:

• When type is set to oauth2 and scheme to bearer, it indicates the traditional bearer token usage without employing DPoP mechanisms, aligning with standard OAuth 2.0 practices.
• When type is oauth2 and scheme is dpop, it explicitly indicates the utilization of DPoP, necessitating the format Authorization: DPoP token. Furthermore, in accordance with RFC 9449, this setup mandates the inclusion of a DPoP header in the request, providing a DPoP proof.

Rationale Behind the Proposal:

The motivation for these modifications is grounded in the detailed examination of the DPoP authentication scheme as outlined in Section 7.1 of RFC 9449. DPoP introduces a more secure method for handling tokens by binding them to a particular HTTP request and a cryptographic key pair owned by the client. This mechanism significantly mitigates the risk associated with token theft and replay attacks, as the token is no longer a standalone bearer token but requires accompanying proof of possession.

By integrating dpop as a specified scheme within the OAuth 2.0 security scheme in OpenAPI, we acknowledge the necessity for APIs to adopt more secure authentication methods in light of increasing security challenges. This proposal ensures that the OpenAPI Specification remains relevant and capable of describing modern, secure API architectures.

Furthermore, the explicit distinction between bearer and dpop within the specification allows for clear documentation and implementation of APIs that require enhanced security measures. It encourages API designers to consider and implement DPoP where applicable, fostering a more secure ecosystem of web APIs.

Examples of Usage:

Bearer Token Example for OAuth 2.0

Here's how you can specify the use of standard OAuth 2.0 bearer tokens in an OpenAPI document:

components:
  securitySchemes:
    oauth2Bearer:
      type: oauth2
      scheme: bearer
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Read access
            write: Write access
      description: Standard OAuth2 bearer token usage.

DPoP Token Example for OAuth 2.0

For specifying OAuth 2.0 with DPoP tokens, indicating enhanced security by binding the tokens to a specific HTTP request:

components:
  securitySchemes:
    oauth2DPoP:
      type: oauth2
      scheme: dpop
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Read access
            write: Write access
      description: OAuth 2.0 with DPoP tokens for enhanced security, binding tokens to specific requests.

Conclusion:

This PR aims to enhance the OpenAPI Specification by providing clear, structured means to specify the use of DPoP tokens alongside traditional bearer tokens. By doing so, it contributes to the broader goal of improving security practices within the API design community, ensuring that OpenAPI remains at the forefront of technological and security advancements.

Closes #3612.

[alex-feel]

In submitting this PR, my aim was to maintain consistency with the original discussion, hence the title and description chosen. However, it's important to highlight that the proposed modification opens up possibilities not only for describing DPoP but also for incorporating other authentication schemes, both existing and potentially new ones in the future. This flexibility ensures that the OpenAPI Specification can evolve alongside advancements in security protocols, maintaining its relevance and utility for API designers and developers.

[LasneF]

adding a required statement , might be seen as a breaking change , even if here it is not formulated inside a strong schema validation. so any addition should be set as optionnal

given the addition should go in the 3.2 as a target branch

required statement would mandate a version change , and so going to moonwalk

[alex-feel]

Thank you for the review. Could we possibly change the base branch of the current PR instead of creating a new one? I'll need to check if it has a common history with the current branch to ensure there are no conflicts. Do you think that would be a better approach, or would you recommend creating a new PR?

[lornajane]

Thanks for adding this, we're agreed as a group that this (and many other OAuth things) would be excellent additions, but as @LasneF already mentioned, it won't be added to the 3.0.x branch. I'm closing this pull request since it can't merge as-is, but let's continue discussion on the issue to move forward with this feature.