JSON Web Token

Versie 08-09-2022 Status: In ontwikkeling

08-09-2022
- Artikel geüpdatet
19-04-2021
- Eerste versie gepubliceerd

Met de Single Sign-On (SSO) service kunnen zorgaanbieders hun professionals in een viewer of andere applicatie (vanaf hier: Viewer) laten inloggen met identiteitskenmerken uit het zorginformatiesysteem (XIS)

Bij een SSO-verbinding komen het partnersysteem XIS en een Viewer een technische standaard overeen om het authenticatieproces van de professional naar een viewer naadloos te laten verlopen.

Vereisten

Het uitgangspunt is dat een partnersysteem XIS een JSON Web Token (JWT) maakt met een standaard set claims en dit token indient bij een SSO-endpoint. Na validatie van de JWT zal de SSO-service de aanvragende XIS-applicatie omleiden naar de juiste bestemmings-URL (van de Viewer). Dit vereist geen verdere actie van het partnersysteem XIS anders dan het tijdig volgen van de omleiding.

De openbare RSA sleutel van het XIS dient te worden ingediend bij de leverancier van de Viewer. De Viewer leverancier autoriseert vervolgens de openbare sleutel van het XIS en staat het XIS toe om de SSO-service endpoints van de viewer te gebruiken. In dit stadium kunnen verzoeken aan de SSO-service worden gedaan.

Het sleutelpaar dat wordt gebruikt om de JWT te ondertekenen, moet een RSA-sleutelpaar zijn. Aanvaardbare sleutelgroottes zijn 2048-bits en 4096-bits RSA sleutels. De sleutelgrootte van 4096 bits wordt aanbevolen. Het Afsprakenstelsel Interoperabiliteit geboortezorg vereist sleutelparen behorende bij een UZI-servercertificaat of een PKIoverheid-private servercertificaat.

JWT (JSON Web Token)

Het gegevensformaat dat wordt gebruikt om de volledige lading aan informatie, die nodig is om de SSO-verbinding in te dienen, wordt opgeslagen in een JWT. Het formaat is een veelgebruikte standaard voor het uitwisselen van ondertekende JSON-gegevens. Documentatie over JSON Web Tokens is beschikbaar op de Wikipedia-pagina (JSON Web Token ).

Naast de gewone vereisten voor een ondertekende JWT, geldt de volgende eis met betrekking tot de JWT-handtekening:

Het algoritme dat wordt gebruikt voor de handtekening van de JWT moet RS256 of RS512 zijn. RS512 wordt aanbevolen.

Payload van de JWT

De payload van de JWT vertegenwoordigt het geheel van de authenticatie gerelateerde gegevens die van het XIS naar de Viewer worden verzonden in JSON-indeling. De JWT-payload bestaat uit vier groepen gegevens:

Algemene gegevens van het JWT-Token.
Gegevens van de zorgorganisatie waartoe de professional, die de SSO initieert, behoort.
Gegevens van de zorgprofessional die de SSO initieert.
Gegevens van de cliënt/patient waarop de gegevensuitwisseling betrekking heeft.

De onderstaande tabel documenteert alle velden in de vier groepen. Een voorbeeld van de lading is beschikbaar in de volgende sectie.

Veld naam	Data groep	Toelichting	Type	Kardinaliteit

Veld naam	Data groep	Toelichting	Type	Kardinaliteit
iss	General JWT token	Unieke identifier afgestemd tussen leverancier XIS en leverancier Viewer	String	1..1
jti	General JWT token	Uniek ID van de huidige JWT. Iedere keer dat het XIS een JWT genereert dient er ook een unieke v4 UUID gegenereerd te worden: Universally unique identifier	String	1..1
iat	General JWT token	UNIX tijdstempel op het moment van genereren JWT	Number	1..1
dest	General JWT token	URL van de applicatie waarin wordt beoogd via SSO in te loggen. Wordt aangeleverd door leverancier Viewer	String	1..1
exp	General JWT token	UNIX tijdstempel voor expiratie van het token bepaald door het XIS. Maximaal 1 uur na het iat tijdstempel.	Number	1..1
org-id	Healthcare organisation	Unieke identifier van de organisatie afgestemd tussen leverancier XIS en leverancier Viewer	String	1..1
org-ura	Healthcare organisation	De URA identifier van de organisatie	String	0..1
org-agb	Healthcare organisation	De AGB identifier van de organisatie	String	0..1
org-name	Healthcare organisation	De publieke naam van de zorgorganisatie	String	1..1
user-id	Healthcare Professional	Het unieke ID binnen het zorginformatiesysteem van de zorgverlener	String	1..1
user-uzi	Healthcare Professional	De UZI identifier van de zorgverlener	String	0..1
user-big	Healthcare Professional	De BIG identifier van de zorgverlener	String	0..1
user-agb	Healthcare Professional	De AGB identifier van de zorgverlener	String	0..1
user-given-name	Healthcare Professional	De voornaam(en) van de zorgverlener	String	1..1
user-family-name	Healthcare Professional	De achternaam van de zorgverlener	String	1..1
user-email	Healthcare Professional	Het werk emailadres van de zorgverlener. Deze moet uniek zijn voor de zorgverlener en mag niet hergebruikt worden voor verschillende gebruiker accounts	String	1..1
patient-bsn	Patient identification	Het BSN van de cliënt/Patiënt	String	1..1
patient-given-name	Patient identification	De voornaam(en) van de cliënt/patiënt	String	1..1
patient-family-name	Patient identification	Achternaam van de cliënt/patiënt	String	1..1

