Description
An OAuth2 scope required by global security in OpenAPI 3.0 must be defined in the corresponding components.securitySchemes entry's flows. Referencing an undefined name leaves the required permission unclear.
Potential impact
API users may request the wrong scope, or document validation and client generation may fail.
Remediation
Align the global requirements with the OAuth2 flow's scopes and the authorization server's configuration. Correct invalid references while retaining required permissions by adding any missing definitions. OpenID Connect uses the provider's scopes rather than local OAuth2 flow definitions.
Examples
The example removes an unnecessary error:api reference. Add the scope definition instead if it represents a required permission.
Before
json
{
"openapi": "3.0.0",
"security": [
{
"oAuth2AuthCode": [
"read:api",
"error:api"
]
}
],
"components": {
"securitySchemes": {
"oAuth2AuthCode": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://api.example.com/oauth/authorize",
"tokenUrl": "https://api.example.com/oauth/token",
"scopes": {
"read:api": "read your apis"
}
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"security": [
{
"oAuth2AuthCode": [
"read:api"
]
}
],
"components": {
"securitySchemes": {
"oAuth2AuthCode": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://api.example.com/oauth/authorize",
"tokenUrl": "https://api.example.com/oauth/token",
"scopes": {
"read:api": "read your apis"
}
}
}
}
}
}
}