Swagger/OpenAPI Bearer auth with custom header name

Question

I'm defining (small parts of) an existing API (Samanage) using OpenAPI to assist with some integration work.

I need to authenticate using Bearer auth, but by sending the token in a header other than Authorize.

The server expects Bearer authentication in a header named X-Samanage-Authorization like this example:

curl -H "X-Samanage-Authorization: Bearer <TokenGoesHere>" -H 'Accept: application/vnd.samanage.v2.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json

I'm aware of https://swagger.io/docs/specification/authentication/bearer-authentication/, but it doesn't seem to help me fully.

This (OpenAPI 3)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
...
security:
- bearerAuth: []

Results in an authentication header named the default (Authorization)

curl -X GET "https://api.samanage.com/incidents/12341234.json" -H "accept: application/json" -H "Authorization: Bearer <TokenGoesHere>"

Which then fails (401).

I feel like I want this:

components:
  securitySchemes:
    bearerAuth:
      type: http
      name: X-Samanage-Authorization
      in: header
      scheme: bearer

But that fails validation in Swagger Editor as I believe a type of http doesn't allow the name component (like a type of apiKey would). I couldn't quite make full sense of the docs here to be honest.

I did read about Specification Extensions but being completely new to OpenAPI, I couldn't find any examples on how to actually implement what I need.

Any insight much appreciated!

Helen Helen · Accepted Answer · 2019-06-03T13:27:01

type: http is for HTTP authentication as defined by RFC 7235 and the IANA HTTP Authentication Scheme Registry. HTTP authentication, by definition, uses the Authorization header.

To use a custom header name, you need to define it as an API key (type: apiKey):

components:
  securitySchemes:
    bearerAuth:
      type: apiKey
      name: X-Samanage-Authorization
      in: header

Note that since it's a non-standard Bearer scheme, the clients will need to manually add the "Bearer " prefix to the token value. For example, when you click "Authorize" in Swagger UI, you'll need to enter "Bearer TOKEN" instead of just "TOKEN".

Swagger/OpenAPI Bearer auth with custom header name

1 Answers