Single sign-on

Single sign-on using JSON Web Tokens (JWT)

JSON Web Tokens (JWT)

For single sign-on JSON Web Tokens (JWT) are utilized. jwt.io provides excellent information about this standard, with an overview of libraries you can use to generate tokens and a short introduction to JWTs.

Signing SSO-token

Single sign-on token signatures are encrypted asymmetrically, so the token gets signed by the XIS using a private key. This private key has a corresponding public key, which ZorgDomein can use to validate the token. So, a XIS-supplier needs to generate a private key and share the corresponding public key with ZorgDomein. Exchanging this key is done out-of-band.

Claims in token

See Table 1 for an overview of all valid claims of the SSO-token payload. It exists 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 logical id of the patient in the context claims, this is especially true for those who use the FHIR REST interface.

Example of the payload of a single-sign-on token

{
  "iss": "Demo XIS",
  "jti": "4a006a12-dc2b-470a-b031-a3682b653ba7",
  "iat": 1475482548,
  
  "user-id.system": "agb-z",
  "user-id.value": "01029999",
  "org-id.system": "agb-z",
  "org-id.value": "05029999",

  "context.patient-id": "5a4fc42a-1847-4862-a5da-7af86ac23968",
  "context.icpc": "T90",
"context.xis-transaction-id": "6fb34257-7e0d-41a1-b8a7-417a50de6d39" }

Sending token

Following upon the generating of a single sign-on token it is ready to be send to ZorgDomein, this can be done by doing a HTTP GET to https://www.zorgdomein.nl/jwt-login/ using "token" as the parameter. An example would be: 
https://www.zorgdomein.nl/jwt‑login/?token=eyJhbGciOiAiUci[...snipped for breviety]

After receiving the token ZorgDomein will validate the token through the public key of the users’ XIS. If the token is valid, the various claims in the payload are accepted, the user gets logged in and context information will be made available to the ZorgDomein application. If the token isn’t valid, the user will be shown an Access denied-error.

Single Sign-On token specifications

Single Sign-On token header

In the header of the JWT a kid needs to be set. This is the key-id for the key that is used to sign the token, a XIS-supplier receives this id after exchanging certificates with ZorgDomein.

Example of the payload of a single sign-on token header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "0f379bb9-cbb6"
}

Single Sign-On token payload

Parameter Description Datatype Required? Example value
iss Identifier of XIS issuing token String Yes Demo XIS
jti Identifier of the token, this needs to be unique for at least 1 hour String Yes 4a006a12-dc2b-470a-b031-a3682b653ba7
iat Token creation timestamp More information NumericDate Yes 1496275200
org-id.system System the organization identifier originates from String Yes fixed value: local
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 10987654
user-id.system System the user identifier originates from String, see: Table 2 Yes agb-z
user-id.value User identifier value String Yes 01234567
responsible-id.system System the user identifier of the responsible practitioner originates from String No agb-z
responsible-id.value User identifier for the responsible practitioner String No 01234567
context.patient-id Logical id by which the patient is known in XIS. Used to retrieve patient information over FHIR interface. String Rec. 456-789
context.icpc ICPC code of the patient’s problem. String No T90
context.xis-transaction-id Unique transaction identifier as defined by the XIS. If provided, this identifier will be included in all subsequent requests for the rest of the transaction.  String No 6fb34257-7e0d-41a1-b8a7-417a50de6d39

Table 1

Expiry timestamp

As mentioned in Table 1 each token has a creation timestamp (issued at). Tokens with a timestamp older than 300 seconds will not be accepted by ZorgDomein. The timestamp is not related to how long a user session on ZorgDomein can be active once it is accepted.

(Coding-)systems for user identifiers

System Parameter 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 e-mail E-mail address of user

Table 2: Use of parameters in bold is strongly recommended.

  • Deze informatie is alleen beschikbaar in het Engels.
  • The information on this page applies to ZorgDomein Integrator FHIR Edition.