API lacks required discoverability features

[OR13]

This issue is being raised here to track a number of implementation challenges we have faced trying to leverage this API spec.

Discovering Credential Suites and Issuer Ids

• @TallTed proposed using the HTTP Link Header
• @brianorwhatever proposed using did:web
• @OR13 proposed using .well-known configuration files

Today, there is no way to:

1. know what suites an api supports.
2. know what issuer id's an api supports (and they must be supplied in post body to create valid VCs)
3. know what credential formats are supported (only LD Proofs are supported today)
4. know what auth mechanisms an api supports (https://swagger.io/docs/specification/authentication/ could help....)

I propose the following:

Proposal 1: The APIs that use OAS3.0 MUST define securitySchemes per the OAS 3.0 spec. (@OR13 proposal addresses 4) Proposal 2: The APIs that use OAS3.0 can define the use of the Link Header for suite and issuer id discovery (@TallTed 's proposal addressing 1/2/3) Proposal 3: The APIs that use OAS3.0 MUST define the use of a .well-known JSON resource for conveying supported issuer ids and suites. (@OR13 's. proposal addressing 1/2/3)

Previously we had resolved to use OAS3.0 to define the APIs, I suggest we also use it to address these discoverability issues.

[TallTed]

Modify Proposal 2 -- HTTP Link: header can be used to address all 1/2/3/4 of your listed requirements.

This does not block, and may improve (by way of clear implementation definitions), parallel implementation of Proposals 1 and 3.

[OR13]

@TallTed I changed MUST -> can does that work? free free to put you proposal in verbatim, I thought the other aspects provided helpful context.

[TallTed]

Since you're proposing the other two as MUSTs, then all three should be so.

• You said — "(@TallTed's proposal addressing 1/2/3)".
• My version just adds /4 — "(@TallTed's proposal addressing 1/2/3/4)".

In other words, the Link: header can be used to satisfy all 4 of your listed requirements, in contrast to securitySchemes which I gather can only satisfy the first.

I believe .well-known can also be used to satisfy all 4 requirements, and will be easier to specify following clear specification of Link: header usage.

[msporny]

The group discussed this on 2022-04-19 and noted a lack of progress on this issue. It was suggested that we need a concrete use case for this issue that an implementer is attempting to address that involves a machine reading the discovery information about the VC API and then making protocol choices based off of that information.

@amiller-ims noted that there is a dynamic registration mechanism and there was a need to simplify registration process for Open Badges, dynamic registration needed URL for authz server. @ottonomy might have more thoughts on this issue.

[msporny]

The group discussed this on 2023-03-28:

@dlongley noted that related to proposals 2 and 3, given that the group has consensus on instances, that there are not use cases where a client would discover an issuer configuration and decide to use it. Instead, an instance configuration is created and given to a client (or published somewhere in an out of band fashion). Clients don't pick out configurations that they use, they're configured to use existing isntances. Client wouldn't have authorization to use instances (unless it's also granted out of band). @PatStLouis noted that discovery is listed under exchange, when doing ACAPy VC API coordinator, mapped exchange endpoint to discover feature endpoint on ACAPy, lists all DIDComm protocols on agent -- return a list on all types of exchanges you can engage with? @dlongley That might have been what Exchange Discovery could have been about, but that's not this issue. This issue is really talking about issuer discovery, and I don't think issuer discovery makes sense, but it might make sense for a client to figure out what protocols an exchange supports for delivery of VCs, but that's a different issue. @jandrieu wanted to support what @dlongley has presented, but not sure it will address the concerns. Not supportive of discovery in the way that this issue proposes. There is a conversation to get back to @OR13 and @mavarley -- if there is an important use case, let's get it in the conversation.

