From c6e65b9b80b2d19600e74e5b868a1802a9ef7d10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Thu, 2 Jul 2026 17:07:43 +0200 Subject: [PATCH 1/3] Introduce SAML 2.0 Bearer flow --- src/oas.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d5b3645174..2583dbf635 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4577,6 +4577,7 @@ 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]]. 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. +For requests between pre-integrated business systems, SAML 2.0 Bearer flow as defined in [RFC7522, section 2.1](https://tools.ietf.org/html/rfc7522#section-2.1) is an alternative that avoids the need for explicit consent by the user. #### Fixed Fields @@ -4651,6 +4652,7 @@ Allows configuration of the supported OAuth Flows. | password | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Password flow | | clientCredentials | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. | | authorizationCode | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. | +| saml2Bearer | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth SAML 2.0 Bearer flow. | | deviceAuthorization | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Device Authorization flow. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -4665,7 +4667,8 @@ Configuration details for a supported OAuth Flow | ---- | :----: | ---- | ---- | | 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. | | 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. | -| 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. | +| samlMetadataUrl | `string` | `oauth2` (`"saml2Bearer"`) | The metadata URL for the SAML entity that accepts the SAML assertion. This MUST be in the form of a URL. | +| tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`, `"saml2Bearer"`, `"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. | | 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. | | 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. | From eec1007c3e906cc1adc7e210b9fc003c751024aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Thu, 2 Jul 2026 17:21:25 +0200 Subject: [PATCH 2/3] Schema change --- src/schemas/validation/schema.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 702e73c11e..b599c673a1 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -1037,6 +1037,8 @@ $defs: $ref: '#/$defs/oauth-flows/$defs/client-credentials' authorizationCode: $ref: '#/$defs/oauth-flows/$defs/authorization-code' + saml2Bearer: + $ref: '#/$defs/oauth-flows/$defs/saml2-bearer' deviceAuthorization: $ref: '#/$defs/oauth-flows/$defs/device-authorization' $ref: '#/$defs/specification-extensions' @@ -1115,6 +1117,26 @@ $defs: $ref: '#/$defs/specification-extensions' unevaluatedProperties: false + saml2-bearer: + type: object + properties: + samlMetadataUrl: + type: string + format: uri-reference + 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 + device-authorization: type: object properties: From 460dae6768e662afa26e9100530216ccc826eb4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Fri, 3 Jul 2026 09:50:03 +0200 Subject: [PATCH 3/3] Do not mention the SAML metadata --- src/oas.md | 1 - src/schemas/validation/schema.yaml | 3 --- 2 files changed, 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index 2583dbf635..9857df38ac 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4667,7 +4667,6 @@ Configuration details for a supported OAuth Flow | ---- | :----: | ---- | ---- | | 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. | | 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. | -| samlMetadataUrl | `string` | `oauth2` (`"saml2Bearer"`) | The metadata URL for the SAML entity that accepts the SAML assertion. This MUST be in the form of a URL. | | tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`, `"saml2Bearer"`, `"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. | | 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. | | 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. | diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index b599c673a1..f6b37f2c0f 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -1120,9 +1120,6 @@ $defs: saml2-bearer: type: object properties: - samlMetadataUrl: - type: string - format: uri-reference tokenUrl: type: string format: uri-reference