Organisatie-ID’s

Geaccepteerde organisatie-ID’s zijn: URA-code, AGB-code en de interne organisatie ID’s. Het interne organisatie-ID is altijd vereist en moet consistent blijven met betrekking tot een organisatie tijdens alle SSO-logins. Het gebruik van globale identifiers wordt sterk aangemoedigd, en twee worden in volgorde van voorkeur weergegeven; het gebruik van alleen een interne identifiers wordt afgeraden.

Het aanleveren van een geldige URA- of AGB-code voor de organisatie is de verantwoordelijkheid van het XIS. Deze informatie wordt gebruikt voor logging en wettelijke naleving.

Met de optie interne organisatie-ID kan het XIS een aangepaste organisatie-ID definiëren en gebruiken. Wanneer deze identifier wordt gebruikt, moet het XIS een lijst met interne identifiers en de organisatie voor elke identifier aanleveren, zodat de viewer deze informatie kan relateren aan een AGB- of URA-code.

Zorgverlener ID’s

Geaccepteerde zorgverlener identifiers zijn: UZI, BIG, AGB en interne zorgverlener identifiers. De globale identifiers worden weergegeven in volgorde van voorkeur, en de unieke claim voor de interne zorgverlener identifiers is altijd verplicht, aangezien deze tijdens het eerste gebruik van de SSO aan een gebruiker in de gebruikersopslag van de viewer is gekoppeld en vervolgens gebruikt om de gebruiker uniek te identificeren in alle verdere SSO-aanmeldingen. Het is van essentieel belang dat de unieke identificatiegegevens consistent worden gehouden met betrekking tot de gebruikers die ze vertegenwoordigen bij alle SSO-verzoeken. Evenzo moet het e-mailadres van een gebruiker uniek zijn voor de gebruiker en niet opnieuw worden gebruikt voor verschillende gebruikersaccounts. Het gebruik van globale identificatiecodes, naast de unieke interne identificatiecode, wordt sterk aangemoedigd.

Patient-ID’s

De enige geaccepteerde patiëntidentificatie is het BSN. Dit is een verplichte claim die wordt gebruikt om patiënten uniek te identificeren.

Voorbeeld JWT en payload

Het volgende is een voorbeeld van een gecodeerde JWT die voldoet aan de specificaties

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cmwteGlzIiwianRpIjoiYzYxMWFlOWEtNmZmZi00MzQ
4LWE0YjAtZDJmOWU2ODZiOTc2IiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyNDI2MjIsImRlc3QiOiJodHRwczov
L2FjYy5oaW5xLm5sL24vYW1vIiwib3JnLWlkIjoiMTIzNDUiLCJvcmctYWdiIjoiMTIzNDUiLCJvcmctdXJhIjoiMTIz
NDUiLCJvcmctbmFtZSI6Ikdlem9uZGhlaWRzY2VudHJ1bSBEZSBLb25pbmciLCJ1c2VyLWlkIjoiTjMwNjNKRC1GWTdML
TIzRkc0MiIsInVzZXItdXppIjoiMTIzNDUiLCJ1c2VyLWJpZyI6IjEyMzQ1IiwidXNlci1hZ2IiOiIxMjM0NSIsInVzZX
ItZ2l2ZW4tbmFtZSI6IkpvaG4iLCJ1c2VyLWZhbWlseS1uYW1lIjoiRG9lIiwidXNlci1lbWFpbCI6ImpvaG5kb2VAZXh
hbXBsZXpvcmcubmwiLCJwYXRpZW50LWJzbiI6IjEyMzQ1Njc4IiwicGF0aWVudC1naXZlbi1uYW1lIjoiSmFuZSIsInBh
dGllbnQtZmFtaWx5LW5hbWUiOiJEb2UifQ.n6j7cMiVmy2Z2qbpb08wqymzEt73Akh7PGJia1FojvxVRCu2b9l9nfMIbo
wuCeMRsJ08IIVqmBG1WyJ6XiyVoiF7LsxBHIvLCsZL2DpjajU2PmeIaWGgFMnE4AKobRqeXdAulfR6rVGVKVlnSR2avww
pSRHS6zt2STDuByC8Yppi5mrFATrFfIG0g0ikSkiRpYuzB7yeBIMySQuemm7XY-qXv2ZEjtu74b99g4i5-CeQw-195Pd
kbzVCl7_ML6jLTss04c-eITh_g51ppllHnxd3U6r3y1mPfQfEiA7burFo1Lvg-jBObVd7fU5O 3G8a9wK-QcKXHoxnLw
OWvxbFow