@PatStLouis if the title said API lacks discovery feature, there was probably a use case in mind. 2nd point, you said "dont' think it's a good idea because it allows attacks" -- doesn't that imply security by obscurity? Not a big fan of security by obscurity. Making information public forces you to be accountable for the solution and to have a good implementation, but maybe misinterpreting what's been said. @dlongley noted the issue was filed prior to figuring out instances and configurations, the previous design was built around implementing to a test suite instead of real applications. Once we introduced instances/configs, that addressed the issue. Before instances, we had a single issuer endpoint and that idea is kind of like "any client can come along, presumably with permission to use service" and could use any endpoint, any credential, any suite, and you'd have to give it authz to do all things to use feature as described. New system doesn't do security by obscurity, there are different issuer configurations and you get authz to use that particular one. In order for client to get permission, you'd need to know which one you were hitting. @PatStLouis When we say you have a difference instance, how does that work with multitenancy model? ACAPy can have one agent that does multitenancy for multiple tenants, but here we have something separate? Full instance for each issuer, is there a concept of multi-tenancy?

Alan Karp noted that we dealt with this in eSpeak -- if people find things, you can protect them with capabilities, have best of both worlds. Have a system that anyone can hit, return services available, or some capability can be used to find things that could be hidden. @dlongley Responding to Patrick... multitenancy, an implementation can have many different instances, that covers multi-tenanncy. Each item exposes n-many issuers, and each issuer can have n-many instances. An issuer can expose as many instances as it wants, each instance has its own credential issuance endpoint.

know what suites an api supports.

The instance endpoint given to the client is explicitly configured with a particular cryptographic suite. When the client makes a call to the instance endpoint, the cryptographic suite is set ahead of time and used (it is not configurable, unless through an extension to the VC API). Instead of being "discoverable", the configuration is "provided" to the client prior to the integration with the system.

know what issuer id's an api supports (and they must be supplied in post body to create valid VCs)

The answer here is the same as the above. The issuer ID is no longer provided in the API (unless done via an extension to the VC API).

know what credential formats are supported (only LD Proofs are supported today)

The answer here is the same as the above. The credential format is set on the instance endpoint. You set up instances that are meant to work on specific clients -- discovery is not how clients find services to use. You have an administrator that knows about clients that need to issue credentials, creates instances for them to use, provides authz tokens to use the instance endpoints, and the clients use those endpoints.

know what auth mechanisms an api supports (https://swagger.io/docs/specification/authentication/ could help....)

Instances have authz mechanisms they support, which are communicated out of band to the client when the instance endpoint is provided to the client.

Proposal 1: The APIs that use OAS3.0 MUST define securitySchemes per the OAS 3.0 spec. (@OR13 proposal addresses 4)

This has been done and is in the latest spec.

Proposal 2: The APIs that use OAS3.0 can define the use of the Link Header for suite and issuer id discovery (@TallTed 's proposal addressing 1/2/3) Proposal 3: The APIs that use OAS3.0 MUST define the use of a .well-known JSON resource for conveying supported issuer ids and suites. (@OR13 's. proposal addressing 1/2/3)

These two proposals have been addressed via the "instances" mechanism in the VC API spec, which pre-configured instance endpoints with issuer IDs, cryptosuites, authz mechanisms, and other administrator or system provided configurations. Those instance endpoints are then given to the appropriate clients.

@OR13 and @mavarley, given all of the above, the group has two questions:

1. Does this address the initial use cases you have?
2. Can we close this issue given that the group feels like we've addressed all of the initial points raised in the issue?

[OR13]

Yes, go ahead a close, are there any tests for the instance API and authz that can be linked to for future readers?

[msporny]

Yes, go ahead a close, are there any tests for the instance API and authz that can be linked to for future readers?

No, we haven't spec'd the instance configuration API endpoints due to lack of bandwidth. At present, all implementations implement them in a proprietary way, so the goal is to figure out how people are implementing them and see if there are any commonalities and then try to standardize that. That's not at the top of the group's priority list at present.

For now, it is expected that authz will be handled as it is handled today, with the implementation specifying what type of authz they implement. At present, multiple implementations support oauth2:

https://github.com/w3c-ccg/vc-api-test-suite-implementations/blob/main/implementations/Mesur.io.json

but zcaps have also been demonstrated here:

https://github.com/w3c-ccg/vc-api-test-suite-implementations/blob/main/implementations/DigitalBazaar.json

(and, of course, this doesn't preclude other authz mechanisms from being used).