Openapi-specification: 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

[dolmen]

@ponelat wrote:

Does it make sense to put in a template?

Swagger implementations have already too many security holes that allow code injection. No need to add one more vector with templated content.

[fehguy]

@dolmen ??? I have to assume you're not being serious

[tmaszk]

+1 for bearer token authorization support

[pdeschen]

+1 for bearer token authorization support

[yunixon]

+1 for bearer token authorization support

[ePaul]

Just a note, you don't have to write just a +1 comment, you can add your vote to other people's comments using the reaction button (" + 😀") on the top left of the comment.

[webron]

Kinda wish github added proper voting mechanism instead of the reaction button.

[lucj]

Any update on this feature ? Any way to use "Bearer TOKEN" in the Authorization header ?

[jmls]

as @lucj asked: any news ? I've just hit this barrier :(

[darrelmiller]

It is on our backlog. We haven't forgotten. It just hasn't bubbled to the top of the list yet.

[jmls]

/me turns the heat to "high", hoping it bubbles more ;)

Thanks for the quick response

[darrelmiller]

@jmls :-) Unfortunately, no matter how fast we get it into the 3.0 spec, there is still the "tooling needs to start supporting 3.0" delay.

[jmls]

Oddly enough, it looks like if I define oauth2 as the security, the language generator I'm wanting to use (typescript-nodejs) seems to generate the code I need ...

export class OAuth implements Authentication {
    public accessToken: string;

    applyToRequest(requestOptions: request.Options): void {
        requestOptions.headers["Authorization"] = "Bearer " + this.accessToken;
    }
}

then within each "api" I have

 protected authentications = {
        'default': <Authentication>new VoidAuth(),
        'my_auth': new OAuth(),
    }

and for each endpoint

        this.authentications.my_auth.applyToRequest(requestOptions);
        this.authentications.default.applyToRequest(requestOptions);
[snip]
        return new Promise<{ response: http.ClientResponse; body: any;  }>((resolve, reject) => {
            request(requestOptions, (error, response, body) => {

I haven't gotten round to testing just yet, but the generated code seems to solve my issues ;)

[darrelmiller]

I have attempted to address the missing support for bearer/JWT in this PR #807 Feedback encouraged. I'm not a fan of the bearerFormat field but as there is no standard for communicating this to clients, I'm not sure what the best approach is.

[cikasfm]

+1 for Bearer 👍

[okkedek]

+1 for Bearer support

[cschachinger]

+1 for Bearer support

[vincentbarat]

+1 for Bearer

[basharov]

As a temporary solution that seems to work, at least to me, is to add "Bearer " prefix manually in the auth dialog of Swagger UI.

[jtn-d]

+1 for Bearer

[teemuniiranen]

+1 for JWT Bearer token

[CollinGraves]

Need. JWT. Please.

[fehguy]

@CollinGraves it _will_ be supported in 3.0 through https://github.com/OAI/OpenAPI-Specification/pull/818

[dsx1986]

+1 for JWT Bearer

[fehguy]

Already added, no need to +1 here :)

[ratanakpek]

I got error, I try to install the swagger but it error about $urltoDoc,.... in views/vendor/l5-swagger.index.blade.php. Please kindly help! Thanks!

Message error: below is the error msg.

https://2.bp.blogspot.com/-wlExmpcjcjw/WNKq_J7YeZI/AAAAAAAAC5g/ftwwzC1Rr0s3Jyz6AnehJCqvXC1zoWJPQCLcB/s1600/15.PNG

[ePaul]

@ratanakpek please note that this repository is about the OpenAPI specification, not any specific implementation. This issue specifically is about the next version of OpenAPI, for which there are no implementations yet.
It looks like you have a problem with some tooling (not sure which one) – please open an issue there (first have a look whether there already is an issue for this.) You'll need to provide more information, though.

[paulocdf]

Is it possible now to have the apikey using the Bearer authentication?

Authorization: Bearer <apiKey>

[MikeRalphson]

Yes, in v3.0 - see this example. You can omit the bearerFormat hint if you want.

Note that apiKey and http are different types of securityScheme.

[twitnic]

@MikeRalphson with:

type: http
scheme: bearer
bearerFormat: JWT

I get: "User Warning: @OA\SecurityScheme() is missing key-field: "securityScheme""

[MikeRalphson]

@twitnic that sounds like a problem with a specific tool, not with the specification itself.