Skip to content

Commit e878b96

Browse files
rvedotrcrvedotrc
committed
Be more explicit about how to interpret security 
1 parent b016683 commit e878b96

File tree

1 file changed

+19
-3
lines changed

1 file changed

+19
-3
lines changed

‎versions/3.1.1.md

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -314,12 +314,28 @@ This is the root object of the [OpenAPI document](#openapi-description).
314314
| <a name="oas-paths"></a>paths | [Paths Object](#paths-object) | The available paths and operations for the API. |
315315
| <a name="oas-webhooks"></a>webhooks | Map[`string`, [Path Item Object](#path-item-object)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. |
316316
| <a name="oas-components"></a>components | [Components Object](#components-object) | An element to hold various schemas for the document. |
317-
| <a name="oas-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | 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. |
317+
| <a name="oas-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. See [The `security` Field](#the-security-field). |
318318
| <a name="oas-tags"></a>tags | [[Tag Object](#tag-object)] | A list of tags used by the document 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](#operation-object) 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. |
319319
| <a name="oas-external-docs"></a>externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. |
320320

321321
This object MAY be extended with [Specification Extensions](#specification-extensions).
322322

323+
###### The `security` Field
324+
325+
The `security` field describes which authentication mechanisms may be expected to be relevant for this API. This field, however, does not _define_ how authentication / authorization works for this API. Think of it more as _setting expectations_.
326+
327+
`security` may be specified at the [OpenAPI Object](#openapi-object) level, or at the [Operation Object](#operation-object) level, or neither, or both. The effective value of `security` for a given operation is given by the first available of:
328+
329+
1. the `security` value given at the Operation level (if specified);
330+
2. the `security` value given at the OpenAPI Object level (if specified);
331+
3. the empty array (`[]`).
332+
333+
If the effective value of `security` is the empty array (`[]`), then nothing should be inferred about authentication / authorization for this API. Maybe credentials are required, maybe not; we just don't know.
334+
335+
Otherwise, `security` is a non-empty array of [Security Requirement Objects](#security-requirement-object), and it should be inferred that at least one of these needs to be satisfied for the request to be accepted.
336+
337+
Because the empty Security Requirement Object `{}` will always be satisfied, any `security` list that includes the empty object (`{}`) may be inferred to allow all requests. In particular, `security: [{}]` is the RECOMMENDED way of saying "this API (or operation) does not require authentication".
338+
323339
#### Info Object
324340

325341
The object provides metadata about the API.
@@ -967,7 +983,7 @@ Describes a single API operation on a path.
967983
| <a name="operation-responses"></a>responses | [Responses Object](#responses-object) | The list of possible responses as they are returned from executing this operation. |
968984
| <a name="operation-callbacks"></a>callbacks | Map[`string`, [Callback Object](#callback-object) \| [Reference Object](#reference-object)] | 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](#callback-object) that describes a request that may be initiated by the API provider and the expected responses. |
969985
| <a name="operation-deprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. |
970-
| <a name="operation-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | 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`](#oas-security). To remove a top-level security declaration, an empty array can be used. |
986+
| <a name="operation-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used for this operation. If present, then this overrides any `security` field specified at the [OpenAPI Object](#oas-security) level. See the [definition of that field](#the-security-field) for details. |
971987
| <a name="operation-servers"></a>servers | [[Server Object](#server-object)] | An alternative `servers` array to service this operation. If a `servers` array is specified at the [Path Item Object](#path-item-servers) or [OpenAPI Object](#oas-servers) level, it will be overridden by this value. |
972988

973989
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -3907,7 +3923,7 @@ The name used for each property MUST correspond to a security scheme declared in
39073923
Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
39083924
This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
39093925

3910-
When a list of Security Requirement Objects is defined on the [OpenAPI Object](#openapi-object) or [Operation Object](#operation-object), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
3926+
When a non-empty list of Security Requirement Objects is defined on the [OpenAPI Object](#openapi-object) or [Operation Object](#operation-object), at least one of the Security Requirement Objects in the list needs to be satisfied for the request to be authorized; see [The `security` Field](#the-security-field).
39113927

39123928
##### Patterned Fields
39133929

0 commit comments

Comments
 (0)