From c6c079507d8fa224fe7d2d76697bee98bf0d58ba Mon Sep 17 00:00:00 2001 From: Alex Feel Date: Thu, 29 Feb 2024 14:06:09 +0200 Subject: [PATCH] Extend Security Scheme Object to support DPoP token specification 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. I apologize for the confusion and appreciate your patience. Let's directly address your request and correct the approach for specifying OAuth 2.0 with bearer tokens and DPoP within the OpenAPI Specification, focusing on the `scheme` field extension. ### 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: ```yaml 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: ```yaml 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. --- versions/3.0.3.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index e21aa46554..6b356227f6 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3188,7 +3188,7 @@ Field Name | Type | Applies To | Description description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. -scheme | `string` | `http` | **REQUIRED**. 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). +scheme | `string` | `http`, `oauth2` | **REQUIRED**. 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). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. @@ -3248,6 +3248,7 @@ bearerFormat: JWT ```json { "type": "oauth2", + "scheme": "bearer", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", @@ -3262,7 +3263,8 @@ bearerFormat: JWT ```yaml type: oauth2 -flows: +scheme: bearer +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: @@ -3303,6 +3305,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```JSON { "type": "oauth2", + "scheme": "bearer", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", @@ -3325,7 +3328,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml type: oauth2 -flows: +scheme: bearer +flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: