Description
A name in an OpenAPI 3.0 operation’s security array must be defined in components.securitySchemes. Operation-level security overrides the global requirements, so it must identify the authentication method the operation actually needs.
Potential impact
Tools or API consumers may misunderstand authentication for that operation, causing requests to fail. A documentation error does not itself imply an authentication bypass on the server.
Remediation
Define each scheme referenced by the operation under the same name and verify its authentication type and scopes. Use an empty scope array for types other than OAuth2 and OpenID Connect. Check the operation’s actual authentication behavior as well.
Examples
The examples add the definition referenced by petstore_auth on the GET operation. Do not use the historical implicit flow and HTTP authorization URL as production recommendations. For new OAuth2 configurations, review HTTPS and the authorization code flow with PKCE.
Before
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
After
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"regularSecurity": {
"type": "http",
"scheme": "basic"
},
"petstore_auth": {
"type": "oauth2",
"flows": {
"implicit": {
"scopes": {
"write:pets": "modify pets in your account",
"read:pets": "read your pets"
},
"authorizationUrl": "http://example.org/api/oauth/dialog"
}
}
}
}
}
}
The revised GET requirement points to the defined petstore_auth scheme. Defining a scheme and enforcing authentication on incoming requests are separate responsibilities.