Merge pull request #4388 from handrews/sec-req-uri

Allow URIs for Security Schemes

Author: miqui

Diff for: 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.
@@ -4165,7 +4165,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 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).
 
 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.
@@ -4178,8 +4183,8 @@ An empty Security Requirement Object (`{}`) indicates anonymous access is suppor
 ##### Patterned Fields
 
 | Field Pattern | Type | Description |
-| ---- | :----: | ---- |
-| <a name="security-requirements-name"></a>{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. |
+| --- | :---: | --- |
+| <a name="security-requirements-name"></a>{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
 
@@ -4199,6 +4204,8 @@ api_key: []
 
 ###### OAuth2 Security Requirement
 
+This example uses a component name for the Security Scheme.
+
 ```json
 {
   "petstore_auth": ["write:pets", "read:pets"]
@@ -4213,14 +4220,16 @@ 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 <a href="#openapi-object">OpenAPI Object</a> or an <a href="#operation-object">Operation Object</a>:
 
 ```json
 {
   "security": [
     {},
     {
-      "petstore_auth": ["write:pets", "read:pets"]
+      "#/components/securitySchemes/petstore_auth": ["write:pets", "read:pets"]
     }
   ]
 }
@@ -4282,6 +4291,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.