Implementing a Nuts v2 Use Case
A Nuts use case enables organizations that don't directly trust each other, but rely on trusted third parties, to find each other and securely exchange data. The use case specifies which data is exchanged, on which authorization grounds, and how API endpoints can be found.
This book tells you how to implement a use case that uses Nuts spec v2: deployment and configuration, managing DIDs and credentials, registering on and searching the Discovery Service, and requesting and validating access tokens. Nuts spec v2 uses did:web and the Discovery Service. It does NOT use did:nuts or the gRPC network.
This book uses 360-graden-clientbeeld as its example use case. Steps that are the same for every use case are written in general terms. Everything specific to 360-graden-clientbeeld is in a blue box marked "360-graden-clientbeeld" (see "How to use this book" for an example). For another use case, refer to that use case's implementation guide (IG) instead.
Start here
How this book works, who does what, and what you need from the use case.
Deploy
Deploy the Nuts node and, optionally, Nuts Admin. Put the node behind a reverse proxy with the ri...
Deploy the Nuts node
There are two ways to run the Nuts part of your system. Choose one: Option What it is When to cho...
Endpoints and TLS certificates
Which endpoints you expose, to whom, and with which TLS certificate. This repeats the recommended...
Deploy admin app
Nuts Admin is an optional web application for managing your Nuts node by hand: create subjects, l...
Configure url rewrite for OAuth
Other parties look up your node's OAuth2 metadata at a .well-known URL, which always starts at t...
Configure the node for a use case
Install the Discovery Service and policy definitions you receive from the use case.
Set up a care organization
Do this once per care organization, on the vendor's Nuts node: create a subject, get an X509Crede...
Create a subject
Each care organization gets its own subject on the vendor's Nuts node. A subject is the name you ...
Get an X509Credential from a UZI certificate
Many use cases identify care organizations by their URA number. The CIBG doesn't issue Verifiable...
Load the credential into the wallet
Load the X509Credential into the care organization's wallet on the Nuts node. The node uses crede...
Obtaining credentials
Some use cases require credentials besides the X509Credential. Check the use case's Discovery Ser...
Join the use case
Do this once per care organization, per use case: register on the use case's Discovery Service so...
Outbound: querying another party
Find another care organization, request an access token, and query its FHIR API.
Find care organizations and their endpoints
Before you can query another care organization, you need its API endpoint and its authorization s...
Request an access token
To query another care organization's API, you need an access token from that organization's autho...
Make the FHIR call
With an access token, you can query the other care organization's FHIR API (or other data API). T...
Inbound: handling queries
Check the access token on incoming requests and decide whether to allow the query.
Test your setup
Check each part of your setup, from the node itself to a query with another party.
Running it
Keep credentials valid, monitor and back up the node, and fix common problems.