Security Requirement Consistency with Server Objects

[stevendearborn]

In OpenAPI 3.0 server objects can be defined at three basic levels: 1) entire JSON document (global - all resources and operations), 2) a path (all operations on a resource), and 3) an operation [on a resource], with the more specific overriding more global definitions. Security Requirement objects can be defined/specified at two levels: 1) globally and 2) on an operation, but not for an entire path.

If a path can have one or more servers distinguished for it, then the security on a resource server MAY be different than others more globally defined and in-effect [through Swagger Editor, Swagger UI]. Thus, adding security object to a path object will provide this flexibility in definition and use. It will provide a productive shorthand to specifying the same on each operation for the same reason that servers does.

[cmheazel]

One reason to provide multiple servers (or at least URLs) it that each server supports a different authentication protocol. Even if we have Security Requirement objects at the Path level, we still cannot associate a security requirement with the server which implements that requirement. Perhaps what we need is to add a security requirement property to the Server object.

[darrelmiller]

@stevendearborn For consistency, I would agree that having SecurityRequirement objects at the path level would be logic.

@cmheazel Can you expand a little on why multiple servers that expose the same API would have different security requirements? It's the same data and there is no reason why one server can't support multiple security schemes, so I'm not sure I understand the use case.

[cmheazel]

It comes down to access control and level of trust. If you authenticate using HTTP basic, I would have a rather low level of trust that you are in-fact who you claim to be. I would allow you to see only that data which would cause little damage if it is compromised. If you authenticate using HTTPS with client certificates, then I have a high level of trust that you are who you say you are. Therefore, you can have access to a much larger set of data.
While it is true that one server can support multiple security schemes, that doesn't mean that we should require it.

[darrelmiller]

@cmheazel It's not about "requiring" that all servers implement the same security scheme. It's a cost/benefit argument for adding the ability to limit some servers to only use some security schemes. Adding stuff to the spec is cheap and easy. But requiring all the tooling folk to support it is neither.

[cmheazel]

It's about being competitive in the market. A complex spec adds cost to the tool developers. An inadequate spec adds cost to the system developers. A spec which can not meet (or is cost prohibitive to meet) the end-user needs doesn't get used at all. IMO this particular enhancement does not make the cut at this time. But it could in the future.

[databu]

Another use case of security-per-server is that there might be different URLs for different environments with different trust levels. E.g. the API might be available from an internal network only (blocked from outside by firewall) using a URL and no or basic auth, while public access from outside using a public URL requires api key.

[kgehmlich]

Throwing a +1 on this.

In our case, different environments use cookies with different names (e.g. auth-dev & auth-prod). Being able to specify the correct cookie name per server would be ideal.

[creckord]

Me as well. We have different oauth servers for different resource servers.

[kjkent]

Stumbled on this issue while searching for a resolution to the same -- in our situation, we have different OAuth2 endpoints and security requirements for dev/stage/prod environments.