Description
Authorization carries HTTP authentication information. OpenAPI 3.0 ignores an ordinary header parameter with this name, so model authentication through security schemes and security requirements.
Potential impact
Authentication input may be missing from documentation tools or confused with business input. Editing the document alone does not enforce server authentication.
Remediation
Define authentication in components.securitySchemes for OpenAPI 3.0 or securityDefinitions for Swagger 2.0, and reference it through security. Give unrelated inputs separate names and keep them consistent with actual request handling.
Examples
The examples incorrectly use Authorization for ID input. These OpenAPI 3.0 excerpts omit the separate path parameter definition required by /users/{id}.
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"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "header",
"name": "Authorization",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
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"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "query",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "header",
"name": "id",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
The revised ID inputs are separate from the authentication header. If the API requires authentication, configure its security scheme and server-side enforcement as well.