`.
# Configure the node for a use case
Install the Discovery Service and policy definitions you receive from the use case.
# Install the use case's configuration files
A use case gives you two kinds of configuration files. Your Nuts node needs both, for every use case you join.
| File | What it tells your node | Directory setting |
|---|---|---|
| Discovery Service definition | Where the use case's Discovery Service is, and which credentials a care organization must present to register on it | `discovery.definitions.directory` |
| Policy definition | Which credentials another party must present to get an access token from you, per scope | `policy.directory` |
Do this once per use case, per environment.
**Don't change these files.** They contain the use case's trust rules, such as which certificate authorities are trusted. A changed file can make your node accept parties it shouldn't.
## Install the files
1. Download the Discovery Service definition and the policy definition for your environment from the use case's IG.
2. Put them in the directories set in `discovery.definitions.directory` and `policy.directory`. Use any file name that ends in `.json`; the node skips other files.
3. If you use Docker, mount the directories read-only.
4. Restart the node. It reads the files at startup. If it can't read a Discovery Service definition, it doesn't start; the log says which file.
Each environment has its own files. Only install the files for the environment the node runs in. A use case typically uses the same service ID and scope in all environments; with files for two environments, the node won't start.
**360-graden-clientbeeld**
The files are in the [nl-360-ig](https://github.com/nuts-foundation/nl-360-ig) repository:
| Environment | Discovery Service definition | Policy definition | Discovery Server |
|---|---|---|---|
| Development | [discovery_360_dev.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/discovery-service-presentation-definitions/ontwikkel/discovery_360_dev.json) | [policy_360_dev.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/oauth-presentation-definitions/ontwikkel/policy_360_dev.json) | `http://localhost:9091` (a local Discovery Server) |
| Test | [discovery_360_test.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/discovery-service-presentation-definitions/test/discovery_360_test.json) | [policy_360_test.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/oauth-presentation-definitions/test/policy_360_test.json) | `https://development.nedap-nuts.nl` |
| Acceptance | [discovery_360_acc.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/discovery-service-presentation-definitions/acceptatie/discovery_360_acc.json) | [policy_360_acc.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/oauth-presentation-definitions/acceptatie/policy_360_acc.json) | `https://staging.nedap-nuts.nl` |
| Production | [discovery_360_prod.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/discovery-service-presentation-definitions/productie/discovery_360_prod.json) | [policy_360_prod.json](https://raw.githubusercontent.com/nuts-foundation/nl-360-ig/refs/heads/main/docs/oauth-presentation-definitions/productie/policy_360_prod.json) | `https://nedap-nuts.nl` |
All environments use the service ID `360-graden`.
## What's in a Discovery Service definition
| Part | What it means |
|---|---|
| `id` | The service ID. You use it in the Discovery Service API calls. |
| `endpoint` | The Discovery Server where registrations are stored |
| `presentation_max_validity` | How long a registration is valid, in seconds. Your node refreshes it before then. |
| `presentation_definition.input_descriptors` | The credentials a care organization must present to register |
| Fields with a `filter` | Requirements on a credential, e.g. which certificate authorities are trusted. This is why each environment has its own file. |
| Fields with an `id` | Values the node takes from the credentials. They show up as `fields` in search results. A pattern with a capture group, like `(\d+)`, returns only the captured part. |
**360-graden-clientbeeld**
The test definition, shortened: some fields, like `organization_id`, `organization_city` and `fhir_base_url_stu3`, are left out. It requires an X509Credential from a trusted certificate authority, and a DiscoveryRegistrationCredential with the endpoints. The `organization_ura` pattern returns only the URA.
```json
{
"id": "360-graden",
"endpoint": "https://development.nedap-nuts.nl/discovery/360-graden",
"presentation_max_validity": 259200,
"presentation_definition": {
"input_descriptors": [
{
"id": "id_uzicert_x509credential",
"constraints": {
"fields": [
{ "path": ["$.type"], "filter": { "const": "X509Credential" } },
{ "path": ["$.issuer"], "filter": { "pattern": "^did:x509:0:sha256:(GwlhBZ...|szqMaT...|svKzNx...)..." } },
{ "id": "organization_ura", "path": ["$.credentialSubject.san.otherName"], "filter": { "pattern": "^[0-9.]+-\\d+-\\d+-S-(\\d+)-00\\.000-\\d+$" } },
{ "id": "organization_name", "path": ["$.credentialSubject.subject.O"] }
]
}
},
{
"id": "id_registration_parameters_credential",
"constraints": {
"fields": [
{ "path": ["$.type"], "filter": { "const": "DiscoveryRegistrationCredential" } },
{ "id": "authorization_server_url", "path": ["$.credentialSubject.authServerURL"] },
{ "id": "fhir_base_url_r4", "path": ["$.credentialSubject.fhirR4BaseURL"], "optional": true }
]
}
}
]
}
}
```
## What's in a policy definition
A policy definition maps a scope to the credentials another party must present to get an access token for it.
- The top-level key is the scope. Another party asks for it in its token request.
- Under the scope, `organization` lists the credentials the requesting care organization must present.
- The fields with an `id` show up in the token introspection result (see "Validate the access token").
**360-graden-clientbeeld**
The policy, shortened. The scope is `360-graden`. The requester must present an X509Credential and a NutsEmployeeCredential.
```json
{
"360-graden": {
"organization": {
"input_descriptors": [
{ "id": "id_uzicert_uracredential", "...": "X509Credential from a trusted CA, as in the Discovery Service definition" },
{ "id": "id_employee", "...": "NutsEmployeeCredential with employee_name, employee_role and employee_identifier" }
]
}
}
}
```
# Set up a care organization
Do this once per care organization, on the vendor's Nuts node: create a subject, get an X509Credential from the organization's UZI server certificate, and load it into the wallet.
# Create a subject
Each care organization gets its own subject on the vendor's Nuts node. A subject is the name you use for the care organization in all calls to the Nuts node's internal API. Behind a subject, the node creates one or more DIDs (decentralized identifiers) and their keys.
Do this once per care organization, per environment.
## Before you start
- The Nuts node is deployed (see chapter "Deploy").
- did:web is enabled by default. We recommend setting `didmethods` to `web`, so the node doesn't also create a did:nuts DID, which spec v2 use cases don't need.
## Decide: generated or your own subject ID
You have to choose one of these:
| Option | How | What you do |
|---|---|---|
| Let the Nuts node generate the subject ID | Leave out `subject` in the request | Store the subject ID from the response in your own system, with the care organization |
| Bring your own subject ID | Set `subject` in the request, e.g. to the ID your system already uses for the care organization | Nothing to store: you already know the ID |
Keep in mind:
- The subject ID is public. It's part of your authorization server URL (`https:///oauth2/`), which is published on the Discovery Service and is in every access token. Don't use an ID you want to keep private.
- It may only contain letters, digits, `.`, `_` and `-`.
If you bring your own subject ID and it isn't random (e.g. a KVK number or an auto-incrementing database key), consider adding the environment at the end, e.g. `12345678-acc`. The same ID then can't exist in two environments, which reduces the chance of leaking data because environments got mixed up. The examples on this page use `careorg-a-acc`.
## Using the API
```http
POST /internal/vdr/v2/subject
Content-Type: application/json
{"subject": "careorg-a-acc"}
```
The response contains the subject ID and its DID documents:
```json
{
"subject": "careorg-a-acc",
"documents": [
{
"id": "did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142",
...
}
]
}
```
## Using Nuts Admin
1. Log in to Nuts Admin.
2. Click "Identities".
3. Click the plus sign on the right.
4. Enter the subject ID, e.g. `careorg-a-acc`.
5. Click "Create Identity".
## Check that it worked
Other parties must be able to resolve the DID from the internet. Test that with a public DID resolver:
1. Take the DID from the `id` field in the response above, e.g. `did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142`.
2. Paste it into the Universal Resolver at https://dev.uniresolver.io/ and click "Resolve".
3. It should return the DID document. If it fails, check that the node's public interface is reachable from the internet through your reverse proxy (see chapter "Deploy"). The resolver fetches the document from `https://nuts.example.com/iam/657f064a-ebef-4f0f-aa87-88ed32db3142/did.json`, so you can also open that URL from outside your network.
You need this DID in the next step, to issue the X509Credential. To look up a subject's DIDs later, use `GET /internal/vdr/v2/subject/careorg-a-acc`.
API reference: [Verifiable Data Registry (v2)](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Verifiable%20Data%20Registry%20(v2))
# Get an X509Credential from a UZI certificate
Many use cases identify care organizations by their URA number. The CIBG doesn't issue Verifiable Credentials with the URA yet, so you create one yourself from the care organization's UZI server certificate: an X509Credential.
The node uses the X509Credential to:
- register the care organization on the Discovery Service, so other parties can find it;
- prove the care organization's identity when it requests an access token from another party.
The X509Credential is:
- **issued by** the UZI certificate: the issuer is a did:x509 DID derived from the certificate, and the credential is signed with the certificate's private key;
- **issued to** the care organization's did:web DID, which belongs to its subject on your Nuts node. That subject holds the credential in its wallet.
It contains the UZI certificate, and the URA, name and city taken from it. It does **not** contain the private key.
For background, such as how the URA ends up in the credential and which certificate authority a use case trusts, see [X509Credential with UZI server certificates](https://wiki.nuts.nl/books/designing-a-nuts-use-case/page/x509credential-with-uzi-server-certificates).
Do this once per care organization, per environment.
## Who does what
The UZI certificate and its private key belong to the care organization. Ideally, the private key never leaves the care organization:
| Step | Who |
|---|---|
| Create the subject and give its did:web DID to the care organization | Vendor |
| Create the X509Credential with the UZI certificate and private key | Care organization |
| Send the X509Credential (a JWT, without the private key) to the vendor | Care organization |
| Load the X509Credential into the wallet | Vendor |
In practice, the vendor often already manages the care organization's UZI certificate, e.g. for client TLS connections. The vendor then has the private key anyway, and can create the X509Credential itself. The steps below work for the care organization and the vendor alike.
## Before you start
- The care organization has a subject, and you have its did:web DID from the vendor (see "Create a subject").
- The care organization's UZI server certificate from the CIBG:
- the full certificate chain (root CA up to the certificate itself) as a PEM file;
- the unencrypted private key of the certificate as a PEM file.
- A tool to create the credential. Choose one:
- The `nutsfoundation/go-didx509-toolkit` Docker image ([source](https://github.com/nuts-foundation/go-didx509-toolkit)), to create the credential by hand. The steps below use this tool.
- The Java library [uzi-did-x509-issuer-java](https://github.com/nuts-foundation/uzi-did-x509-issuer-java), to create the credential from your EHR or another Java application, without Docker. See its README for usage.
## Create the credential
Put the certificate chain (`certificate.pem`) and private key (`privatekey.pem`) in a directory called `certs`. From the directory that contains `certs`, run:
```shell
docker run --rm -v "$(pwd)/certs:/certs" \
nutsfoundation/go-didx509-toolkit:1.2.0 \
vc /certs/certificate.pem /certs/privatekey.pem \
"" \
```
- `` is the care organization's did:web DID, from "Create a subject".
- `` is the full name (subject DN) of the CIBG certificate authority that issued the UZI server certificate. It depends on the type of certificate:
| Certificate | CA (`CN` part of the name) |
|---|---|
| Production, G1 | `UZI-register Private Server CA G1` |
| Production, G4 (from 12 November 2026) | `UZI Server - G4 PKIo Priv G-TLS SYS - 2025` |
| CIBG test, G1 | `TEST UZI-register Private Server CA G1` |
| CIBG acceptance, G4 | `ACCEPTATIE UZI Server - G4 Priv G-TLS SYS - 2025` |
The easiest way to get the exact name: run the command with `""` as it is. The tool then fails with `ca-fingerprint certificate not found in chain` and lists the names of all certificates in your chain under `Candidates:`. Copy the one for the CA and run the command again.
Check https://hub.docker.com/r/nutsfoundation/go-didx509-toolkit/tags for the latest version.
The output is the X509Credential as a JWT (a long string starting with `eyJ`). Send it to the vendor, who loads it into the care organization's wallet (see "Load the credential into the wallet").
## Non-production environments
For non-production environments, the CIBG issues test certificates whose name, URA and city don't match the real care organization. Where the use case allows it, you can instead create a fake UZI server certificate with a test CA:
1. Check out https://github.com/nuts-foundation/go-didx509-toolkit. You need Bash and `openssl`.
2. In the `test_ca` directory, run:
```shell
./issue-cert.sh
```
The domain, UZI and AGB values can be anything; use cases don't use them.
3. The certificate chain and private key are written to the `out` directory. Copy them to your `certs` directory.
4. Create the credential as above, but with `"CN=Fake UZI Root CA"` as the CA:
```shell
docker run --rm -v "$(pwd)/certs:/certs" \
nutsfoundation/go-didx509-toolkit:1.2.0 \
vc /certs/-chain.pem /certs/.key \
"CN=Fake UZI Root CA" \
```
Which CAs an environment accepts is set in the use case's Discovery Service definition.
**360-graden-clientbeeld**
The X509Credential is the only credential a care organization needs to obtain. Accepted certificates per environment:
| Environment | Accepted certificates |
|---|---|
| Development, test | Fake UZI certificates and CIBG test certificates (G1 and acceptance G4) |
| Acceptance | CIBG test certificates (G1 and acceptance G4) and real G1 certificates. Not fake ones, and not real G4 ones. |
| Production | Real CIBG certificates only (G1 and G4) |
## Lifecycle
The X509Credential is only valid as long as the UZI certificate it was created from. Create and load a new X509Credential:
- before the UZI certificate expires, with the renewed certificate;
- when the UZI certificate is replaced or revoked;
- when the care organization's details in the certificate change (name, city).
Load the new credential as described in "Load the credential into the wallet", then remove the old one (see "Renew credentials").
# Load the credential into the wallet
Load the X509Credential into the care organization's wallet on the Nuts node. The node uses credentials from the wallet when it registers on the Discovery Service and when it requests access tokens.
The same steps work for any other credential you receive for the care organization.
## Before you start
- The care organization has a subject (see "Create a subject").
- You have the X509Credential as a JWT (see "Get an X509Credential from a UZI certificate").
## Using the API
```http
POST /internal/vcr/v2/holder/careorg-a-acc/vc
Content-Type: application/json
"eyJ..."
```
- Replace `careorg-a-acc` with the subject ID.
- The body is the JWT as a JSON string: the JWT in double quotes.
- The node returns `204 No Content` on success. It returns `400 Bad Request` if the credential is invalid, for example when it was issued to a DID that doesn't belong to this subject, or when it has expired.
## Using Nuts Admin
1. Log in to Nuts Admin.
2. Click "Identities".
3. Click the care organization.
4. Under "Credentials in Wallet", click "Upload".
5. Paste the credential (the JWT) in the input field.
6. Click "Upload Credential".
## Check that it worked
List the credentials in the wallet:
```http
GET /internal/vcr/v2/holder/careorg-a-acc/vc
```
The result should contain a credential with type `X509Credential`.
API reference: [Verifiable Credential Registry (v2)](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Verifiable%20Credential%20Registry%20(v2))
# Obtaining credentials
Some use cases require credentials besides the X509Credential. Check the use case's Discovery Service and policy definitions to see which credentials you need.
**360-graden-clientbeeld**
No other credentials are needed. You can skip this page.
A credential is issued in one of two ways, depending on the use case:
| Issued by | When | What you do |
|---|---|---|
| A trusted third party | The use case names an issuer, e.g. VZVZ or Vektis | Receive the credential from the issuer and load it into the wallet |
| The care organization itself (self-issued) | The use case allows it, e.g. because there's no trusted issuer yet | Issue it with your Nuts node, then load it into the wallet |
## Self-issue a credential
The steps below use the HealthcareProviderRoleTypeCredential as example, from the Huisartsinzage use case.
The [HealthcareProviderRoleTypeCredential](https://nuts-foundation.github.io/nl-generic-functions-ig/credential-HealthcareProviderRoleTypeCredential.html) states the type of care organization, e.g. `H1` (huisartsinstelling) or `X3` (verplegings- of verzorgingsinstelling). Huisartsinzage requires it. VZVZ might issue it in the future; until then, care organizations issue it themselves.
### Before you start
- The care organization has a subject and a did:web DID (see "Create a subject").
### Issue the credential
```http
POST /internal/vcr/v2/issuer/vc
Content-Type: application/json
{
"@context": "https://www.w3.org/2018/credentials/v1",
"type": "HealthcareProviderRoleTypeCredential",
"issuer": "did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142",
"credentialSubject": {
"id": "did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142",
"roleCodeNL": "X3"
},
"expirationDate": "2027-10-27T00:00:00Z",
"format": "jwt_vc"
}
```
- `issuer` and `credentialSubject.id` are both the care organization's DID: it issues the credential to itself.
- `format` must be `jwt_vc`. The default format (`ldp_vc`, JSON-LD) fails, because no JSON-LD context defines `roleCodeNL`.
- Set `expirationDate`. Without it, the node requires `withStatusList2021Revocation`.
The response is the credential as a JWT, in double quotes.
### Load the credential into the wallet
Issuing doesn't put the credential in the wallet. Load it as described in "Load the credential into the wallet", using the response from the step above as the request body.
### Lifecycle
Issue and load a new credential before `expirationDate`, and when the care organization's type changes.
API reference: [Verifiable Credential Registry (v2)](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Verifiable%20Credential%20Registry%20(v2))
# Join the use case
Do this once per care organization, per use case: register on the use case's Discovery Service so other parties can find you.
# Register on the Discovery Service
Register the care organization on the use case's Discovery Service, so other parties can find it and its API endpoints. In the Nuts node this is called "activating" the Discovery Service for a subject.
Do this once per care organization, per use case. The node then keeps the registration up to date by itself.
## Before you start
- The node has the use case's Discovery Service definition (see chapter "Configure the node for a use case").
- The care organization has a subject (see "Create a subject").
- The wallet has the credentials the Discovery Service definition requires (see "Load the credential into the wallet").
- You know which registration parameters the use case requires, see below.
## Registration parameters
Registration parameters are values you publish with the registration, typically API endpoints. The use case says which ones you need. The node puts them in a DiscoveryRegistrationCredential, so you don't need to issue that credential yourself.
The node always adds `authServerURL`: your Nuts node's OAuth2 authorization server URL for this subject.
**360-graden-clientbeeld**
The wallet only needs the X509Credential. Registration parameters:
| Parameter | Required | Value |
|---|---|---|
| `fhirR4BaseURL` | At least one of the two | Base URL of your FHIR R4 API |
| `fhirStu3BaseURL` | At least one of the two | Base URL of your FHIR STU3 API |
The service ID is `360-graden`.
## Using the API
```http
POST /internal/discovery/v1//
Content-Type: application/json
{
"registrationParameters": {
"": ""
}
}
```
- `` is the `id` field of the Discovery Service definition.
- `` is the care organization's subject ID, e.g. `careorg-a-acc`.
**360-graden-clientbeeld**
```http
POST /internal/discovery/v1/360-graden/careorg-a-acc
Content-Type: application/json
{
"registrationParameters": {
"fhirR4BaseURL": "https://fhir.example.com/r4"
}
}
```
The node registers right away:
| Response | Meaning | What to do |
|---|---|---|
| `200 OK` | Registered. The node refreshes the registration by itself before it expires. | Nothing |
| `412 Precondition Failed` | Not registered. The response says why, e.g. missing credentials or the Discovery Server can't be reached. The node does **not** retry by itself. | Fix the cause and call the API again |
| `404 Not Found` | Unknown service ID or subject ID | Check both IDs |
## Check that it worked
Get the registration status:
```http
GET /internal/discovery/v1//
```
- `activated` should be `true` and `status` should be `active`.
- If `status` is `error`, `error` says what went wrong, e.g. a refresh that failed.
Then check that others can find you, by searching for your own care organization, e.g. by name:
```http
GET /internal/discovery/v1/?=
```
**360-graden-clientbeeld**
The name is in the X509Credential:
```http
GET /internal/discovery/v1/360-graden?credentialSubject.subject.O=Zorgorganisatie%20A*
```
- The query parameter is a path in the credential (without `$.`), not a field ID from the definition.
- Matching is case-insensitive, and `*` is a wildcard at the start or end.
- Your care organization should be in the result, with your DID in `credential_subject_id` and your registration parameters in `registrationParameters`.
See "Find care organizations and their endpoints" for more search options.
## Changing or removing the registration
- **Change the registration parameters**, e.g. a new FHIR URL: call the `POST` again with the new values.
- **Remove the registration**:
```http
DELETE /internal/discovery/v1//
```
`200 OK` means it was removed. `202 Accepted` means the node stopped refreshing, but couldn't remove the registration from the Discovery Server; it disappears there when it expires.
API reference: [Discovery Service](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Discovery%20Service)
# 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 server URL. Find both by searching the use case's Discovery Service through your own Nuts node.
## Before you start
- The node has the use case's Discovery Service definition (see chapter "Configure the node for a use case").
## Search
```http
GET /internal/discovery/v1/?=
```
- `` is the `id` field of the Discovery Service definition.
- Without query parameters, you get all registered care organizations.
Query parameters are paths in the registered credentials:
- Write the path without `$.`, e.g. `credentialSubject.subject.O`.
- Field IDs from the definition, like `organization_name`, don't work as query parameters.
- Matching is case-insensitive. Use `*` at the start or end of a value as a wildcard.
- With several query parameters, all of them must match the same credential.
Which paths you can search on depends on the credentials the use case requires.
**360-graden-clientbeeld**
Name and city are in the X509Credential, so you can combine them:
| Search by | Query parameter |
|---|---|
| Name | `credentialSubject.subject.O=Zorgorganisatie*` |
| City | `credentialSubject.subject.L=Utrecht` |
```http
GET /internal/discovery/v1/360-graden?credentialSubject.subject.O=Zorgorganisatie*
```
Your node searches its own copy of the Discovery Service. It updates that copy every 10 minutes by default (`discovery.client.refreshinterval`), so a new registration can take that long to show up.
## The result
| Part | What it is |
|---|---|
| `credential_subject_id` | The care organization's DID |
| `fields` | Values taken from the credentials, named by the field IDs in the Discovery Service definition |
| `registrationParameters` | The values the care organization registered, e.g. its API endpoints |
| `authServerURL` | The authorization server URL. You need it to request an access token (see "Request an access token") |
Which fields and registration parameters you get depends on the use case.
**360-graden-clientbeeld**
```json
[
{
"id": "did:web:nuts.other.example:iam:2f1b7c3e-0d1a-4a7e-9a55-4b8f3c2e9d10#7c4e...",
"credential_subject_id": "did:web:nuts.other.example:iam:2f1b7c3e-0d1a-4a7e-9a55-4b8f3c2e9d10",
"fields": {
"organization_id": "did:web:nuts.other.example:iam:2f1b7c3e-0d1a-4a7e-9a55-4b8f3c2e9d10",
"organization_name": "Zorgorganisatie B",
"organization_city": "Utrecht",
"organization_ura": "87654321",
"authorization_server_url": "https://nuts.other.example/oauth2/careorg-b-acc",
"fhir_base_url_r4": "https://fhir.other.example/r4"
},
"registrationParameters": {
"authServerURL": "https://nuts.other.example/oauth2/careorg-b-acc",
"fhirR4BaseURL": "https://fhir.other.example/r4"
},
"vp": { ... }
}
]
```
`organization_ura` is the bare URA, because the definition's pattern has a capture group.
API reference: [Discovery Service](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Discovery%20Service)
# Request an access token
To query another care organization's API, you need an access token from that organization's authorization server. Your Nuts node requests it for you: it shows the authorization server the credentials the use case requires.
## Before you start
- You found the other care organization and its `authServerURL` (see "Find care organizations and their endpoints").
- Your care organization's wallet has the credentials the use case's policy requires (see "Load the credential into the wallet").
- You know the scope. The use case sets it.
**360-graden-clientbeeld**
- The wallet needs the X509Credential.
- The scope is `360-graden`.
- Each request needs a NutsEmployeeCredential for the logged-in user (see below).
## Request the token
```http
POST /internal/auth/v2//request-service-access-token
Content-Type: application/json
{
"authorization_server": "",
"scope": "",
"credentials": [ ]
}
```
| Field | Value |
|---|---|
| `` (in the URL) | The subject ID of your care organization: the one making the request, e.g. `careorg-a-acc` |
| `authorization_server` | The other care organization's `authServerURL`, from the Discovery Service search result |
| `scope` | Set by the use case |
| `credentials` | Optional. Credentials to present that aren't in the wallet, typically about the user. See below |
| `token_type` | Optional. `DPoP` (default) or `Bearer`. Use DPoP: a stolen DPoP token can't be used without your node's key |
### The user's identity
Some use cases require a credential about the logged-in user, e.g. a NutsEmployeeCredential. Pass it in `credentials`. You don't sign it, and you leave out `issuer` and `credentialSubject.id`: the node fills them in with your care organization's DID. The node's signature on the whole request protects it.
**360-graden-clientbeeld**
A NutsEmployeeCredential is required, for the other party's audit log:
| Field | Value |
|---|---|
| `name` | The user's name |
| `roleName` | The user's role, e.g. "Verpleegkundige" |
| `identifier` | The user's ID in your system |
```http
POST /internal/auth/v2/careorg-a-acc/request-service-access-token
Content-Type: application/json
{
"authorization_server": "https://nuts.other.example/oauth2/careorg-b-acc",
"scope": "360-graden",
"credentials": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://nuts.nl/credentials/v1"
],
"type": ["VerifiableCredential", "NutsEmployeeCredential"],
"credentialSubject": {
"name": "J. de Vries",
"roleName": "Verpleegkundige",
"identifier": "123456"
}
}
]
}
```
## The response
```json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
"token_type": "DPoP",
"dpop_kid": "did:web:nuts.example.com:iam:657f064a-ebef-4f0f-aa87-88ed32db3142#",
"scope": "",
"expires_in": 900
}
```
- Use `access_token` in the `Authorization` header when you call the other party's FHIR API (or other data API).
- For a DPoP token, you also need a DPoP header for every request, signed with the key in `dpop_kid` (see "Make the FHIR call").
- The node caches tokens: calling this API again returns the same token while it's valid, so you don't have to cache it yourself.
## Errors
| Response | Meaning |
|---|---|
| `400 Bad Request` | A parameter is wrong, or the authorization server returned an OAuth error |
| `412 Precondition Failed` | Your wallet doesn't have the credentials the policy requires |
| `502 Bad Gateway` | The other party's authorization server returned an error |
| `503 Service Unavailable` | The other party's authorization server can't be reached |
API reference: [Auth (v2)](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Auth%20(v2))
# Make the FHIR call
With an access token, you can query the other care organization's FHIR API (or other data API).
The token is either a DPoP token (the default) or a Bearer token, depending on `token_type` in your token request. DPoP is optional, but more secure: every request also needs a DPoP header, which proves the request comes from you, the party the token was issued to. A stolen DPoP token is useless without your node's key. Your Nuts node creates the DPoP header for you.
## Before you start
- You have an access token and its `dpop_kid` (see "Request an access token").
- You have the other care organization's API endpoint, from its `registrationParameters` (see "Find care organizations and their endpoints").
- Your client can connect to the other party's API. Data endpoints are protected with mTLS (see "Endpoints and TLS certificates").
## 1. Create the DPoP header (DPoP tokens only)
Create a new DPoP header for **every** request. It's only valid for one HTTP method and URL, and can only be used once.
```http
POST /internal/auth/v2/dpop/
Content-Type: application/json
{
"htm": "",
"htu": "",
"token": ""
}
```
| Field | Value |
|---|---|
| `` (in the URL) | `dpop_kid` from the token response, URL-encoded once, e.g. `#` becomes `%23` |
| `htm` | The HTTP method of the request you're about to make, e.g. `GET` |
| `htu` | The URL of the request you're about to make. Query parameters are ignored. |
| `token` | The access token |
The response:
```json
{
"dpop": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0In0..."
}
```
## 2. Make the request
Send the access token in the `Authorization` header with the type `DPoP`, and the DPoP header in `DPoP`:
```http
Authorization: DPoP
DPoP:
```
For a Bearer token, skip step 1 and send `Authorization: Bearer `.
## Errors
| Response from the other party | What to do |
|---|---|
| `401 Unauthorized` | The token expired, or the DPoP header doesn't match the request. Check `htm` and `htu`. If the token expired, request a new one. If it hasn't expired, the other party may have lost it: request a new token with the header `Cache-Control: no-cache`, which skips your node's token cache. |
| `403 Forbidden` | The other party doesn't allow this query, e.g. no legal basis such as consent. Check the use case's rules. |
**360-graden-clientbeeld**
Use `fhirR4BaseURL` or `fhirStu3BaseURL` from the search result, depending on which FHIR version the other party offers. The examples below use R4, with base URL `https://fhir.other.example/r4`.
**1. Get the CapabilityStatement.** It says which queries the other party supports. It doesn't need an access token, and you need it before any query other than Patient.
```http
GET https://fhir.other.example/r4/metadata
```
**2. Find the patient by BSN.** Only POST-based search is allowed. Create the DPoP header with `htm` `POST` and `htu` `https://fhir.other.example/r4/Patient/_search`.
```http
POST https://fhir.other.example/r4/Patient/_search
Content-Type: application/x-www-form-urlencoded
Authorization: DPoP
DPoP:
identifier=http://fhir.nl/fhir/NamingSystem/bsn|123456789
```
The result has the patient's ID at the other party, e.g. `Patient/abc123`.
**3. Query the data.** For example, the patient's allergies. Create a new DPoP header with `htm` `GET` and `htu` `https://fhir.other.example/r4/AllergyIntolerance`.
```http
GET https://fhir.other.example/r4/AllergyIntolerance?patient=abc123&_profile=http://nictiz.nl/fhir/StructureDefinition/nl-core-AllergyIntolerance,http://nictiz.nl/fhir/StructureDefinition/zib-AllergyIntolerance
Authorization: DPoP
DPoP:
```
- Queries select resources by FHIR profile (`_profile`). [Volume 3 of the IG](https://nuts-foundation.github.io/nl-360-ig/vol3.html) lists the query for each zib and FHIR version.
- Results are paged: use `_count` (maximum 100) and follow the bundle's `next` link.
- The order of requests is in [volume 2b of the IG](https://nuts-foundation.github.io/nl-360-ig/vol2b.html).
**360-graden-clientbeeld**
```json
{
"active": true,
"iss": "https://nuts.example.com/oauth2/careorg-a-acc",
"client_id": "https://nuts.other.example/oauth2/careorg-b-acc",
"scope": "360-graden",
"exp": 1793110000,
"cnf": { "jkt": "jlkhnp87453slfhansdhf" },
"organization_ura": "87654321",
"organization_name": "Zorgorganisatie B",
"organization_city": "Utrecht",
"employee_name": "J. de Vries",
"employee_role": "Verpleegkundige",
"employee_identifier": "123456"
}
```
- If `active` is `false`, reject the request with `401 Unauthorized`. The token is expired, invalid or unknown.
- Check that `scope` is the scope of the use case the request belongs to.
- Check that `iss` is the authorization server of the care organization whose data is requested, e.g. `https://nuts.example.com/oauth2/careorg-a-acc`. Your node hosts several care organizations and introspects tokens for all of them, so without this check a token issued for one care organization could be used to query another.
- `cnf.jkt` is only there for DPoP tokens. You need it in the next step.
Need the presented credentials themselves, e.g. for your audit log? Use `POST /internal/auth/v2/accesstoken/introspect_extended`: same result, plus the Verifiable Presentations.
## 2. Check the DPoP header (DPoP tokens only)
A DPoP token is only valid together with a DPoP header that the requester signed for this request:
```http
POST /internal/auth/v2/dpop/validate
Content-Type: application/json
{
"dpop_proof": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0In0...",
"method": "",
"url": "",
"thumbprint": "jlkhnp87453slfhansdhf",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..."
}
```
| Field | Value |
|---|---|
| `dpop_proof` | The `DPoP` header of the incoming request |
| `method` | The HTTP method of the incoming request |
| `url` | The URL of the incoming request, as the requester called it. Query parameters are ignored. |
| `thumbprint` | `cnf.jkt` from the introspection result |
| `token` | The access token from the `Authorization` header |
The node answers with `200 OK` and whether the DPoP header is valid:
```json
{
"valid": false,
"reason": "DPoP proof is expired"
}
```
- `valid: true`: the DPoP header belongs to this token and this request.
- `valid: false`: reject the request with `401 Unauthorized`. `reason` says why.
Use the URL as the requester called it, not as your API sees it after a reverse proxy rewrote it. Otherwise the check fails.
## 3. Decide whether to allow the query
The Nuts node doesn't decide whether the requester may see this data. Your application does, using the introspection result and the rules of the use case.
The use case's IG describes the rules, e.g. which legal basis is needed (such as consent registered in Mitz), and what the request must contain.
You don't have to build this from scratch: **Nuts Knooppunt** has a policy decision point (PDP). Your reverse proxy or API gateway sends it the introspection result and the request details, and gets back allow or deny. It checks things like the FHIR CapabilityStatement, required search parameters and Mitz consent. It has built-in policies per scope, e.g. for BgZ, eOverdracht and PZP. See [using the PDP](https://github.com/nuts-foundation/nuts-knooppunt/blob/main/docs/INTEGRATION.md) in the Knooppunt docs.
**360-graden-clientbeeld**
The rules are in [volume 2a of the IG](https://nuts-foundation.github.io/nl-360-ig/vol2a.html). In short:
- The request must fit the use case's FHIR CapabilityStatement.
- The requesting organization (`organization_ura`) must be identified, and the user (`employee_identifier`, `employee_role`) must be present for the audit log.
- There must be a legal basis: consent registered in Mitz, the requester is in the patient's CareTeam, or another legal basis.
- The request must be about one patient: a BSN in `/Patient/_search`, otherwise a reference to the Patient.
The IG has an [OPA policy](https://github.com/nuts-foundation/nl-360-ig/blob/main/docs/policy/policy.rego) that implements these rules. It isn't used in production yet, but can be a starting point. Knooppunt has no built-in 360-graden policy.
Log every request with the requester's organization and user, as the use case requires.
API reference: [Auth (v2)](https://nuts-node.readthedocs.io/en/latest/pages/integrating/api.html?urls.primaryName=Auth%20(v2))
# Test your setup
Check each part of your setup, from the node itself to a query with another party.
# Test your setup step by step
Check your setup in the order you built it. Each check tells you which part works; if one fails, fix it before going on.
| # | Check | Tests |
|---|---|---|
| 1 | The node runs | Deployment |
| 2 | Others can reach your node | Reverse proxy, TLS, URL rewrite |
| 3 | The wallet has the credentials | Credentials |
| 4 | You're registered and can be found | Discovery Service registration |
| 5 | You can get an access token from yourself | Policy definition, credentials, token flow, DPoP |
| 6 | You can query another party | Everything, with a real other party |
## 1. The node runs
```http
GET /health
```
Should return `200 OK` with status `UP`. If not, check the node's log.
## 2. Others can reach your node
From **outside** your network:
- Resolve a subject's DID with the [Universal Resolver](https://dev.uniresolver.io/) (see "Create a subject").
- Open your OAuth2 metadata: `https:///.well-known/oauth-authorization-server/oauth2/`. It should return JSON with `"issuer": "https:///oauth2/"`. If your node runs on a subpath, use the URL from "Check that it works" in "Configure url rewrite for OAuth" instead.
If this fails, check your reverse proxy, TLS certificate and URL rewrite (see chapter "Deploy").
## 3. The wallet has the credentials
```http
GET /internal/vcr/v2/holder//vc
```
The result should contain every credential the use case requires (see "Load the credential into the wallet").
## 4. You're registered and can be found
```http
GET /internal/discovery/v1//
```
`activated` should be `true` and `status` `active`. Then search for your own care organization (see "Register on the Discovery Service").
## 5. Get an access token from yourself
Request a token from your own authorization server, as if you were another party. This tests your policy definition, your credentials and the whole token flow.
```http
POST /internal/auth/v2//request-service-access-token
Content-Type: application/json
{
"authorization_server": "https:///oauth2/",
"scope": "",
"credentials": [ ]
}
```
`authorization_server` is your own `authServerURL`. Your node reaches it through its public URL, so this also tests your reverse proxy.
The result is an access token (see "Request an access token"). Then check it as you would an incoming request (see "Validate the access token"):
1. Introspect the token. `active` should be `true`, and the fields from the policy definition should be there.
2. Create a DPoP header for a test URL (see "Make the FHIR call"), and validate it with the same method and URL. `valid` should be `true`.
3. Validate the same DPoP header again. Now `valid` should be `false`, with reason `jti already used`: a DPoP header can only be used once.
| Response to the token request | Likely cause |
|---|---|
| `412 Precondition Failed` | The wallet doesn't have the credentials the policy requires |
| `400 Bad Request` | Wrong scope (no policy for it), or a wrong `credentials` value |
| `503 Service Unavailable` | Your node can't reach its own public URL |
**360-graden-clientbeeld**
Use scope `360-graden`, and pass a NutsEmployeeCredential with test values:
```json
{
"authorization_server": "https:///oauth2/careorg-a-acc",
"scope": "360-graden",
"credentials": [
{
"@context": ["https://www.w3.org/2018/credentials/v1", "https://nuts.nl/credentials/v1"],
"type": ["VerifiableCredential", "NutsEmployeeCredential"],
"credentialSubject": { "name": "Test User", "roleName": "Tester", "identifier": "test-1" }
}
]
}
```
The introspection result should contain `organization_id`, `organization_ura`, `organization_name`, `organization_city`, `employee_name`, `employee_role` and `employee_identifier`.
## 6. Query another party
In a test environment, agree with another vendor to test with each other's care organizations:
1. Find their care organization (see "Find care organizations and their endpoints").
2. Request a token from their authorization server, and make a query (see chapter "Outbound: querying another party").
3. Let them do the same with yours, and check your logs.
# Running it
Keep credentials valid, monitor and back up the node, and fix common problems.
# Renew credentials
Credentials expire. When one expires, the node no longer uses it, and the care organization can't register on the Discovery Service or get access tokens anymore. Renew them in time.
## What to renew, and when
| What | When | How |
|---|---|---|
| X509Credential | Before the UZI server certificate expires, or when it's replaced or revoked | Create a new one from the renewed certificate (see "Get an X509Credential from a UZI certificate") |
| Self-issued credentials | Before their `expirationDate` | Issue a new one (see "Obtaining credentials") |
| Credentials from a trusted third party | Before they expire | Ask the issuer for a new one |
| Discovery Service registration | Never: the node refreshes it by itself | — |
Keep a list of expiry dates per care organization, or check them regularly (see "Find expiring credentials" below).
## Replace a credential
1. Load the new credential into the wallet (see "Load the credential into the wallet").
2. Remove the old credential from the wallet, so the node doesn't pick it by mistake:
```http
DELETE /internal/vcr/v2/holder//vc/
```
Find the credential ID (`id`) by listing the wallet: `GET /internal/vcr/v2/holder//vc`.
The node uses the new credential right away for new access tokens. It uses it for the Discovery Service registration at the next refresh. To update the registration right away, call the registration `POST` again (see "Register on the Discovery Service").
## Find expiring credentials
List the wallet and look at each credential's `expirationDate` (or `exp` for credentials in JWT form):
```http
GET /internal/vcr/v2/holder//vc
```
This only returns valid credentials: expired ones are left out.
# Operate the node
## Monitoring
| Endpoint (internal interface) | Use it for |
|---|---|
| `/health` | Health checks by Docker or Kubernetes. Returns `200 OK` when the node is healthy. |
| `/status/diagnostics` | Details about the node's state, for administrators |
| `/metrics` | Metrics in Prometheus format |
See [monitoring](https://nuts-node.readthedocs.io/en/latest/pages/deployment/monitoring.html) in the Nuts node documentation.
## Backups
Back up both, and test that you can restore them:
- the SQL database (`storage.sql.connection`);
- the private keys (`crypto.storage`, e.g. HashiCorp Vault or Azure Key Vault).
Without the private keys, the node can't use its DIDs anymore, and every care organization needs a new subject, new credentials and a new registration.
## Upgrades
- Read the [release notes](https://nuts-node.readthedocs.io/en/latest/pages/release_notes.html) before you upgrade.
- Upgrade test and acceptance first, then production.
- Keep a fixed version in your deployment (see "Deploy the Nuts node").
## Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| The node doesn't start | A Discovery Service definition can't be read | The log says which file. Use the files from the use case's IG, unchanged. |
| A DID doesn't resolve from the internet | Reverse proxy, TLS or DNS | See "Endpoints and TLS certificates" and check 2 in "Test your setup step by step" |
| Discovery registration returns `412` | Missing or expired credentials, or the Discovery Server can't be reached | The response says which. Fix it and call the registration `POST` again: the node doesn't retry by itself. |
| Registration status is `error` | A refresh failed | `error` in the status says why. Fix it; the node retries at the next refresh. |
| You can't find a care organization that just registered | Your node updates its copy of the Discovery Service every 10 minutes by default | Wait, or check `discovery.client.refreshinterval` |
| Token request returns `412` | Your wallet doesn't have the credentials the other party's policy requires | Check the wallet and the use case's policy definition |
| Token request returns `503` | The other party's authorization server can't be reached | Check the `authServerURL` and your outbound network |
| The other party returns `401` for a token that hasn't expired | Their authorization server may have lost the token, e.g. after a restart | Request a new token with the header `Cache-Control: no-cache`, which skips your node's token cache. Don't do this by default: it adds load on both sides. |
| DPoP validation fails for incoming requests | The URL your API sees differs from the URL the requester used, e.g. after a reverse proxy rewrote it | Validate with the URL as the requester called it (see "Validate the access token") |
Still stuck? Set `verbosity` to `debug` for more detail in the log, and ask on the [Nuts Slack](https://nuts-foundation.slack.com).