Support resolution of refs which require authentication

[bjhartin]

Some HTTP resources require authentication, especially in corporate environments.

When we want to extract common schema elements, e.g. create a schema registry, this becomes important. In corporate environments its common for repositories (of various kinds) to require authentication.

I'm not sure the best way to implement, but I think refs need some way to support authentication mechanisms. Maybe I missed how to do this.

[MikeRalphson]

Interesting! Do you have examples of the kind of schemes we might need to support? I can see some kind of mash up between a $ref and a security requirements object using a $ref sibling being doable.

[MikeRalphson]

Ping @Relequestual / @handrews

[bjhartin]

@MikeRalphson Header-based auth to start.

I'm publishing contracts with a github action using the html template for both Async- and Open-API, via Github action (enterprise), and I could grab whatever token is needed and pass to the generator. Then it could resolve the refs properly and render the included schemas.

[bjhartin]

I assume a change to the actual standard would take some time, but perhaps the generator could support this in a way that doesn't require a change to the standard, e.g. perhaps it could accept configuration that is logically the same as:

[{
  "domain": "x.y.z",
  "authType": "Bearer token",
  "token value": "..."
}, ...]

Which I could pass in in my CI pipeline, where the token value is exposed as a secret.

[bjhartin]

Related issues below. I've opened a separate issue with the tooling because I think this could be supported in the generator without changing the spec.

[handrews]

@bjhartin $ref values are identifiers rather than locators. While of course it's possible to retrieve references on demand, it's a security nightmare regardless of authentication. If you're writing a hypermedia client that is using OpenAPI/AsyncAPI/JSON Schema to discover new resources at runtime, you have to deal with the security problems anyway.

But in any other situation, the intended use of $ref is that resources are made available in advance, separating the concerns of location (and retrieval and the security and performance difficulties involved in it) and identification.

A $ref should be read to me "you need to look at the thing identified by this URI, which you are assumed to already know about and have available."

[handrews]

@bjhartin also note that in the OAS 3.1 Schema Object you can add custom keywords adjacent to $ref to provide additional information to tools that do want to provide on-demand resolution. This is a much more flexible approach than changing referencing as a whole to support a use case that was not intended to be within its scope in the first place.

[bjhartin]

@handres Ah, I see. I think this is better raised as an issue for the tooling which, as far as I can tell, does usually support dynamic resolution. Thanks!

[handrews]

@bjhartin reference resolution support is highly variable, and also depends on if you're using OAS 3.1 and deferring JSON Schema reference handling to the JSON Schema implementation. It also depends a lot of the security policies of your team and the performance needs of your code. Having worked in orgs that audit code for security issues and have performance requirements that can't accommodate the highly variable cost of network retrieval, I'm always a bit surprised at how often people want on-demand resolution. 🤷

But yes, I'd say this is more of a tooling concern. On-demand network reference resolution, in particular, is not part of either spec. Tools can offer whatever sort of configuration they want for it.

[handrews]

I do want to be pedantic on one more point: Reference resolution is always "dynamic" in the sense of being resolved a reference load time (or in the case of JSON Schema 2020-12's $dynamicRef, at schema evaluation time).

The question is dynamic retrieval of the target resource. And also whether tools correctly separate the concerns of identification and location (which can be done whether retrieval is dynamic or must be done in advance). AFAICT, one reason referencing is so rarely fully supported is that this distinction is often ignored.

[bjhartin]

@handrews Closing in favor of OpenAPITools/openapi-generator#15460.