De JWT kan worden gedecodeerd, wat resulteert in de onderstaande structuur. U kunt deze JWT online decoderen met jwt.io.

Header 
{ 
  "alg": "RS256", 
  "typ": "JWT" 
} 

Payload 
{ 
  "iss": "url-xis", 
  "jti": "c611ae9a-6fff-4348-a4b0-d2f9e686b976", 
  "iat": 1516239022, 
  "exp": 1516242622, 
  "dest": "<https://acc.hinq.nl/n/amo>", 
  "org-id": "12345",
  "org-agb": "12345", 
  "org-ura": "12345", 
  "org-name": "Gezondheidscentrum De Koning", 
  "user-id": "N3063JD-FY7L-23FG42", 
  "user-uzi": "12345", 
  "user-big": "12345", 
  "user-agb": "12345", 
  "user-given-name": "John", 
  "user-family-name": "Doe", 
  "user-email": "johndoe@examplezorg.nl", 
  "patient-bsn": "12345678", 
  "patient-given-name": "Jane", 
  "patient-family-name": "Doe" 
}

Een verzoek doen
Viewer-leveranciers bieden per XIS en per use-case specifieke SSO endpoints aan, waarnaar een JWT moet worden gepost. Als de JWT met succes is gevalideerd, retourneert de viewer een HTTP 302-omleidingsreactie, waardoor de professional naar de gewenste webpagina van de viewer wordt geleid. Als dit niet lukt, wordt een andere HTTP-code en reactie weergegeven, waarin het probleem wordt beschreven.

Acceptatie en productie endpoints

Er kunnen verschillende omgevingen voor bijv. acceptatie- en productie-omgevingen door de viewer leverancier beschikbaar worden gesteld aan XISsen voor het doen van aanvragen. Bijvoorbeeld:

Acceptatieomgeving: https://login.acc.viewer.nl/…
Productieomgeving: https://login.viewer.nl/…

Let op: de endpoint-url’s dienen in overleg tussen de viewer leverancier en de XIS leverancier te worden vastgesteld.

Aanvraag formaat

Het SSO-endpoint verwacht een HTTP POST-verzoek in de volgende indeling:

POST <PATH> HTTP/1.1 

/* ...generic HTTP headers... */ 
Content-Type: application/x-www-form-urlencoded 
/* ...generic HTTP headers... */ 

jwt=TOKEN_HERE

Het path attribute wordt geleverd door de viewer leverancier

Voorbeeld

POST <PATH> HTTP/1.1 

/* ...generic HTTP headers... */ 
Content-Type: application/x-www-form-urlencoded 
/* ...generic HTTP headers... */ 

jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cmwteGlzIiwianRpIjoiYzYxMWFlOWEtNmZmZ
i00MzQ4LWE0YjAtZDJmOWU2ODZiOTc2IiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyNDI2MjIsImRlc3QiOiJ
odHRwczovL2FjYy5oaW5xLm5sL24vYW1vIiwib3JnLWlkIjoiMTIzNDUiLCJvcmctYWdiIjoiMTIzNDUiLCJvcmctd
XJhIjoiMTIzNDUiLCJvcmctbmFtZSI6Ikdlem9uZGhlaWRzY2VudHJ1bSBEZSBLb25pbmciLCJ1c2VyLWlkIjoiTjM
wNjNKRC1GWTdMLTIzRkc0MiIsInVzZXItdXppIjoiMTIzNDUiLCJ1c2VyLWJpZyI6IjEyMzQ1IiwidXNlci1hZ2IiO
iIxMjM0NSIsInVzZXItZ2l2ZW4tbmFtZSI6IkpvaG4iLCJ1c2VyLWZhbWlseS1uYW1lIjoiRG9lIiwidXNlci1lbWF
pbCI6ImpvaG5kb2VAZXhhbXBsZXpvcmcubmwiLCJwYXRpZW50LWJzbiI6IjEyMzQ1Njc4IiwicGF0aWVudC1naXZlb
i1uYW1lIjoiSmFuZSIsInBhdGllbnQtZmFtaWx5LW5hbWUiOiJEb2UifQ.n6j7cMiVmy2Z2qbpb08wqymzEt73Akh7
PGJia1FojvxVRCu2b9l9nfMIbowuCeMRsJ08IIVqmBG1WyJ6XiyVoiF7LsxBHIvLCsZL2DpjajU2PmeIaWGgFMnE4A
KobRqeXdAulfR6rVGVKVlnSR2avwwpSRHS6zt2STDuByC8Yppi5mrFATrFfIG0g0ikSkiRpYuzB7yeBIMySQuemm7X
Y-qXv2ZEjtu74b99g4i5-CeQw-195PdkbzVCl7_ML6jLTss04c-eITh_g51ppllHnxd3U6r3y1mPfQfEiA7burFo1L
vg-jBObVd7fU5O3G8a9wK-QcKXHoxnLwOWvxbFow