You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `security` section is a list of [Security Requirement Objects](/openapi/security#security-requirement-object) that apply to all operations in the API (if defined at the [document](/openapi#openapi-document-structure) level) or to a specific operation (if defined at the [operation](/openapi/paths/operations) level).
3
+
When designing an API, it is important to consider the security requirements for accessing the API. OpenAPI 3.1 provides a way to define security requirements at both the document and operation levels.
4
4
5
-
Operation-level security requirements override any security requirements defined at the document level.
5
+
Security requirements are defined as a list of [Security Requirement Objects](/openapi/security#security-requirement-object) in the `security` section. Each object in the list represents a set of security requirements that must be satisfied to access the API.
6
+
7
+
To add security to an API as a whole, the `security` keyword must be defined at the [document](/openapi#openapi-document-structure) level.
8
+
9
+
Likewise, to add security to a specific operation, the `security` keyword must be defined at the [operation](/openapi/paths/operations) level.
10
+
11
+
Security requirements defined at the operation level override the security requirements defined at the document level.
6
12
7
13
If not provided at the document level, the default security requirements are assumed to be `[]`, an empty array, meaning no security is required to access the API.
8
14
9
-
Example:
15
+
The following example requires an API key to access the API:
10
16
11
17
```yaml
12
18
security:
@@ -19,17 +25,39 @@ components:
19
25
in: header
20
26
```
21
27
22
-
The named security schemes referenced **_must_** be [Security Scheme Objects](/openapi/security/security-schemes) defined in the [Components Object](/openapi/components) under the `securitySchemes` field.
28
+
In valid OpenAPI 3.1, the [Security Requirement Objects](/openapi/security#security-requirement-object) listed in `security` sections may only reference [Security Scheme Objects](/openapi/security/security-schemes) that are defined in the [Components Object](/openapi/components) under the `securitySchemes` field. In other words, the `security` section may not contain inline security schemes, and it may not contain security schemes that are not defined yet.
23
29
24
-
Security can also be made optional by providing an empty object (`{}`) in the list of security requirements. For example:
30
+
## Security Requirement Object
25
31
26
-
```yaml
27
-
security:
28
-
- apiKey: []
29
-
- {}
30
-
```
32
+
A Security Requirement Object defines a map of security scheme names to [scopes or roles](#security-requirement-scopes-or-roles) that are required to access the API. The names **_must_** match the names of [Security Scheme Objects](/openapi/security/security-schemes) defined in the [Components Object](/openapi/components) under the `securitySchemes` field.
| `{securitySchemeName}` | List\<string\> | | A list of [scopes or roles](#security-requirement-scopes-or-roles) required for the security scheme. If the security scheme type is `oauth2` or `openIdConnect`, this is a list of scope names required by the API consumer to be able to access or use the API. For any other type, this could contain a list of roles or similar required for the API consumer to obtain to authenticate with the API. |
37
+
38
+
## Supported Security Schemes
39
+
40
+
Before referencing a [Security Scheme](./security/security-schemes.md) as a requirement in the `security` section, it must be defined in the [Components Object](/openapi/components) under the `securitySchemes` field.
41
+
42
+
OpenAPI 3.1 supports the following security schemes:
Security can also be disabled for a specific operation by providing an empty array (`[]`) in the list of security requirements. For example:
54
+
The `security` keyword can be used in the following ways to express security requirements.
55
+
56
+
### Disabling Security
57
+
58
+
Security can be _disabled_ for a specific operation by providing an empty array (`[]`) in the list of security requirements.
59
+
60
+
In this example, the `POST` operation in the `/auth` path does not require security:
33
61
34
62
```yaml
35
63
paths:
@@ -38,30 +66,28 @@ paths:
38
66
operationId: authenticate
39
67
summary: Authenticate with the API
40
68
security: [] # Disable security for this operation
41
-
requestBody:
42
-
required: true
43
-
content:
44
-
application/json:
45
-
schema:
46
-
type: object
47
-
properties:
48
-
username:
49
-
type: string
50
-
password:
51
-
type: string
52
-
responses:
53
-
"200":
54
-
description: The api key to use for authenticated endpoints
55
-
content:
56
-
application/json:
57
-
schema:
58
-
type: object
59
-
properties:
60
-
token:
61
-
type: string
69
+
# ...
70
+
```
71
+
72
+
### Optional Security
73
+
74
+
Security can also be made optional by providing an empty object (`{}`) in the list of security requirements.
75
+
76
+
In this example, the API may be accessed with or without an API key:
77
+
78
+
```yaml
79
+
security:
80
+
- apiKey: []
81
+
- {}
62
82
```
63
83
64
-
Security can be made completely optional for a specific operation by providing an empty object (`{}`) in the list of security requirements. For example:
84
+
### Adding Optional Security to a Specific Operation
85
+
86
+
Security can be made _optional_ for a specific operation by providing an empty object (`{}`) in the list of security requirements.
87
+
88
+
This does not disable the security requirements defined at the document level, but makes them optional for this specific operation.
89
+
90
+
In this example, the `GET` operation in the `/drinks` path _may_ be accessed with or without an API key, but if authenticated, the response will include additional information:
65
91
66
92
```yaml
67
93
paths:
@@ -71,68 +97,66 @@ paths:
71
97
summary: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information
72
98
security:
73
99
- {} # Make security optional for this operation
74
-
responses:
75
-
"200":
76
-
description: A list of drinks
77
-
content:
78
-
application/json:
79
-
schema:
80
-
type: array
81
-
items:
82
-
$ref: "#/components/schemas/Drink"
100
+
# ...
83
101
```
84
102
85
-
The combination of different security requirements can be used to express complex authorization scenarios. For example:
103
+
### Allowing a Choice of Security Schemes
104
+
105
+
To allow users to choose between multiple different security requirements, define the `security` keyword as a list of [Security Requirement Objects](/openapi/security#security-requirement-object). The API consumer can choose one of the requirements to authenticate.
106
+
107
+
In this example, the API may be accessed with an API key **OR** OAuth 2.0:
The above example allows for the API to be accessed via an API Key **OR** OAuth2.0 with both the `read` and `write` scopes.
117
+
### Requiring Multiple Security Schemes Together
118
+
119
+
If multiple schemes are required together, then the [Security Requirement Object](/openapi/security#security-requirement-object) should be defined with multiple security schemes.
110
120
111
-
If multiple schemes are required together, then the [Security Requirement Object](/openapi/security#security-requirement-object) can define multiple schemes. For example:
121
+
In this example, both an API key **AND** basic auth are required to access the API:
112
122
113
123
```yaml
114
124
security: # both apiKey AND basic is required
115
125
- apiKey: []
116
126
basic: []
117
-
components:
118
-
securitySchemes:
119
-
apiKey:
120
-
type: apiKey
121
-
name: X-API-Key
122
-
in: header
123
-
basic:
124
-
type: http
125
-
scheme: basic
126
127
```
127
128
128
-
The above example requires both an API Key **AND** basic auth to be provided.
129
+
### Complex Authorization Scenarios
129
130
130
131
This **AND**/**OR** logic along with optional (`{}`) security can be used in any combination to express complex authorization scenarios.
131
132
132
-
## Security Requirement Object
133
+
In this example, the API may be accessed with an API key **AND** OAuth 2.0 **OR** with basic authentication:
133
134
134
-
A Security Requirement Object defines a map of security scheme names to scopes that are required to access the API. The names **_must_** match the names of [Security Scheme Objects](/openapi/security/security-schemes) defined in the [Components Object](/openapi/components) under the `securitySchemes` field.
| `{securitySchemeName}` | List\<string\> | | A list of scopes/roles required for the security scheme. If the security scheme type is `oauth2` or `openIdConnect`, this is a list of scope names required by the API consumer to be able to access or use the API. For any other type, this could contain a list of roles or similar required for the API consumer to obtain to authenticate with the API. |
144
+
## Security Requirement Scopes or Roles
145
+
146
+
When defining an OAuth 2.0 or OpenID Connect [Security Requirement Object](/openapi/security#security-requirement-object) for an operation, the `{securitySchemeName}` field should contain a list of scopes or roles required for the security scheme.
147
+
148
+
For example, the following security requirement object requires the `read` and `write` scopes for the `oauth2` security scheme:
0 commit comments