Skip to main content

Migratie naar Nuts v6 en did:web

Status: in voorbereiding Waar: #kring-techniek-aanspreekpunt en #development

Wat het is

Onder "de v6-migratie" gaan twee verschillende dingen schuil.

De node-upgrade van v5 naar v6 is een deployment-wijziging: een SQL-store, een domeinnaam, gewijzigde poorten en TLS-terminatie. v6 is backwards compatible op API's en features, dus een toepassing die op did:nuts draait blijft werken op een v6-node.

De toepassingsmigratie van did:nuts naar did:web is een herontwerp van de toepassing: did:web en did:x509, OpenID4VCI voor de uitgifte van credentials, OID4VP als basis voor het token request, een discovery service of de GF-adressering in plaats van het gRPC-netwerk, en autorisatie op basis van de eigen administratie in plaats van de NutsAuthorizationCredential.

Die twee worden vaak als één ding besproken. Dat heeft een risico: het maakt de node-upgrade afhankelijk van besluitvorming die daar niet voor nodig is. Deze pagina houdt ze uit elkaar en beschrijft wat de kring in beide doet.

Relevantie voor Nuts

did:nuts en het gRPC-netwerk zijn deprecated en moeten uit. Het netwerk vervult op dit moment vier functies: het distribueren van publieke credentials voor adressering en zoeken, het uitwisselen van private credentials tussen partijen, het publiceren van intrekkingen, en het publiceren van DID-documenten met de bijbehorende sleutelrotatie. Voor elk daarvan moet iets in de plaats komen voordat het netwerk uit kan.

Zolang dat niet gebeurt, stapelen de kosten zich op. De resourcebehoefte van het netwerk blijft stijgen, er moet een dubbele stack in stand worden gehouden, en nieuwe leveranciers willen niet meer op did:nuts bouwen terwijl bestaande toepassingen er nog op draaien. Dat maakt aansluiten bij een bestaande toepassing moeilijker, precies waar groei zou moeten ontstaan.

De drie stappen

Stap Wat Waar het ligt
1 Node-upgrade naar v6 Kring Techniek, rechtstreeks met leveranciers en node-beheerders
2 Ontwerp van de nieuwe toepassingsversie Werkgroep Technische Convergentie, met de Werkgroep Architectuur
3 Implementatie van dat ontwerp Kring Toepassingen en de leveranciers

Stap 1 en 2 kunnen parallel: ontwerpen vraagt geen v6-node. Stap 2 vraagt wel een referentie-ontwerp voor het betreffende communicatiepatroon; zolang dat er niet is, kan een toepassing wel starten maar loopt zij het risico keuzes te maken die later afwijken. Stap 3 vereist dat stap 1 klaar is en dat er een ontwerp uit stap 2 ligt.

Daarmee is de node-upgrade de kritieke voorwaarde voor het geheel, en die kan nu al vooruit zonder dat één toepassing een besluit hoeft te nemen.

Opdracht 1: node-upgrade naar v6

Doel. Alle deelnemers draaien op een v6-node, zodat het uitfaseren van did:nuts en het gRPC-netwerk niet op de deployment vastloopt.

Scope. Inventarisatie van wie nog op v5 draait en wat hen tegenhoudt; documentatie op het niveau van een beheerder in plaats van een ontwikkelaar; en ondersteuning per leverancier bij de upgrade zelf.

Buiten scope: het omzetten van de toepassing, en het beheer van individuele nodes bij deelnemers.

Resultaat. Een beeld van het resterende v5-gebruik, bijgewerkte migratiedocumentatie, en deelnemers die de upgrade kunnen uitvoeren.

Belegging. Het producteigenaarschap van de nuts-node, zie Beheer en doorontwikkeling nuts-node.

Werkwijze. Rechtstreeks met de leveranciers en node-beheerders, zoals dat bij KIK-V is gedaan via een eigen kanaal en een gezamenlijke doorloop van de bevindingen. Dit vraagt geen tussenkomst van een toepassing.

Opdracht 2: ontwerp van de nieuwe toepassingsversie

Doel. Elke toepassing heeft een uitgewerkt ontwerp voor de overgang naar did:web, gebaseerd op een referentie-ontwerp en niet op een eigen interpretatie.

Scope. Per toepassing in beeld brengen welke technische stap aan de orde is en waar die op vastloopt; de referentie-ontwerpen per communicatiepatroon toepassen op de toepassing; en de vraagstukken die om een kaderkeuze vragen terugbrengen naar de kring.

Buiten scope: de implementatie zelf, en de planning en prioritering daarvan.

