From 8b724f809ae479e37d79f42843f07e68b954a99a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 3 Apr 2019 11:53:22 +0400 Subject: [PATCH 1/4] Clarify empty Security Requirement Object usage and validity --- versions/3.0.3.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index b1abb2223a..8107734621 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -195,7 +195,7 @@ Field Name | Type | Description servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement (`{}`) can be included in the array. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. @@ -851,7 +851,7 @@ Field Name | Type | Description responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. To make security optional, an empty security requirement (`{}`) can be included in the array. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -3337,6 +3337,8 @@ flows: 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](#componentsSecuritySchemes) under the [Components Object](#componentsObject). +An empty Security Requirement Object with no properties (`{}`) is also valid. It can be used as part of a `security` array in an OpenAPI Object or an Operation Object, along with other Security Requirement Objects, meaning that security with them is optional. + Security Requirement Objects that contain multiple schemes require that 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. @@ -3346,7 +3348,7 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](# Field Pattern | Type | Description ---|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. +{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. An empty Security Requirement Object (`{}`) is also valid. ##### Security Requirement Object Examples @@ -3379,6 +3381,32 @@ petstore_auth: - read:pets ``` +###### Optional OAuth2 Security + +Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object: + +```json +{ + "security": [ + {}, + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ] +} +``` + +```yaml +security: + - {} + - petstore_auth: + - write:pets + - read:pets +``` + ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. From 6e115e5897c100cf66586000a84f4b843090f236 Mon Sep 17 00:00:00 2001 From: Ron Date: Fri, 14 Feb 2020 09:09:11 -0700 Subject: [PATCH 2/4] Reorder sentences to make clearer. --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 8107734621..2ef313c88f 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -851,7 +851,7 @@ Field Name | Type | Description responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. To make security optional, an empty security requirement (`{}`) can be included in the array. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). From 7c836b28b7fd457cacfde242b5461e926e5782b2 Mon Sep 17 00:00:00 2001 From: Ron Date: Fri, 14 Feb 2020 09:09:28 -0700 Subject: [PATCH 3/4] Remove wrong text. --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 2ef313c88f..94f2b84560 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3348,7 +3348,7 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](# Field Pattern | Type | Description ---|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. An empty Security Requirement Object (`{}`) is also valid. +{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples From 2caf837bf43805a9e36ca9457b4d9ad7a66f2fb0 Mon Sep 17 00:00:00 2001 From: Ron Date: Fri, 14 Feb 2020 09:12:00 -0700 Subject: [PATCH 4/4] Removed unneeded text. --- versions/3.0.3.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 94f2b84560..64c7023065 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3337,8 +3337,6 @@ flows: 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](#componentsSecuritySchemes) under the [Components Object](#componentsObject). -An empty Security Requirement Object with no properties (`{}`) is also valid. It can be used as part of a `security` array in an OpenAPI Object or an Operation Object, along with other Security Requirement Objects, meaning that security with them is optional. - Security Requirement Objects that contain multiple schemes require that 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.