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 https://github.com/OAI/OpenAPI-Specification/issues/1416#issuecomment-374868917 (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!

[orubel]

Technically this is separate from a schema as you are now talking 'architecture'; schema should be a document for 'data' (not function) related to the accessing a response using a request/response for an http api endpoint(s).

as you are now talking architecture, I would suggest Terraform or a tool that is aligned for that purpose

[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.

[orubel]

True but if security was an issue, you'd address OWASP API3:2019 & OWASP API6:2019. By not following RBAC procedures and associating a ROLE with an ednpoint, you are ASSUMING/FORCING an architectutural choice of ROLE/build or ROLE/server rather than allowing allowing resource to be built based on requesting credentials and passed data.

For example:

                "create": {
                    "METHOD":"POST",
                    "DESCRIPTION":"Create new Person",
                    "ROLES":{
                    "BATCH":["ROLE_ADMIN"],
                    "HOOK":["ROLE_ADMIN"]
                },
                    "REQUEST": {
                        "permitAll":["username","password","email","firstName","lastName"]
                    },
                    "RESPONSE": {
                        "permitAll":["username","email"],
                                        "ROLE_ADMIN":["id","version","enabled","accountExpired"]
                    }
                },

The gateway has to either create it's own ROLE-ENDPOINT association which may not sync with OpenAPI and the endpoints that OpenAPI is based on (thats right, 3 separate points to synchronize). OR... you may not have a document at all which is where the majority lay.

Making it out of compliance with OWASP API3:2019 and OWASP API6:2019.

[orubel]

description of architecture does not relate to description of endpoints. I pointed to Terraform as it is a separate doc which enables proper DRY/KISS/AOP practices to be upheld.

[orubel]

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'?? You guys are seeming to want to cherry pick security issues

[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.

[orubel]

It's not your mentioning of (spurious) OWASP issues...

I'm sorry but are you saying OWASP issues are spurious?? or just MY mentioning of them are spurious? Because if it's the latter, I would be more than happy to explain if you are having issues understanding.

[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 ;)

[orubel]

Ron that is incorrect. Its totally something you can do. I do it all the time (have been implementing this since 2015) (https://gist.github.com/orubel/6d529d39133e39b3f28d7cf1b9240236)

I've also helped Netflix and AWS team with this.

[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

[orubel]

The maintainers of OpenAPI have stated they will not support this as it is a 'static document' that does not support ROLES : https://flic.kr/p/2keNR8v

They have openly mocked those stating a need for API RULES versus testing/documentation

Owen Rubel @.***

On Fri, Aug 16, 2024 at 8:43 AM Emma Roberts @.***> wrote:

Any update on this please?

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

— Reply to this email directly, view it on GitHub https://github.com/OAI/OpenAPI-Specification/issues/2628#issuecomment-2293740145, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACDCTD2J56MBZMAPGIZKK3ZRYMZNAVCNFSM6AAAAABMUJFWPOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOJTG42DAMJUGU . You are receiving this because you were mentioned.Message ID: @.***>

[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

• OAI/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.

[orubel]

oh goody. a tool soon to be released that doesn't backport and resolve issues that have existed since 2014 and were brought up to Tony Tam in 2014 prior to Swagger becoming OpenAPI

This solves EVERYTHING.

Owen Rubel @.***

On Sat, Aug 17, 2024 at 12:54 PM Henry Andrews @.***> wrote:

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

• OAI/sig-moonwalk#141 https://github.com/OAI/sig-moonwalk/discussions/141

See the various security discussions https://github.com/OAI/sig-moonwalk/discussions?discussions_q=is%3Aopen+label%3ASecurity and deployment discussions https://github.com/OAI/sig-moonwalk/discussions?discussions_q=is%3Aopen+label%3ADeployment 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.

— Reply to this email directly, view it on GitHub https://github.com/OAI/OpenAPI-Specification/issues/2628#issuecomment-2294959794, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACDCTBBUJMTLZMYCOZ3VLDZR6S75AVCNFSM6AAAAABMUJFWPOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOJUHE2TSNZZGQ . You are receiving this because you were mentioned.Message ID: @.***>

[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.