Request an access token
To call an endpoint of another care organization, your node requests an access token at that organization's node (Nuts RFC003). The other party's node checks the request and, if it's valid, issues the token. Its resource server then decides whether the token gives access to the requested data.
| Role | Who | Does |
|---|---|---|
| Requester | Your care organization, through your node | Requests the token, calls the endpoint with it |
| Authorizer | The care organization that holds the data | Its node issues the token; its resource server checks it |
Use case design (spec v1)**
The use case specifies, per endpoint:
- the service the token is requested for (
service, e.g.eOverdracht-sender); - which NutsAuthorizationCredentials must be included, and whether a user identity is needed;
- the access policy: what the token gives access to, on top of the resources in the credentials.
Prerequisites
- Both nodes accept calls on
/n2nfrom other nodes, with a TLS client certificate: see Recommended deployment in the Nuts node v5.4 documentation. - The authorizer's DID document has the service, with an
oauthendpoint that is the full URL of its node's token endpoint, e.g.https://<node domain>/n2n/auth/v1/accesstoken(HTTPS in strict mode): see Set up DIDs and services. - The authorizer's node trusts your vendor DID as issuer of NutsOrganizationCredentials, and your care organization has one: see Register, find and authorize care organizations.
1. Request the access token
POST <internal Nuts interface>/internal/auth/v1/request-access-token
{
"requester": "<your care organization DID>",
"authorizer": "<other care organization DID>",
"service": "<service type>",
"credentials": [ <NutsAuthorizationCredential> ],
"identity": <signed login contract>
}
credentials: the full NutsAuthorizationCredentials the authorizer issued to you, as found with a search (see Register, find and authorize care organizations, step 5). Use[]if the use case needs none.identity: the signed login contract of the user, see Authenticate users. Leave it out if the use case doesn't need a user identity.
Your node:
- resolves the
oauthendpoint of theservicein the authorizer's DID document; - creates a JWT with the request, signed with your care organization's key;
- sends it to that endpoint, and returns the response.
{
"access_token": "<access token>",
"token_type": "bearer",
"expires_in": 60
}
Errors:
400: the request is invalid, e.g. the authorizer's DID document has no such service oroauthendpoint, or a credential is invalid.503: the authorizer's node couldn't be reached or refused the request; its log says why.
The JWT is valid for 5 seconds, so the clocks of both nodes must be in sync (allowed difference: auth.clockskew, default 5 seconds).
2. Call the endpoint
Send the token with each request to the authorizer's endpoint, until it expires. In strict mode a token is valid for 60 seconds (expires_in), so request a new one when needed:
Authorization: Bearer <access token>
Resolve the endpoint's URL as described in Set up DIDs and services.
3. Accept a token (authorizer)
Your node issues the token only when all of these hold:
- The JWT has a valid signature and isn't expired.
- The requester has a NutsOrganizationCredential from an issuer your node trusts.
- Your node manages the authorizer DID.
- The JWT is meant for the
oauthendpoint of theservicein the authorizer's DID document. - If there's an
identity: the contract is valid, and its organization name and city match a NutsOrganizationCredential of the requester. - Each NutsAuthorizationCredential is valid, not revoked, issued by the authorizer and issued to the requester.
It doesn't check:
- which data the request is for, or whether the credentials fit the
service: that's up to your resource server; - credentials of other types: they're passed on to the token unchecked.
4. Check a token at your resource server (authorizer)
For each incoming request, introspect the token (RFC7662):
POST <internal Nuts interface>/internal/auth/v1/accesstoken/introspect
Content-Type: application/x-www-form-urlencoded
token=<access token>
Deny the request if active is false. Otherwise, check:
| Field | Contains | Check |
|---|---|---|
service |
The service the token was requested for | Matches the endpoint that is called |
iss |
The authorizer DID | Is the care organization whose data is requested |
sub |
The requester DID | |
resolvedVCs |
The credentials of the request | The purposeOfUse fits the service. The requested path and operation are in resources of one of them, or allowed by the use case's access policy. If that resource has userContext: true, the token has a user |
username, initials, prefix, family_name, email, user_role, assurance_level |
The user, if the request had an identity |
Record in your audit log; username identifies the user |
vcs lists the IDs of all credentials in the request. resolvedVCs only has those that are valid now: a credential that was revoked or expired after the token was issued is left out. So use resolvedVCs, not vcs.
eOverdracht
Three token requests, see the eOverdracht leveranciersspecificatie:
| Who, for what | service |
credentials |
identity |
|---|---|---|---|
| Sender, to notify the receiver | eOverdracht-receiver |
none | no |
| Receiver, to fetch the Task | eOverdracht-sender |
The Task credential | no |
| Receiver, to fetch the patient data | eOverdracht-sender |
The patient data credential | yes |
API reference: Auth (v1)