SSO to ZorgDomein
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
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.
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.
||Identifier of XIS issuing token||String||Yes|
||Identifier of the token, this needs to be unique for at least 1 hour||String||Yes|
||Token creation timestamp More information||NumericDate||Yes|
||Fixed value: "local"||String||Yes|
||Organization identifier value
NB: This parameter must contain the value of the unique organization identifier that was exchanged during auto-activation.
||System the user identifier originates from||String, see: Table 2||Yes|
||User identifier value||String||Yes|
||System the user identifier of the responsible practitioner originates from||String||No|
||User identifier for the responsible practitioner||String||No|
||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|
||ICPC code of the patient’s problem.||String||No|
||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|
||Local identifier, most likely the logical user-id from the XIS.|
|E-mail address of user|
Table 2: Supported naming systems for user id claims in the SSO token.
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-idclaim 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
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!
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]
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:
- providing a valid SSO token to ZorgDomein.
- providing a Task resource to communicate application context to ZorgDomein.
- providing a Patient resource to communicate patient details to ZorgDomein.
- providing a Coverage resource to communicate insurance details to ZorgDomein.