gRPC-less Nuts network without big-bang migration to did:web

[reinkrul]

We want to move away from the gRPC network to improve reliability and debuggability. The gRPC network is used for several purposes:

• Registry ("public credentials")
• Publishing revocations (public and private credentials)
• Distributing credentials ("private credentials")
• Resolving key material

We introduced a set of new features to replace the Nuts gRPC network; OpenID4VCI, did:web and Discovery Services. If parties with an existing implementation want to start using these features, they need to migrate their implementation on at least the following points:

• Registry: clients now need to use the Discovery Client API to search for published VCs, which has different search semantics
• Credentials can't be distributed over the network any more (server-to-server). They now need to be issued over OpenID4VCI, which includes a browser and company representative requesting the credential from the issuer.
• New DIDs (did:web) need to be created for care organizations, this also means new NutsOrganizationCredentials have to be issued to those new DIDs.
• These new features store their data in a SQL database, by default in SQLite which isn't recommended in production. So parties should deploy an additional MySql or Postgres database.

Aside from that, the authorization protocol changed (from bearer token request to a Presentation Exchange based token with different API semantics), meaning authorization changes on both client and server side.

Risks

These changes are non-trivial. I suspect that, at best, the new features will be adopted with a severe delay (thinking of years?). At worst, they will never be adopted (the new product is so much better, but so different that nobody adopts it).

At the same time, we want parties to moving towards these features as soon as possible, to improve reliability/analysability of the implementations. So any non-trivial work (reworking implementation) will stall or prevent these improvements from taking effect.

Solutions

In this issue, I want to explore the possibilities of migrating parties to these new features without them having to rework their implementations.

We also should not forget to design how/when we stop supporting (remove) the "old" features.

[reinkrul]

Migrating Nuts Registry to Discovery Service

Currently, parties publish organization identifiers (NutsOrganizationCredential, KIK-v's HealthcareproviderDetailsExcerptCredential) as "public credentials" to the Nuts network. The gRPC-networkless alternative we devised is the Discovery Service, which is hosted by a Discovery Server. Clients configure the Discovery Service and hosting server by loading a JSON document known as a Discovery Definition.

Current implementation

• Nuts nodes publish their NutsOrganizationCredentials by setting publishToNetwork to true. This causes other nodes to receive the credential.
• Nuts nodes need to "trust" an issuer's DID (typically the vendor's did:nuts DID) to have their node accept public credentials from other nodes.
• Nuts nodes use DIDMan's SearchOrganization and/or VCR's SearchVCs API to search for organization credentials (e.g. to find an organization to perform an eOverdracht with).

Migration

Impact on Nuts node:

• Accept did:nuts DIDs in Discovery Services
• Accept JSON-LD credentials in Discovery Services (now we only accept JWTs)
  • The retract_jticlaim needs to be specified for JSON-LD (or implement differently, since it requires a custom JSON-LD context)
• Have Discovery Client publish did:nuts VCs as well, they now aren't in the wallet (no migration there, we planned for it to only contain did:web-related VCs), so we need a solution there

Required community actions:

