JSON Web Token
Versie 08-09-2022 Status: In ontwikkeling
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 (https://en.wikipedia.org/wiki/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 |
|---|---|---|---|---|
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: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) | 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/…
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
Voorbeeld