How to use this book
This book takes you through implementing a Nuts spec v2 use case, from deploying the Nuts node to querying another care organization. Each page is one task: what it's for, what you need first, the steps, and how to check it worked.
Everything specific to the example use case, 360-graden-clientbeeld, is in a blue box like this one:
360-graden-clientbeeld
Values and rules that only apply to 360-graden-clientbeeld. For another use case, refer to that use case's implementation guide (IG).
Who does what
| Party | Role |
|---|---|
| Vendor | Runs the Nuts node, for all of its care organizations, and integrates it with its EHR or other software. Most of this book is for the vendor. |
| Care organization | Owns its UZI server certificate and creates its X509Credential with it (see "Get an X509Credential from a UZI certificate"). |
| Use case | Its implementation guide (IG) sets the rules: which credentials, which endpoints, which data, and on which legal basis. |
What you need from the use case's IG
| What | Used in |
|---|---|
| Discovery Service definition, per environment | "Install the use case's configuration files" |
| Policy definition, per environment | "Install the use case's configuration files" |
| Which credentials a care organization needs | "Set up a care organization" |
| Which registration parameters to publish, e.g. API endpoints | "Register on the Discovery Service" |
| The scope, and which credentials go in a token request | "Request an access token" |
| Which queries are allowed, and the rules for allowing them | "Make the FHIR call", "Validate the access token" |
Checklist
| Step | How often | Chapter |
|---|---|---|
| Deploy the Nuts node | Once per vendor, per environment | Deploy |
| Install the use case's configuration files | Once per use case, per environment | Configure the node for a use case |
| Create a subject, get and load its credentials | Once per care organization, per environment | Set up a care organization |
| Register on the Discovery Service | Once per care organization, per use case, per environment | Join the use case |
| Find the other party, request a token, make the call | Every query | Outbound: querying another party |
| Validate the token, decide whether to allow the query | Every incoming query | Inbound: handling queries |
Words used in this book
| Word | Meaning |
|---|---|
| Subject | A care organization on your Nuts node. You use its subject ID in all calls to the node's internal API. |
| DID | Decentralized identifier: a public ID with keys. Each subject has one or more DIDs. |
| did:web | The DID method used in spec v2. Its DID document is published on your node's public web address. |
| Verifiable Credential | A signed statement about a subject, e.g. its URA number (X509Credential). Credential types are defined in the credential catalog. |
| Verifiable Presentation | One or more credentials, signed by the holder, to show them to another party. |
| Wallet | Where the node stores a subject's credentials. |
| Discovery Service | A shared list where care organizations register, so others can find them and their endpoints. |
| Discovery Server | The server that holds a Discovery Service's list. The use case says where it is. |
| Policy definition | The credentials another party must present to get an access token, per scope. |
| Scope | The name of what an access token gives access to. The use case sets it. |
| Authorization server | The part of a Nuts node that issues access tokens. |
| Introspect | Ask your Nuts node what an access token contains and whether it's valid. |
| DPoP | A way to bind an access token to the requester's key, so a stolen token can't be used. |