• Design/decide on a Presentation Definition for NutsOrganizationCredential
• Decide who runs the Discovery Server for dev, stable, acc and production networks.
• Instruct other use cases having their own "public credentials" (KIK-v's HealthcareproviderDetailsExcerptCredential) on how to migrate as well.

Vendor changes required:

• Load the correct Presentation Definition(s) for their nodes, depending on the network

[reinkrul]

Migrating Private Credentials to Server-to-Server issued Credentials

OpenID4VCI works only with a browser involved, and current implementations use server-to-server issued credentials (KIKvGevalideerdeVraagCredential and NutsAuthorizationCredential). We need to retain this feature, but not by publishing on the network. We can use the current OpenID4VCI server-to-server implementation to migrate away from them being issued on the Nuts network.

Current implementation

• Nuts nodes publish their NutsAuthorizationCredentials by setting publishToNetwork to true and visibility to private. This causes other the node to publish an encrypted network transaction which only intended receiver Nuts node can decrypt and retrieve.
• Private credentials are used for requesting access tokens. XIS's search for the required credential, and then include it in the call to RequestAccessToken.

Migration

Impact on Nuts node:

• Add validation in wallet when receiving a server-to-server issued VC ("is this issuer allowed to put credential of type X in my wallet"?). 2-fold:
  • Allow explicit configuration of allowed issuer DID - credential type (for KIK-v's GevalideerdeVraagCredential).
  • Allow configuration of held credential type - allowed credential type ("participants of use case X (identified by credential Y) may issue me credentials of type Z" -> "parties with NutsOrganizationCredentials may send me NutsAuthorizationCredentials")

Required community actions:

• Check whether issuance over OpenID4VCI server-to-server works;
  • Did GoldenHammer 🔨 register the Nuts node-base URL in the vendor and care organization's DID documents?
  • Can we ask around (is it in the logs?)?

Vendor changes required:

• KIK-v nodes need to configure the issuer for GevalideerdeVraagCredential
• eOverdracht nodes need to configure the credential type (NutsOrganizationCredential) that allows issuance of NutsAuthorizationCredential

Process of dropping support for private credentials:

• Add flag to force usage of issuance over OpenID4VCI. This makes the call synchronous: if it fails (credential wasn't received), the HTTP call fails. The calling application (e.g. XIS) must implement a retry mechanism.

[reinkrul]

Migrating from revocations published to Nuts Network

• NutsAuthorizationCredential, revoked when the eOverdracht ends
• NutsOrganizationCredential, revoked when a care organization stops supporting Nuts or is renamed
• KIK-v's GevalideerdeVraagCredential, revoked when ... ?
• KIK-v's HealthcareproviderDetailsExcerptCredential revoked when ... ?

In v5.5: start supporting StatusList2021 In v6: enable StatusList2021 by default (when expirationDate is not set for a credential)

Current implementation

Migration

Impact on Nuts node:

Required community actions:

Vendor changes required:

Process of dropping support for Nuts-network style revocations

[reinkrul]

Migrating away from did:nuts storage on Nuts network

Credentials are issued to did:nuts DIDs, which are resolved when:

• Public keys are resolved as part of signature verification, e.g. when an access token is requested.
• Service endpoints are resolved, e.g. when a XIS wants to lookup a FHIR server, or to request an access token

did:nuts DIDs are published to the Nuts network, so to resolve them a Nuts node to be in sync with the Nuts gRPC network.

As long as there are credentials issued to did:nuts DIDs, they should be resolvable. A gRPC-less alternative could involve a did:web approach similar to the "Well-Known DID Configurations" specification:

• The did:nuts owner self-issues a DIDOwnerCredential (better name?), that contains an URL where the did:nuts document can be resolved.
• The did:nuts owner publishes the credential to a Discovery Service.
• Nuts nodes that don't support the gRPC network, resolve did:nuts by looking up the HTTP endpoint in the Discovery Service. It then reads the DID document from that endpoint.

Things to decide:

• Whether to support key rotation:
  • If we support key rotation, we need to return all versions of the DID document. The resolver then needs to check the chain of signatures of the versions of the DID document.
  • If we don't support key rotation (we assume parties never deleted/lost private keys), we can sign the credential with the private key from which the DID document was created. This proves control over the private key that created the credential, thus the authenticity of the DID document loaded from the HTTP endpoint.
• Which endpoint to use:
  • Golden Hammer's node-http-services-baseurl is a "node-to-node" endpoint, meaning PKIOverheid Private Services certificate is required. But many DID documents should already have it (we need to check this). It registers .../n2n/identity, so we resolver needs to be hosted under this URL
  • Public URL is also a good fit (and should be configured already), but might require additional reverse proxy configuration

Current implementation

Migration

Impact on Nuts node:

• v5.5: issue DIDOwnerCredential on node startup (and refresh when expires or HTTP endpoint changes)
• v5.5: expose HTTP endpoint for resolving did:nuts DIDs
• v6: discover did:nuts resolution endpoint through Discovery Service and resolve there

Required community actions:

• Have someone host the Discovery Service

Vendor changes required:

• Load Service Definition for discovery of did:nuts owner credentials

Process of dropping support for Nuts network:

• In v5.5: we add support for did:web DID resolution
• In v6: we drop support for the gRPC network, meaning did:nuts will only be resolved over HTTP
• In v6: create did:web instead of did:nuts by default

Process of dropping support for did:nuts:

• Probably in v7

[gerardsn]

related to #2548

[woutslakhorst]

issue needs work/2Bupdated to current state of the node.