Server-specific Security Requirements

[kevinoid]

OpenAPI 3 supports defining multiple servers for an API in a top-level servers array, and multiple security mechanisms in a security array at the top level or operation level, but doesn't appear to provide a way to specify which security requirements apply to which servers. Satisfying any security requirement is assumed to be sufficient for any server. This is problematic in cases where different servers require different authentication.

For example, consider an API with a production server and a sandbox server which each require OAuth2 to a corresponding authentication server (as in the Procore API):

openapi: 3.1.0
info:
  title: Server-specific Security Requirements
  version: 1.0.0
servers:
- url: https://prod.example.com
- url: https://sandbox.example.com
components:
  securitySchemes:
    prodScheme:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://login.example.com/oauth/authorize
          scopes: {}
    sandboxScheme:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://login-sandbox.example.com/oauth/authorize
          scopes: {}
security:
- prodScheme: []
- sandboxScheme: []
paths: {}

This implies sandboxScheme works for https://prod.example.com and prodScheme for https://sandbox.example.com, which are both unintended. Is there a way to avoid this that I've overlooked?

If not, I would suggest considering adding security to Server Object to cover this case. If this might be acceptable, I can start working on a PR or proposal.

Thanks for considering,
Kevin

P.S. This problem was mentioned in #1416 (comment) (about adding security to Path Item Objects) and the example use case in #2322 (about adding support for variables in security scheme URLs). #2322 is a great use case, since adding variables alone would require users to know the mapping of server variable to auth variable (e.g. sandbox.api must be used with sandbox.accounts). Adding per-Server Security Schemes could avoid the need for variables and the problem of mismatched values in that particular case.

[webron]

Thanks for bringing it up. I admit I'm a bit behind on the tickets (so I didn't get a chance to respond to the linked ones).

One thing to keep in mind is that the use of servers to declare multiple environments of the same application is something we've always discouraged from doing ever since we introduced it. There are several reasons for it, but the most obvious one is that you're exposing your environments in production if you use a single definition, and often that's an unwanted side effects.

Other problems that are derived from it is what you bring up here.

We can consider changing how we view servers and introduce better support for the use case you bring up. That said, I can't help but think that Overlays would provide a cleaner solution for multi-environments, without adding complexity to the OpenAPI Specification itself.

[kevinoid]

Thanks @webron! I agree it could be solved by Overlays (once specified/implemented). It could also be solved by maintaining separate OpenAPI document for each server. A key benefit of specifying it in OpenAPI is that it would allow OpenAPI consumers (e.g. generated clients or docs) to easily switch servers. Although that could theoretically be done with Overlays or multiple OpenAPI files if consumers are able to recognize the only changes are server/security, it seems complex, fragile, and unlikely to be widely implemented.

Such a feature could be useful for multiple public environments, as in the Procore example, but also for API white-labeling/reselling, explicit API DNS naming for regions, compliance, service-levels, or other reasons where servers have separate auth requirements.

Whether it's worth the effort to specify is, of course, your call.

Thanks again!

[kevinoid]

Thanks for weighing in @orubel.

I agree Terraform and other tools are useful for server architecture. I'm not sure scoping security to server would add much value server-side (since each server can be deployed with a separate OpenAPI doc or overlay, as it seems you are suggesting).

However, I think it adds a lot of value on the client side, particularly for generated docs and API clients. I think both are within the remit of OpenAPI, whether you call it architecture or data.

[MikeRalphson]

BTW, why is it that everytime anyone brings up lack of compliance with OWASP API3:2019 and OWASP API6:2019, it gets marked as 'OFF-TOPIC'??

It's not your mentioning of (spurious) OWASP issues - it's the fact you do it on issues which are unrelated to your well aired views on role-specific responses.

[rhys-saldanha]

I am a +1 for being able to document which security schemas apply to which servers.

One thing to keep in mind is that the use of servers to declare multiple environments of the same application is something we've always discouraged from doing ever since we introduced it

@webron Is this documented anywhere? It does make sense to enforce separate OAS documents per environment, but I'd like something written down to back me up when my team disagrees!

[webron]

@rhys-saldanha it's not documented as it's not something you cannot do. There are other things allowed by the spec that we don't necessarily recommend. You can always point your team to my comment above though ;)

[emmaLP]

Any update on this please?

I hit this issue as each environment will have a completely different oauth url base on the server url

[handrews]

This sort of thing is being addressed in Moonwalk, the project that will produce the next major version of the OpenAPI Specification. The discussion linked below outlines the areas proposed for Moonwalk and how they relate to each other. Note that the Deploying area allows for multiple deployments (a generalization of the Server Object), each of which can associate different security configurations with the API shape. The exact mechanism for defining and associating security configurations is still under discussion- see the second discussion linked below for

• Functional Areas sig-moonwalk#141

See the various security discussions and deployment discussions for some possible ways security might be configured, although I think all of those pre-date us deciding on the seven functional areas so they may not be quite consistent with that.

As with other topics unlikely to fit in the 3.x minor release line, I am going to close this in favor of work in the Moonwalk repo. However, any Moonwalk work that can be backported to 3.x will be (and we plan to include some in 3.2), so this does not necessarily mean nothing happens until 4.0.

[handrews]

I'll just add that my personal hope is that as we figure out more and more of how we want 4.0 to look, we'll keep finding ways to release those improvements in the ongoing 3.x line. Figuring out the appropriate relationship between API "shape" (the HTTP calls, payloads, etc.) its deployments, and the security configurations of each deployment is one of the more complex topics, so I don't see it as likely to make it into 3.2, which will have some more basic ideas from 4.0 included. But it's plausible that some part of this could make it into a 3.3.

We are currently planning a small, incremental, strictly-compatible-with-3.1 approach for 3.2. If that is successful, then a similarly incremental 3.3 could be done fairly quickly. It all depends on whether tooling vendors prioritize supporting 3.2.

We've also been debating making deployment+security a more-or-less separate spec that could work with either future 3.x releases or 4.0, although at this point we're not sufficiently certain of what that would look like so that discussion has been on hold.

But I just want to make clear to folks following this issue that we're trying to figure out the best way to deliver features to the community in a way that tooling vendors can accommodate. We do not want a repeat of 3.0 and 3.1 where each took multiple years to be supported. That might be unavoidable for 4.0, but that just makes it more important to deliver 3.x increments in the meantime to address community needs where possible.