Add OAuth 2.0 Token Exchange (RFC 8693) to the supported OAuth flows

Adds a tokenExchange fixed field to the OAuth Flows Object, mirroring
the deviceAuthorization pattern: tokenUrl required, scopes as for all
flows. Includes the validation schema addition and test fixtures.

Refs discussion #4807.

Author: cayetanobv

src/oas.md

@@ -4577,7 +4577,7 @@ and `./examples/productNoNulls.xml` would be:
 
 Defines a security scheme that can be used by the operations.
 
-Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), OAuth2 device authorization flow as defined in [RFC8628](https://tools.ietf.org/html/rfc8628), and [[OpenID-Connect-Core]].
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), OAuth2 device authorization flow as defined in [RFC8628](https://tools.ietf.org/html/rfc8628), OAuth2 token exchange as defined in [RFC8693](https://tools.ietf.org/html/rfc8693), and [[OpenID-Connect-Core]].
 Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use cases is Authorization Code Grant flow with PKCE.
 
 #### Fixed Fields
@@ -4654,6 +4654,7 @@ Allows configuration of the supported OAuth Flows.
 | <a name="oauth-flows-client-credentials"></a>clientCredentials | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. |
 | <a name="oauth-flows-authorization-code"></a>authorizationCode | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. |
 | <a name="oauth-flows-device-authorization"></a>deviceAuthorization | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Device Authorization flow. |
+| <a name="oauth-flows-token-exchange"></a>tokenExchange | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Token Exchange flow. |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -4667,7 +4668,7 @@ Configuration details for a supported OAuth Flow
 | ---- | :----: | ---- | ---- |
 | <a name="oauth-flow-authorization-url"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
 | <a name="oauth-flow-device-authorization-url"></a>deviceAuthorizationUrl | `string` | `oauth2` (`"deviceAuthorization"`) | **REQUIRED**. The device authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
-| <a name="oauth-flow-token-url"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`, `"deviceAuthorization"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
+| <a name="oauth-flow-token-url"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`, `"deviceAuthorization"`, `"tokenExchange"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
 | <a name="oauth-flow-refresh-url"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
 | <a name="oauth-flow-scopes"></a>scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. |
 

src/schemas/validation/schema.yaml

@@ -1039,6 +1039,8 @@ $defs:
         $ref: '#/$defs/oauth-flows/$defs/authorization-code'
       deviceAuthorization:
         $ref: '#/$defs/oauth-flows/$defs/device-authorization'
+      tokenExchange:
+        $ref: '#/$defs/oauth-flows/$defs/token-exchange'
     $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false
 
@@ -1136,6 +1138,23 @@ $defs:
         $ref: '#/$defs/specification-extensions'
         unevaluatedProperties: false
 
+      token-exchange:
+        type: object
+        properties:
+          tokenUrl:
+            type: string
+            format: uri-reference
+          refreshUrl:
+            type: string
+            format: uri-reference
+          scopes:
+            $ref: '#/$defs/map-of-strings'
+        required:
+          - tokenUrl
+          - scopes
+        $ref: '#/$defs/specification-extensions'
+        unevaluatedProperties: false
+
   security-requirement:
     $comment: https://spec.openapis.org/oas/v3.3#security-requirement-object
     type: object

tests/schema/minimal-objects.yaml

@@ -155,4 +155,10 @@
     tokenUrl: https://example.com/auth
     scopes: {}
 
+- objectName: OAuth Flow Object (tokenExchange)
+  subSchemaPath: /$defs/oauth-flows/$defs/token-exchange
+  minimalInstance:
+    tokenUrl: https://example.com/token
+    scopes: {}
+
 # Security Requirement Object allows additional properties

tests/schema/pass/security-scheme-object-examples.yaml

@@ -53,6 +53,11 @@ components:
           scopes:
             read:pets: read your pets
           refreshUrl: https://example.com/api/oauth/refresh
+        tokenExchange:
+          tokenUrl: https://example.com/api/oauth/token
+          scopes:
+            read:pets: read your pets
+          refreshUrl: https://example.com/api/oauth/refresh
     OAuth2Old:
       deprecated: true
       type: oauth2