Server-specific Security Requirements

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]

@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 😉

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