Search

SSO to ZorgDomein

Introduction

By implementing the “SSO to ZorgDomein” component in a connector with ZorgDomein, you enable single sign-on to ZorgDomein for users of your application. This way they can automatically login to ZorgDomein and start a transaction, without the need to enter any credentials. This component is required to implement the Send documents component. 

Token based SSO

The implementation of SSO to ZorgDomein is based on an SSO token that the initiating application provides to ZorgDomein. This SSO token contains a number of “claims” that make some assertions about the:

  • Origin of the token
  • User that wants to login to ZorgDomein
  • Organization to which the user belongs
  • Patient being subject of the transaction
  • Task that user intents to perform in ZorgDomein

These claims are ratified by a digital signature that is part of the token. Upon reception of the SSO token ZorgDomein can use this signature to verify the authenticity of the claims. After ZorgDomein has verified the token, it can match the user and organization claims with a known user account for a known organization and create a session for this user. If the organization claims match a known organization, but the user claims do not match a known user, ZorgDomein redirects the user to a registration flow where the user can register a ZorgDomein account. After finishing the registration flow, ZorgDomein will store the user claims in the newly created account, so that the claims can automatically be matched to the ZorgDomein account for future SSO attempts.
If both the organization claims and user claims cannot be matched to any known organization or user account, access is denied.

JSON Web Tokens (JWT)

The SSO token that the application provides to ZorgDomein must conform to the JSON Web Tokens (JWT) standard. This is an open industry standard for representing claims securely between two parties. Please visit jwt.io if you are not familiar with this standard, it provides excellent information about this standard, with an overview of libraries you can use to generate tokens and a short introduction to JWTs.

A JWT always consists of the following elements:

  • header – metadata about the jwt
  • payload – set of claims
  • signature – digital signature to verify the claims

Token header

The ID token header contains the following elements:

  • alg – the signing algorithm that was used to generate the token signature.
  • typ – fixed value: JWT. Indicates that this is a JSON web token.
  • kid – id of the key that was used to sign the token.

Header example:

{
   "typ": "JWT",
   "alg": "RS256",
   "kid": "zorgdomein-2019101711300530"
}

Token payload

See table 1 for an overview of all valid claims in the SSO-token payload. It consits of a set of mandatory claims, like the issuer of the token and identifiers for the user and the organization it’s working for. Other claims are not required but still strongly preferred, like the transaction id. 

Parameter Description Datatype Required
iss Identifier of XIS issuing token String Yes
jti Identifier of the token, this needs to be unique for at least 1 hour String Yes
iat Token creation timestamp More information NumericDate Yes
org-id.system Fixed value: "local" String Yes
org-id.value Organization identifier value
NB: This parameter must contain the value of the unique organization identifier that was exchanged during auto-activation
String Yes
user-id.system System the user identifier originates from String, see: Table 2 Yes
user-id.value User identifier value String Yes
responsible-id.system System the user identifier of the responsible practitioner originates from String No
responsible-id.value User identifier for the responsible practitioner String No
context.patient-id Logical id by which the patient is known in XIS. Used to retrieve patient information over FHIR interface. NB: this claim will be deprecated in the near future!  String No
context.icpc ICPC code of the patient’s problem. String No
context.xis-transaction-id Unique transaction id as defined by the XIS, will be used to request context information from the XIS. Read more about setting application context below. If provided, this id will be included in the token that is added to all subsequent HTTP requests for the rest of the transaction.  String Rec.

Table 1: overview of all valid claims in the SSO-token payload.

System name Claim value Description
Vektis/AGB agb-z AGB-code
UZI uzi-nr-pers UZI
BIG-register big BIG-register
Local local Local identifier, most likely the logical user-id from the XIS.
E-mail email E-mail address of user

Table 2: Supported naming systems for user id claims in the SSO token. 

Token signature

Following the JWT specification, the signature is generated using the encoded header, the encoded payload, and both the key pair and algorithm specified in the header. The signature must be encrypted asymmetrically, so the token must be signed using a private key. This private key has a corresponding public key, which ZorgDomein can use to validate the token. Therefore you need to generate a private key and share the corresponding public key with ZorgDomein. Exchanging this key is done out-of-band.

Setting application context

Apart from creating a valid user session in the ZorgDomein application, the "SSO to ZorgDomein" component also supports setting a specific application context in ZorgDomein. This means that the following context parameters can be set in ZorgDomein through a single SSO call: 

  • Patient context, including insurance details.
  • Launch intent, i.e. the specific task the user intents to perform.
  • Additional input parameters for the task the user intents to perform.

These context parameters are requested by ZorgDomein by querying the following FHIR endpoints of the initiating application: 

  • Task: contains the actual values of the context parameters, or reference to other FHIR resources to contain additional context parameters. ZorgDomein will process the context.xis-transaction-id claim in the SSO token as an id of a Task resource, and will therefore perform a FHIR read request on the Task endpoint of the initiating application to obtain this resource. See the ZD Task profile for more information about the relevant context parameters. 
  • Patient: contains all relevant patient details (name, address, contact details, etc). The Task resource contains a reference to the Patient resource in Task.subject. ZorgDomein will use this reference to perform a FHIR read request to obtain this resource. See the ZD Patient profile for more information about relevant patient details. 
  • Coverage: contains the insurance details of the patient. Based on the patient id specified in the reference in Task.for, ZorgDomein will perform a FHIR search request to obtain the relevant Coverage resource. The response to this search query must be a Bundle of type search-set, which contains one Coverage resource that will be used by ZorgDomein to set some insurance details in the patient context. See the ZD Coverage profile for more information about relevant insurance details. 

Important note about the context.patient-id claim
Please note that both the context.patient-id and indirectly the context.xis-transaction-id claims contain a reference to the Patient resource which will be used to query patient details and set the patient context. This means that the patient context is redundantly present in the SSO token. Therefore the context.patient-id claim will be deprecated in the near future, but will remain supported for backwards compatibility. Please refrain from using this claim in new SSO-implementations! 

Sending token

After generating the SSO token it is ready to be sent to ZorgDomein. This can be done by doing a HTTP GET request to https://www.zorgdomein.nl/jwt-login/. The token must be included in this request using a query parameter named token. An example would be: 
https://www.zorgdomein.nl/jwt-login/?token=eyJhbGciOiAiUci[...snipped for breviety]

Validation criteria

Before a connector with ZorgDomein can be released, ZorgDomein will validate the connector against a set of validation criteria. These validation criteria consist of functional and technical validation criteria. The functional criteria for this component are listed below. 

The application must support:

  1. providing a valid SSO token to ZorgDomein.
  2. providing a Task resource to communicate application context to ZorgDomein.
  3. providing a Patient resource to communicate patient details to ZorgDomein.
  4. providing a Coverage resource to communicate insurance details to ZorgDomein.
  5. auto-activation.