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.

Author: handrews

Diff for: src/oas.md

@@ -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 |
-| ---- | :----: | ---- |
-| <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="securityRequirementsName"></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
 
@@ -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,14 +4124,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"]
     }
   ]
 }
@@ -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.