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.

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

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.for. 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 (required if the connector is expected to be implemented at more than 10 customers).