Skip to main content

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 /n2n from 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 oauth endpoint 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:

  1. resolves the oauth endpoint of the service in the authorizer's DID document;
  2. creates a JWT with the request, signed with your care organization's key;
  3. 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 or oauth endpoint, 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 oauth endpoint of the service in 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)