Security Schema, env/server dependent

[DavDeDev]

I have a microservice with endpoints secured using OAuth 2.0. The service runs in three different servers/environments (Local, Dev, and SIT), and each environment uses a different authorization server with its own Auth URL, Access Token URL, etc. Is there a way to define a single security schema that can adjust these URLs automatically based on the selected server/environment?

[karenetheridge]

tokenUrl and its friends can be indicated in the OAD as a uri-reference. This should be resolved against the the canonical uri of the OAD itself, which in 3.1.x is only provided to the implementation out-of-band as a retrieval uri ("the URL where this document was found") but in 3.2 the $self property is being added for the document itself to state what its identifier should be (and if that is also a uri-reference, that's resolved against the "retrieval uri").

Server urls in the root, path-item object and operation object already exist, but I believe these would only be used for processing the runtime request's URI (e.g. to match a request to the appropriate /paths/* entry in the document), not security URIs.

[handrews]

@karenetheridge This is all my interpretation, btw. That doesn't necessarily mean it's correct.

[karenetheridge]

This could probably use a clarification then. I'm looking through the schema at all the uri-references, and some of them seem intuitively that they'd resolve against the OAD itself with the retrieval uri and $self (e.g. jsonSchemaDialect, /info/termsOfService) and some against an http request at runtime, but I don't think the revisions for 3.2 about URIs differentiates between the two types.

[karenetheridge]

I put up my initial thoughts here - #4926

[handrews]

@karenetheridge it should be possible to fully determine the behavior of all fields from the definitions given in the sections on resolving API description URIs and API URLs.

Anything that is part of interacting with the API (including potentially-3rd-party services like auth servers) is an API URL. Anything that needs to be resolved in order to use the entire OpenAPI Description is an API Description URI and resolved against a base URI per RFC3986 (which is not necessarily the retrieval URI, even if $self is absent). Combining server URL templates and path templates involves special rules, but those are explicitly defined. Is there anything that does not fit in these categories?

[handrews]

@karenetheridge I'm not disputing that it may need clarification and there may be some things mis-categorized or unclear, just trying to figure out what isn't covered by the existing definitions.