From 50f65f5049a8f3cd2d2c28a00ad948d86efc04f5 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 23 Feb 2025 16:29:52 -0800 Subject: [PATCH 1/2] Allow URIs for Security Schemes This allows Security Requirement Objects to reference Security Scheme Objects by URI instead of implicit component name. Without this ability, it is difficult to share Security Schemes in a way that is consistent with re-usable component documents. This approach provides parity with how the Discriminator Object's mapping field works. Also add a note about the complexity of these rules to the Security Considerations section. --- src/oas.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/src/oas.md b/src/oas.md index 19d26b27c0..a14bbf0d24 100644 --- a/src/oas.md +++ b/src/oas.md @@ -214,8 +214,8 @@ This allows Security Scheme Objects and Tag Objects to be defined next to the AP The interface approach can also work for Discriminator Objects and Schema Objects, but it is also possible to keep the Discriminator Object's behavior within a single document using the relative URI-reference syntax of `mapping`. -There are no URI-based alternatives for the Security Requirement Object or for the Operation Object's `tags` field. -These limitations are expected to be addressed in a future release. +There are no URI-based alternatives for the Operation Object's `tags` field. +This limitation is expected to be addressed in a future release. See [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-in-a-referenced-document) for an example of the possible resolutions, including which one is recommended by this section. The behavior for Discrimator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles. @@ -4069,7 +4069,12 @@ flows: #### Security Requirement Object Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#security-scheme-object) under the [Components Object](#components-object). + +The name used for each property MUST either correspond to a security scheme declared in the [Security Schemes](#security-scheme-object) under the [Components Object](#components-object), or be the URI of a Security Scheme Object. +Property names that match the syntax of a component name under the Components Object MUST be treated as a component name. +To reference a Security Scheme with a single-segment relative URI reference (e.g. `foo`) that collides with a component name (e.g. `#/components/securitySchemes/foo`), use the `.` path segment (e.g. `./foo`). + +Using a Security Scheme component name that appears to be a URI is NOT RECOMMENDED, as the precedence of component-name-matching over URI resolution, which is necessary to maintain compatibility with prior OAS versions, is counter-intuitive. See also [Security Considerations](#security-considerations). A Security Requirement Object MAY refer to multiple security schemes in which case all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. @@ -4082,8 +4087,8 @@ An empty Security Requirement Object (`{}`) indicates anonymous access is suppor ##### Patterned Fields | Field Pattern | Type | Description | -| ---- | :----: | ---- | -| {name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#security-scheme-object) under the [Components Object](#components-object). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band. | +| --- | :---: | --- | +| {name} | [`string`] | Each name or URI MUST correspond to a security scheme as described above. If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band. | ##### Security Requirement Object Examples @@ -4103,6 +4108,8 @@ api_key: [] ###### OAuth2 Security Requirement +This example uses a component name for the Security Scheme. + ```json { "petstore_auth": ["write:pets", "read:pets"] @@ -4117,6 +4124,8 @@ petstore_auth: ###### Optional OAuth2 Security +This example uses a relative URI reference for the Security Scheme. + Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object: ```json @@ -4124,7 +4133,7 @@ Optional OAuth2 security as would be defined in an Ope "security": [ {}, { - "petstore_auth": ["write:pets", "read:pets"] + "#/components/securitySchemes/petstore_auth": ["write:pets", "read:pets"] } ] } @@ -4186,6 +4195,11 @@ In addition, OpenAPI Descriptions are processed by a wide variety of tooling for An OpenAPI Description describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations. +The rules for connecting a [Security Requirement Object](#security-requirement-object) to a [Security Scheme Object](#security-scheme-object) under a [Components Object](#components-object) are ambiguous in a way that could be exploited. Specifically: + +* It is implementation-defined whether a component name used by a Security Requirement Object in a referenced document is resolved from the entry document (RECOMMENDED) or the referenced document. +* A Security Requirement Object that uses a URI to identify a Security Scheme Object can have the URI resolution hijacked by providing a Security Scheme component name identical to the URI, as the name lookup behavior takes precedence over URI resolution for compatibility with previous versions of the OAS. + ### Handling External Resources OpenAPI Descriptions may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted. From 33aef075bb0ded0820720eb27736082fbf9d45fd Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 13 Mar 2025 09:46:00 -0700 Subject: [PATCH 2/2] Review feedback --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index a14bbf0d24..10c892ff2d 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4071,7 +4071,7 @@ flows: Lists the required security schemes to execute this operation. The name used for each property MUST either correspond to a security scheme declared in the [Security Schemes](#security-scheme-object) under the [Components Object](#components-object), or be the URI of a Security Scheme Object. -Property names that match the syntax of a component name under the Components Object MUST be treated as a component name. +Property names that are identical to a component name under the Components Object MUST be treated as a component name. To reference a Security Scheme with a single-segment relative URI reference (e.g. `foo`) that collides with a component name (e.g. `#/components/securitySchemes/foo`), use the `.` path segment (e.g. `./foo`). Using a Security Scheme component name that appears to be a URI is NOT RECOMMENDED, as the precedence of component-name-matching over URI resolution, which is necessary to maintain compatibility with prior OAS versions, is counter-intuitive. See also [Security Considerations](#security-considerations). @@ -4088,7 +4088,7 @@ An empty Security Requirement Object (`{}`) indicates anonymous access is suppor | Field Pattern | Type | Description | | --- | :---: | --- | -| {name} | [`string`] | Each name or URI MUST correspond to a security scheme as described above. If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band. | +| {name} | [`string`] | Each name or URI MUST correspond to a security scheme as described above. If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band. | ##### Security Requirement Object Examples