Revisit actions required to enable OpenID4VCI

[reinkrul]

Document what a vendor needs to do to start using (receiving, issuing) VCs over OpenID4VCI. Should be as little as possible.

A vendor currently needs to register a wallet metadata URL on each of its customer's DID documents, which is going to be very cumbersome when a vendor has more than a handful of customers. They also can't be updated transactionally, so keeping it synchronized is going to be tricky.

Therefore, we might want to introduce some conventions, e.g. when a DID document does not have a wallet metadata URL, look at its controllers for a wallet metadata base URL and inject/append the customer's DID into it to construct it (the wallet metadata URL).

[reinkrul]

Discussed with @gerardsn:

• We want parties to start using OpenID4VCI as soon as possible, with the fallback to issuing over the network. Otherwise, we won't know if actually works and subsequently don't know if we can deprecate/remove the private TX fallback.
• Thus, enabling it should be as simple and easy as possible. Having to register additional DID services is probably too big of a hurdle.
• But, we want a DID service for discovery of OpenID4VCI issuers and wallets. Probably a metadata URL which can be used as entry point for discovering additional OAuth2 services. Maybe in the form of a well-known endpoint.
• The current OAuth2 Access Token flow in the Auth module should be migrated (or merged) with the new OpenID4VCI implementation, ultimately (optionally?) removing/replacing the current oauth service registered in the eOverdracht compound services (and others).
• The new DID service endpoint would be almost the same (at least the base URL) as the existing oauth service endpoint, but routing to /n2n/identity instead of /n2n/auth/..., thus could be derived. But it could differ (in some unforeseen situation) and might not be reachable due to strict reverse proxy config (proxying only the existing /n2n URL).

Suggestion:

• Introduce a new DID service endpoint for discovery of OAuth2/OpenID4VCI services (to be specified)
• At startup the new DID service is auto-registered, if OpenID4VCI is enabled:
  • Try to resolve the new DID service on the Nuts node's DID documents
  • If not present, derive it from the oauth service. If it is reachable (self-dial), register the DID service
  • If it can't be derived or isn't reachable, log an error (and health check should indicate OpenID4VCI isn't operational)

[woutslakhorst]

Decision:

Use SAN from the client certificate to auto-discover the domain. Hopefully reverse proxies are using :443 and :5555. And use the /n2n path convention. Migration will be a go routine continually checking DID documents to migrate. A configuration option should be available to disable this. When creating and updating a DID Document the migration should run as well. This is a chicken and egg problem though.

When checking if a url is correct, the migration can dial the URL and check for data available at the URL. This would be an easy check for OIDC metadata. For GRPC this is a bit harder, a GRPC client could do the call and check the headers sent back.

The certificate and NodeDID config values are leading. (These will be replaced by domain for did:web)

Added benefit: NutsComm address registration is no longer required. (auto-detected)

[reinkrul]

We could check stable/acc/prd to find common patterns (e.g. :8443).

[reinkrul]

Registry Admin Demo needs to be able to register the metadata URL.

[woutslakhorst]

Registry Admin Demo needs to be able to register the metadata URL.

As a fallback to the auto-migrate functionality?

[reinkrul]

It all boils down to resolving the OpenID4VCI wallet URL, when a care organization wants to issue a VC to another care organization. This endpoint is hosted by the receiving care organization's vendor, thus the wallet URL should be resolvable using the vendor's DID document. Since the wallet URL is a well-known endpoint, we'll use a base URL, from which the wallet metadata can be resolved. The care organization DID document will refer to the service on the vendor's DID document.

Given the following service in the vendor document:

{
    "type": "node-http-services-baseurl",
    "serviceEndpoint": "https://example.com/n2n"
}

The care organization's document will contain:

{
    "type": "node-http-services-baseurl",
    "serviceEndpoint": "did:nuts:1234?serviceType=node-http-services-baseurl"
}

To find the actual base URL of the DID document (for either vendor or care organization), the DID is appended to the base URL (adding a forward slash if required). To resolve specific services, well-known endpoints can be used to either resolve metadata or invoke it directly.

This is for runtime discovery. We want to automatically add these references a vendor's DID documents. The process is as follows:

• After the node has been started, it will periodically resolve the service (specified above) from the vendor's DID document. If not present, it will try to register it (as specified by https://github.com/nuts-foundation/nuts-node/issues/2112#issuecomment-1578353058):
  • Tries to derive the base URL from the certificate SAN
  • Register it if it can retrieve OpenID4VCI metadata from that URL
  • Assert the metadata is for the expected wallet (check identifier)
  • Reverse proxy could take some time to start routing to the node again after restart, so after 1 minute?
• If the vendor's DID document contains the (reachable) service, it will register a reference on all care organization DID documents
  • "care organization DID documents" are those which's private keys are present, and which NutsComm endpoint references the vendor's DID document
  • It needs to do this in not too large batches, to avoid causing transaction peaks
  • Check every 5 minutes, max. 50 at a time?

[woutslakhorst]

I think it's missing 1 crucial check. When multiple SANs exist, the derived base url should be checked wit downloading the issuer metadata. This metadata contains the correct DID?

[reinkrul]

I think it's missing 1 crucial check. When multiple SANs exist, the derived base url should be checked wit downloading the issuer metadata. This metadata contains the correct DID?

It now executes a HTTP HEAD request to check for existence of the endpoint, since downloading the metadata while the node itself doesn't have its identifiers configured, would involve performing the same operation again, making it recursive.