Apicurio registry OpenAPi schema incorporating multiple authentication methods.

[wtrocki]

Definition of the problem

When generating client codebase from current apicurio registry code clients will ignore every authentication provider we use.
This means that users using SDK providing username and password will not authenticate properly.

Key challenge here is that upstream APicurio-registry is agnostic of authentication and there is no way to provide optional authentication schemes as for now: OAI/OpenAPI-Specification#14

OpenAPI spec provides number of authentication providers that can be selected but we would not know which one to use as this is mainly up to the user.
https://github.com/OAI/OpenAPI-Specification/blob/52286d305c6c742ce9dc12d62529a7e66c80f969/schemas/v2.0/schema.json#L1126-L1145

Our schema as it is will generate client without any auth supplied.
https://github.com/Apicurio/apicurio-registry/blob/2.0.0.Final/app/src/main/resources-unfiltered/META-INF/resources/api-specifications/registry/v2/openapi.json

Solutions

A. Add base64 auth to current schema

That will be quick hack but going to solve all issues we see.

B. Contribute change to OpenAPI generator for each language we use

Generators do not provide any form of authentication by default when none is specified:
SDK should allow users to register custom security scheme no matter what.
We can use custom templates to always override API client config

https://github.com/OpenAPITools/openapi-generator/blob/020883fd4da67050a6ae1b228daa8cef6849d732/modules/openapi-generator/src/main/resources/Java/ApiClient.mustache#L103-L106

C. Provide different flavours of OpenAPI files

Provide OpenAPI files with Authentication providers and separate without Authentication
No auth and Base Auth can be possible. This is far from ideal and quite problematic option.

D. Use JSON Path/Schema file extending strategy to add authentication

For RHOSR SDK and APICurio SDK we need to use OAuth and Basic Auth.
Example we use right now in Python SDK to enable users to use registry with RHOSR
https://github.com/Apicurio/apicurio-registry-client-sdk-python/blob/main/openapi/openapi.diff

E. SDK should hack authentication by specifying headers instead

const configParameters: Api.ConfigurationParameters = {
  headers: {
    'Authorization': 'Bearer ' + myToken,
  },
};

Or

const configParameters: Api.ConfigurationParameters = {
  headers: {
    'Authorization': 'Basic ' + credentialsHashed,
  },
};

[wtrocki]

Done extensive investigation on that area and:

• Fixing problem by wrapping or hacking generated code is suboptimal as OpenAPI file and UI would not allow users to call out service

• Yaml and JSON edits are not going to cover most of the cases - Deletions mainly. Additions are hard

• Different versions of OpenAPI files + merge - works nice but only for additions

Proposed quick fix

Build small CLI/Scripting that can apply additional layers to openapi files and validate if they are still valid. Using JSONPath

[wtrocki]

@EricWittmann

[EricWittmann]

@carlesarnal

[wtrocki]

Note that we have 2 factors here:

• Solution to solve problem we see right now with apicurio SDKs.
• Some future/more flexible and generic solution that solves more than Authentication use case.

[EricWittmann]

OK I'm just getting to read this. Layers is a feature that has been discussed in the OpenAPI spec community for a long time, and I think it's a fantastic idea. I can imagine all sorts of really interesting use cases for it. For me, this exactly use-case was always the one I thought was the most interesting.

Bottom line: I think the best way to solve this is with layers of some sort, as you've suggested.

To me, the problem is that OpenAPI mixes the logical and concrete pieces of an API definition into a single file. It would much better if they didn't do that. For example, WSDL actually does a better job of this separation.

So I think what makes sense is to leverage a layering approach so that we can keep the logical parts of the API definition (operations, data types, etc) separate from the concrete parts (servers, auth mechanisms, etc). +1 from me for this strategy.