Resultaat. Per toepassing een ontwerp dat als basis voor implementatie kan dienen, en zicht op wat er per toepassing nog aan besluitvorming of ondersteuning nodig is.

Belegging. De Werkgroep Technische Convergentie, met de referentie-ontwerpen en de kaderkeuzes vanuit de Werkgroep Architectuur.

Afhankelijkheid. Deze opdracht steunt op de referentie-ontwerpen. De volgorde waarin die beschikbaar komen bepaalt dus welke toepassingen als eerste aan de beurt zijn, en dat is een keuze die in samenhang met de behoefte van de toepassingen wordt gemaakt.

Stap 3: implementatie

De implementatie ligt bij de kring Toepassingen en de leveranciers, die dat zelfstandig doen. Vanuit deze kring is er ad-hoc ondersteuning via #development. Blokkades die tijdens de implementatie ontstaan gaan naar de Werkgroep Technische Convergentie, die ze bundelt en bij de kring neerlegt als ze capaciteit of een kaderkeuze vragen.

Deze stap staat hier om de afhankelijkheid zichtbaar te maken, niet omdat de kring er een opdracht in heeft.

Wat er al ligt

Wat Waar Aandachtspunt
Migratiehandleiding voor de node en de use case wiki, v5 naar v6 migration guide Een jaar niet bijgewerkt. Bevat een geordende migratiereeks per use case, en de aanname dat een use case één partij aanwijst die de discovery server host. Die aanname is geen vastgesteld kader.
Deployment- en migratiedocumentatie readthedocs Bijgewerkt in juni 2026. Te beknopt voor beheerders; aanvullingen over poorten en beveiliging zijn toegezegd.
Analyse van de KIK-V-migratie, in twee stappen Slack, #kikv-v6-migratie Bruikbaar als model voor andere toepassingen.
Bevindingenrapportage van Tribe, met de DaaS-leveranciers via KIK-V Geen blockers gevonden voor de node-upgrade.
Inventarisatie per zorgtoepassing, met DID-methode, protocollen en credentials spreadsheet zorgtoepassing-ontwerpers Uit begin 2025, actualisatie nodig.
Ontwerphandleiding voor toepassingen wiki, designing a nuts use case

Openstaande kaderkeuzes

Deze liggen bij de Werkgroep Architectuur en komen als besluit terug in de kring:

  • Adressering in de tussenperiode. De discovery service uit v6 wordt vervangen door de GF-adressering, die nog niet beschikbaar is. Laten we partijen wachten, gebruiken ze tijdelijk de uit te faseren discovery service, of zetten we zelf een tijdelijke voorziening op?
  • Resolutie van did:nuts na het netwerk.Migratiescenario. Zonder gRPC-netwerk isGaat een centraletoepassing resolverin één keer over, of eenmigreert alias-mappingzij nodig om bestaande did:nuts-identifiers te blijven resolven. Dat veronderstelt dat de stichting de rol van trust anchor op zich neemt,stapsgewijs met deeen bijbehorendeperiode ontwikkel-waarin oud en hostingkosten.nieuw naast elkaar bestaan? Beide vragenscenario's zijnmoeten nogworden onbeantwoord.uitgewerkt, met hun gevolgen en hun voor- en nadelen.
  • Status van de migratiehandleiding. Het migratieboek bevat een geordende reeks stappen per use case en een richtingkeuze over de discovery server. Stelt de kring die reeks vast als aanbevolen pad, en wordt het boek daarvoor bijgewerkt?

Te besluiten

  1. Bevestigt de kring de scheiding in drie stappen, en de belegging van opdracht 1 en 2 zoals hierboven beschreven?
  2. Welke termijn hangen we aan opdracht 1? De node-upgrade is de kritieke voorwaarde voor stap 3 en heeft nu geen einddatum.
  3. Wordt de migratiehandleiding bijgewerkt en als aanbevolen pad vastgesteld, en wie doet dat?

Samenhang met andere trajecten

Wie erbij betrokken zijn

Rol Wie
Opdracht 1, node-upgrade Rein Krul, vanuit het producteigenaarschap
Opdracht 2, ontwerp per toepassing Werkgroep Technische Convergentie
Referentie-ontwerpen en kaderkeuzes Werkgroep Architectuur
Implementatie de toepassingen en hun leveranciers

Hoe haak je aan

Draai je nog op v5 en wil je upgraden, meld je in #development. Gaat het over het omzetten van een toepassing naar did:web, dan loopt dat via de Werkgroep Technische Convergentie.

Back to top