Skip to content

Commit

Permalink
Rewording security as per @handrews' summary
Browse files Browse the repository at this point in the history
  • Loading branch information
rvedotrc committed Aug 23, 2024
1 parent 2c406f9 commit 94f0ae3
Showing 1 changed file with 10 additions and 6 deletions.
16 changes: 10 additions & 6 deletions versions/3.1.1.md
Original file line number Diff line number Diff line change
Expand Up @@ -322,15 +322,19 @@ This object MAY be extended with [Specification Extensions](#specification-exten

###### The `security` Field

The `security` field describes how requests are authorized:
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_.

- If omitted, then nothing can be inferred about the authorization requirements; the behaviour is implementation-defined.
- If present but empty (`security: []`), then the behaviour is undefined.
- Otherwise, it is an array of [Security Requirement Objects](#security-requirement-object), at least one of which needs to be satisfied for the request to be authorized.
`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:

Because the empty Security Requirement Object `{}` will always be satisfied, any `security` list that includes `{}` will allow all requests. In particular, `security: [{}]` means that no security schemes are in use (also known as "no security").
1. the `security` value given at the Operation level (if specified);
2. the `security` value given at the OpenAPI Object level (if specified);
3. the empty array (`[]`).

Individual Operations can [override this field](#operation-security).
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.

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.

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".

#### Info Object

Expand Down

0 comments on commit 94f0ae3

Please sign in to comment.