Skip to main content

Overview (WIP)

When a (care) organization (client) wishes to exchange data with another (care) organization (resource owner) through Nuts, they agree on common technology: OAuth2, DIDs, Verifiable Credentials and Presentations and use case-specific (e.g. eOverdracht) API standards (typically HL7 FHIR).

Resource access authorization is consists of 2 parts:

  • The client proves eligibility for the use case (step 1 in the diagram below). This typically involves presenting a Verifiable Credential that proves the client is a registered care organization. It could include a use case-specific credential,¬†acquired through an audit of the client's software and/or process.
  • The Policy Decision Point checks whether the client is allowed to access the requested resources (step 4).


API Gateway

This setup deploys an API Gateway to secure access to the resource server. API Gateways are typically used to route/load balance incoming requests, monitor traffic and secure endpoints. Most off-the-shelve (e.g. Kong, APISIX, NGINX Plus) products support the required standard authorization protocols (RFC7662 OAuth2 Token Introspection) and commonly used products for authorizing access (e.g Open Policy Agent).

Although a Policy Enforcement Point (PEP) should be part of the resource server, it can be offloaded to the API Gateway if the connection between gateway and resource server is secured sufficiently to avoid man-in-the-middle attacks.

Policy Decision Point

There are 2 types of OAuth2 access token scopes;

  • wide, conceptual scopes that reflect a use case or a concept, e.g. user-profile, send-messages or eOverdracht-receiver.
  • narrow scopes that map to a specific resource, e.g. user:12345:profile, fhir:patient:12345 or fhir:patient:12345/read/write.

When wide/conceptual scopes are used, additional authorization is required when clients attempt to access a specific resource (e.g. /fhir/Patient/12345). This request authorization is performed by the Policy Decision Point that makes a decision based on the access attempt, OAuth2 access token (containing user information and scope) and often additional ACL-like information.

Example: eOverdracht

For example, given the eOverdracht use case:

  • Client requests an access token with scope eOverdracht-receiver (step 1)
    • Client proves:
      • to be a registered care organization by presenting NutsOrganizationCredential. This also identifies the organization (name and location)
      • to be participant in the eOverdracht use case by presenting eOverdrachtCredential (fictional)
  • Client resource access of eOverdracht resources (e.g. FHIR resource /Composition/<XYZ>) is checked in a data store of registered eOverdracht flows:
    • "is client (identified by DID the receiver of eOverdracht <ABC>"
    • "is client requesting one of the resources associated with the eOverdracht flow <ABC>"'
    • "is client using an allowed HTTP method"
    • "is client using an allowed OAuth2 scope (eOverdracht-receiver)"