security: add support for Authorization header with Bearer authentication scheme

[dolmen]

In Swagger 2.0 there is no way to tell that the apiKey can be given in the Authorization header using a given (non-Basic) authentication scheme. For example the Bearer scheme defined in RFC 6750 that is used for OAuth2 but could be used also for non-OAuth2 authentication.

Proposal: add the API Key location authorization in the Security Scheme Object:

{
    "type": "apiKey",
    "in": "authorization-header",
    "authenticationScheme": "Bearer"
}

[fehguy]

are you saying that the apiKey scheme described here:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-scheme-object

is insufficient?

[dolmen]

Yes, of course, the security scheme of Swagger 2.0 is insufficient.

The apiKey scheme with in set to header is designed for a custom header where the api key will be the whole value of the header. For example:

{
    "type": "apiKey",
    "in": "header",
    "name": "Authorization"
}

will send this:

Authorization: <apiKey>

I need this:

Authorization: Bearer <apiKey>

[alecha]

+1, I'm using JWT and I'd need the same thing

[cabbonizio]

+1 in addition to using JWT

[dolmen]

About authentication with JWT

[fehguy]

Parent issue #585

[ChrisPearce]

+1

[jvivs]

+1

[cbornet]

+1 for JWT support. But I would prefer something like "type": "jwt" as this gives more info about the type of authentication.

[K1ll3rF0x]

Here is a related approach to add JWT support into Swagger UI project swagger-api/swagger-ui#2234.

[dolmen]

@cbornet This issue is not just about JWT.

[ponelat]

Does it make sense to put in a template?
Pro: covers a wide range of possibilities
Con: We lose the descriptive value, ie: We don't know what type of authentication (JWT, oAuth, etc) this is, we just know how the tools should implement it.

Template eg:

  type: apiKey,
  in: header,
  name: Authorization
  template: "Bearer {apiKey}"

Conversely, we could just have...

  type: bearer 
  # in header, implied
  # name Authorization, implied
  # Con: a little terse