Description
A name used in the global security array in OpenAPI 3.0 must be defined in components.securitySchemes. A name mismatch makes the required authentication method unclear to API consumers.
Potential impact
Documentation tools or client generators may be unable to interpret the authentication configuration. A broken documentation reference alone does not establish that server authentication is disabled.
Remediation
Define the referenced scheme under the same name and configure it for the actual authentication method. Check the scope lists for OAuth2 and OpenID Connect; use an empty array for other scheme types. Verify authentication enforcement on the server separately.
Examples
The examples add a definition for the global petstore_auth reference. The included implicit flow and HTTP authorization URL are historical examples, not production recommendations. For a new OAuth2 configuration, 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",
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
After
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
],
"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 document provides the petstore_auth definition. The separately defined regularSecurity scheme is not selected by this security entry, and editing the document does not itself enforce server authentication.