Openapi-specification: Allow optional Authorizations

[jacobweber]

This is an enhancement request, to allow optional authorizations. Not sure if this would be useful for others, but it would be for me.

In my case, you can access my APIs with no authorization, with OAuth, or with a set of two API keys. Depending on which you use, I may give you access to different data, but you still use the same APIs.

One way to handle this would be to allow a "required" boolean for each authorization in the API's Authorizations object.

If you did this, I could mark both of my oauth2 and apiKey authorizations as optional, which would allow you to select either or none of them. (It would also allow you to select both, but that's not really a problem.)

My case is also complicated by the fact that I need two parameters for my API key. If you wanted to treat this as a single Authorization, you'd have to allow multiple keynames for an apiKey. You could also treat it as two separate Authorizations, and just make them both optional. That's not ideal, since it wouldn't give you a way to indicate that they go together, but it would work.

[webron]

@jacobweber - in 2.0 you can specify several possible security requirements, and each of them can include multiple schemes.

So if you declare schema A, B and C you can have something like ( (A AND B) OR C ).
Does that meet your proposal?

[jacobweber]

Sounds like it would. Is that documented here? I couldn't quite find what you describe, although I haven't read it too closely yet.

[webron]

Yes. It is spread about several locations though. Perhaps I should create a section that clarifies it.
Check out the documentation for https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#swaggerSecurity and for https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#securityRequirementObject.

[jacobweber]

Will do, thanks. Yeah, an example would probably be helpful.

[webron]

Yeah, I need to add samples throughout the document (as you can obviously see). I was waiting to finalize the security part of it.

If you manage to read through it and see that it fits this issue, please close it.

[wking]

There are some examples already in swagger-spec/fixtures/v2.0/json/resources/securityExample.json:

• Security definitions
• API-wide defaults
• Per-endpoint overrides

What I think is missing is a “no security” option in securityDefinitions. Then you could have:

"security": {
  {"none": []},
  {"oauth": […]},
  {"token-1": []},
  {"token-2": []}
},
"securityDefinitions": {
  "none": {"type": "none", "description": "Publicly accessible (no authentication needed)."},
  "oauth": {…},
  "token-1": {…},
  "token-2": {…}
}

[webron]

This is an old ticket, and I believe the samples have been added to the spec.

[rkarodia]

I still can't find an example of a "no security" option. Something like the {"none": []} example proposed by @wking

[mikestead]

@webron Also in need of a none security definition so when a token isn't provided responses are restricted to public content. Otherwise I need two endpoints for pretty much the same thing.

Should I raise a new ticket for this?

[webron]

@mikestead yup

[rorisme]

+1 Also in need of none security definition. @mikestead would you please copy a reference to the new ticket here when you create it?

[elzii]

Was this functionality ever added? The ability to do as @rkarodia and @mikestead described with "no security" defaulting to public content is very needed

[rompic]

same question here :)

[webron]

Everyone, you don't need a none definition. The following has the same effect:

"security": [
  {},
  {"oauth": […]},
  {"token-1": []},
  {"token-2": []}
]

[rompic]

Thx for the fast feedback. Will look into It.

[iongion]

But the swagger validator says the spec is not valid anymore ?
How do you solve this in the end ?

[webron]

@iongion if it says it's invalid, then file a ticket on that project.

[BGehrels]

Has this feature been somehow lost in 3.0? I want to specify an API, that can be called with and without auth and will return slightly different results depending on that.

[darrelmiller]

@BGehrels I am not aware of any conversations in the work on the V3 spec to change this behavior. I don't think this option was very clearly spelled out in the V2 spec and we didn't do a better job in the V3 spec. We definitely should fix that.

[BGehrels]

Since this issue targets 2.0 and is closed, should i open a seperate issue for that?
This issue is one of the first hits when one searches for "openapi optional auth", so it may be a good idea to leave a hint here how to accomplish this in the meantime. I would do it, but i still have no idea :-)

[JohannesKuehnel]

In case someone is needing optional authorization for Swagger 2.0 and YAML files, this format worked for me: security: [ {}, JwtAuth: []] (where JwtAuth is in my securityDefinitions).

I tried several other variants but this was the only one that worked with swagger-codegen-cli (Java okhttp-gson), swagger-express-middleware for Node.js and validation with swagger-cli.