| Status | ||
|---|---|---|
|
| Status | ||||
|---|---|---|---|---|
|
| Expand | ||
|---|---|---|
| ||
|
| Info |
|---|
Toelichting |
Voorbeeld
| Code Block |
|---|
{
"sub": "profID1241",
"jti": "550e8400-e29b-41d4-a716-446655440000",
"profInfo": {
"firstname": "John",
"lastname": "de Vries",
"email": "john.devries@praktijk.nl"
},
"treatmentRelationshipId": "1532",
"patientInfo": {
"bsn": "426308505",
"firstname": "Peter",
"lastname": "de Mol",
"email", "peter@gmail.com"
},
"iat": 1516239022
} |
Opbouw tokens
SSO-token
...
Name
...
Type
...
Count
...
Description
...
sub
...
string
...
1..1
...
The unique identifier for the professional that is logging in.
...
jti
...
string
...
1..1
...
The unique identifier for this specific JWT. Should be random each time, UUID recommended
...
iat
...
number
...
1..1
...
'Issued at' timestamp. The time this JWT was created (in unix time)
...
treatmentRelationship Id
...
string
...
0..1
...
A unique identifier for the relationship between this professional and the patient (if any). For more information, see note.
...
profInfo
...
ssoTokenProfInfo
...
0..1
...
Additional information about the professional that is logging in. For more information, see note.
...
patientInfo
...
ssoTokenPatientInfo
...
0..1
...
Additional information about the patient into whose context the professional is logging in.
| Info |
|---|
treatmentRelationshipId |
| Info |
|---|
profInfo |
ssoTokenProfInfo
...
Name
...
Type
...
Count
...
Description
...
firstname
...
string
...
0..1
...
The firstname of the professional that is logging in.
...
lastname
...
string
...
0..1
...
The last name of the professional that is logging in.
...
...
string
...
0..1
...
The email of the professional that is logging in.
...
agb
...
string
...
0..1
...
The AGB code of the professional that is logging in.
| Info |
|---|
If the agb field is provided, the professional that is logging in is automatically matched to their existing Hinq account, if they have one. If the firstname, lastname and email fields are all filled in, an account is automatically created for this professional if they do not already have one. This saves steps for the professional. |
ssoTokenPatientInfo
...
Name
...
Type
...
Count
...
Description
...
bsn
...
string
...
0..1
...
The BSN of the patient in whose context the professional is logging in.
...
firstname
...
string
...
0..1
...
The firstname of the patient in whose context the professional is logging in.
...
lastname
...
string
...
0..1
...
The last name of the patient in whose context the professional is logging in.
...
...
string
...
0..1
...
The email of the patient in whose context the professional is logging in.
| Info |
|---|
If the bsn field of this datatype or treatmentRelationshipId field of the container SSO Token datatype is provided, the professional is automatically logged in to the right patient context. If the firstname, lastname and email fields are all filled in, an account is automatically created for this professional if they do not already have one. This saves steps for the professional. |
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.
| Note |
|---|
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:
| Note |
|---|
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 |
| Unieke identifier afgestemd tussen leverancier XIS en leverancier Viewer | String | 1..1 | ||||||||||||
jti |
| 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 |
| UNIX tijdstempel op het moment van genereren JWT | Number | 1..1 | ||||||||||||
dest |
| URL van de applicatie waarin wordt beoogd via SSO in te loggen. Wordt aangeleverd door leverancier Viewer | String | 1..1 | ||||||||||||
exp |
| UNIX tijdstempel voor expiratie van het token bepaald door het XIS. Maximaal 1 uur na het
| Number | 1..1 | ||||||||||||
org-id |
| Unieke identifier van de organisatie afgestemd tussen leverancier XIS en leverancier Viewer | String | 1..1 | ||||||||||||
org-ura |
| De URA identifier van de organisatie | String | 0..1 | ||||||||||||
org-agb |
| De AGB identifier van de organisatie | String | 0..1 | ||||||||||||
org-name |
| De publieke naam van de zorgorganisatie | String | 1..1 | ||||||||||||
user-id |
| Het unieke ID binnen het zorginformatiesysteem van de zorgverlener | String | 1..1 | ||||||||||||
user-uzi |
| De UZI identifier van de zorgverlener | String | 0..1 | ||||||||||||
user-big |
| De BIG identifier van de zorgverlener | String | 0..1 | ||||||||||||
user-agb |
| De AGB identifier van de zorgverlener | String | 0..1 | ||||||||||||
user-given-name |
| De voornaam(en) van de zorgverlener | String | 1..1 | ||||||||||||
user-family-name |
| De achternaam van de zorgverlener | String | 1..1 | ||||||||||||
user-email |
| 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 |
| Het BSN van de cliënt/Patiënt | String | 1..1 | ||||||||||||
patient-given-name |
| De voornaam(en) van de cliënt/patiënt | String | 1..1 | ||||||||||||
patient-family-name |
| 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
| Code Block | ||
|---|---|---|
| ||
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.
| Code Block | ||
|---|---|---|
| ||
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/…
| Note |
|---|
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:
| Code Block |
|---|
POST <PATH> HTTP/1.1
/* ...generic HTTP headers... */
Content-Type: application/x-www-form-urlencoded
/* ...generic HTTP headers... */
jwt=TOKEN_HERE |
| Note |
|---|
Het path attribute wordt geleverd door de viewer leverancier |
Voorbeeld
| Code Block |
|---|
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 |