Interfaceontwerp
Vertrouwde Authenticatie Dienst
Basis flow
De Vertrouwde Authenticatie Dienst (VAD) werkt samen met ToegangVerleningService (TVS) en BSNk om voor PGO's (en andere wel of niet BSN-gerechtigde applicaties) authenticatie te bieden van een gebruiker. Een basis flow wordt hieronder getoond.
Koppelvlakken
Voor verbinding met andere systemen biedt de VAD de volgende koppelvlakken:
OpenID Connect
Versleuteld BSN endpoint
OpenID Connect
Authenticatie via de VAD verloopt via OpenID Connect. Deze open standaard wordt breed ondersteund en is voorgeschreven door het Forum Standarisatie1.
OpenID Connect gebruikt het User Info endpoint om informatie over een gebruiker beschikbaar te stellen. De data die hierin zit is afhankelijk van de scope waarmee de authenticatie gestart is. Hieronder is de volledige lijst.
Eigenschap | Scope |
|---|---|
Versleuteld pseudoniem | - |
Versleuteld pseudoniem voor toestemmingen | nl.minvws.pseudoniem.toestemmingen |
Versleuteld pseudoniem voor lokalisatie | nl.minvws.pseudoniem.lokalisatie |
Versleuteld BSN endpoint
Om een versleuteld BSN te verkrijgen kan een applicatie het versleutelde BSN endpoint van de VAD gebruiken. Hiervoor is een geldig access token (verkregen via de OpenID Connect flow) nodig. Ook dient de doelpartij aangegeven te worden. Deze doelpartij moet BSN gerechtigd zijn. Als identifier wordt de URA code gebruikt. Het endpoint is een REST endpoint wat data verwacht en uitlevert in JSON-formaat.
Pseudoniemen Referentie Service
Koppelvlakken
De Pseudoniemen Referentie Service (PRS) levert een API waarmee een applicatie verschillende type identiteiten kan ophalen. Voor alle endpoints geld dat deze enkel benaderbaar zijn met een geldige access key. Deze access key is gebonden aan geregistreerde applicaties.
Pseudoniemen
Om toestemmingen en lokalisatie te ondersteunen kan er een versleuteld pseudoniem worden opgevraagd voor de toestemmingen of lokalisatie dienst. De pseudoniemen die via dit endpoint geleverd kunnen worden zijn een pseudoniem voor toestemmingen en een pseudoniem voor burger-lokalisatie.
De pseudoniemen die via dit endpoint geleverd worden zijn altijd versleuteld met het sleutelmateriaal wat voor de doel applicatie geregistreerd is.
Technische standaarden
OpenID Connect
SAML (TVS, DigiD, DigiD Machtigen, eIDAS)
BSNk PP
API specificatie VAD
vad-coordination/api/VAD.json at initial-documentation · minvws/vad-coordination (github.com)
{
"openapi": "3.1.0",
"info": {
"title": "VAD",
"version": "1.0.0",
"description": "Vertrouwde Authenticatie Dienst specificatie.",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "Ministerie van Volksgezondheid, Welzijn en Sport, afdeling iRealisatie",
"url": "https://github.com/minvws/",
"email": "helpdesk@irealisatie.nl"
}
},
"servers": [
{
"url": "https://vad.example.com/api/v1",
"description": ""
}
],
"paths": {
"/versleutelde-bsn": {
"summary": "Hiermee kunnen versleutelde BSN's voor zorgaanbieders gemaakt worden.",
"description": "Versleutelde BSN's kunnen gebruikt worden voor communicatie met een zorgaanbieder. Enkel de betreffende zorgaanbieder kan de versleuteling verwijderen.",
"post": {
"requestBody": {
"description": "A new `VersleuteldeBSNAanvraag` to be created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VersleuteldeBSNAanvraag"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VersleuteldBSNRespons"
}
}
},
"description": "Geslaagd"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Fout"
}
}
},
"description": "Wanneer de URA niet bestaat."
}
},
"operationId": "maakVersleuteldeBSNAanvraag",
"summary": "Maak een VersleuteldeBSNAanvraag",
"description": "Maak een `VersleuteldeBSNAanvraag`."
}
},
"/profiel": {
"get": {
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfielRespons"
}
}
},
"description": "Het gebruikersprofiel."
},
"404": {
"description": "Indien de sessie niet bestaat of verlopen is wordt deze response verstuurd."
}
},
"summary": "Het gebruikersprofiel.",
"description": "Het gebruikersprofiel volgens OpenID Connect met aanvullingen voor pseudoniemen: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo"
}
}
},
"components": {
"schemas": {
"Fout": {
"required": [
"code",
"bericht"
],
"properties": {
"code": {
"format": "int32",
"type": "integer"
},
"bericht": {
"type": "string"
}
}
},
"VersleuteldeBSNAanvraag": {
"title": "Root Type for VersleuteldeBSNAanvraag",
"description": "",
"type": "object",
"properties": {
"ura": {
"type": "string"
}
},
"example": {
"ura": "123"
}
},
"VersleuteldBSNRespons": {
"title": "Respons met versleuteld BSN",
"description": "Een response met een versleuteld BSN voor een specifieke zorgaanbieder.",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"doelURA": {
"type": "string"
},
"versleuteldBSN": {
"type": "string"
}
}
}
}
},
"ProfielRespons": {
"title": "Respons met profiel",
"description": "Profiel gegevens conform het UserInfo endpoint van OpenID Connect. https://openid.net/specs/openid-connect-core-1_0.html#UserInfo",
"required": [
"nl.minvws.pseudoniem",
"sub"
],
"type": "object",
"properties": {
"sub": {
"description": "Een ID wat uniek is en bij elke sessie wordt toegewezen. Gebruik het ontsleutelde pseudoniem uit nl.minvws.pseudoniem voor een stabiele gebruikers ID.",
"type": "string",
"readOnly": false
},
"name": {
"type": "string",
"example": "Jane Doe"
},
"nl.minvws.pseudoniem.lokalisatie": {
"type": "string"
},
"nl.minvws.pseudoniem.toestemmingen": {
"type": "string"
},
"nl.minvws.pseudoniem": {
"description": "Het versleutelde pseudoniem voor de dienst die de VAD sessie startte.",
"type": "string"
}
}
}
},
"securitySchemes": {
"OpenID": {
"openIdConnectUrl": "/.well-known/openid-configuration",
"type": "openIdConnect"
}
}
},
"security": [
{
"OpenID": []
}
]
}API specificatie PRS
vad-coordination/api/prs.json at initial-documentation · minvws/vad-coordination (github.com)
{
"openapi": "3.1.0",
"info": {
"title": "PRS",
"version": "1.0.0",
"description": "Pseudoniemen Register Service specificatie.",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "Ministerie van Volksgezondheid, Welzijn en Sport, afdeling iRealisatie",
"url": "https://github.com/minvws/",
"email": "helpdesk@irealisatie.nl"
}
},
"servers": [
{
"url": "https://prs.example.com/api/v1",
"description": ""
}
],
"paths": {
"/pseudoniem": {
"summary": "Hiermee kunnen versleutelde pseudoniemen voor gemaakt worden.",
"description": "Versleutelde pseudoniemen kunnen gebruikt worden voor communicatie met andere systemen over een burger zonder een BSN te delen.",
"post": {
"requestBody": {
"description": "Een pseudoniemen verzoek.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SysteemPseudoniemAanvraagBekend"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VersleuteldPseudoniemRespons"
}
}
},
"description": "Geslaagd"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Fout"
}
}
},
"description": "Wanneer de aanvraag niet geldig is (bijvoorbeeld een verkeerd systeem)."
}
},
"operationId": "maakPseudoniemAanvraag",
"summary": "Maak een PseudoniemAanvraag",
"description": "Maak een `PseudoniemAanvraag`."
}
}
},
"components": {
"schemas": {
"Fout": {
"required": [
"code",
"bericht"
],
"properties": {
"code": {
"format": "int32",
"type": "integer"
},
"bericht": {
"type": "string"
}
}
},
"SysteemPseudoniemAanvraagBekend": {
"title": "Pseudoniem aanvraag via een systeem ID",
"description": "",
"type": "object",
"properties": {
"systeem": {
"enum": [
"lokalisatie",
"toestemmingen"
],
"example": "lokalisatie"
}
},
"required": [
"systeem"
]
},
"VersleuteldPseudoniemRespons": {
"title": "Respons met versleuteld pseudoniem",
"description": "Een response met een versleuteld pseudoniem voor een specifiek systeem.",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"versleuteldPseudoniem": {
"type": "string"
}
}
}
}
}
},
"securitySchemes": {
"mTLS": {
"type": "mutualTLS"
}
}
},
"security": [
{
"mTLS": []
}
]
}Toestemmingen en Lokalisatie
Figuur 1 toont de actoren die betrokken kunnen zijn bij de open - & gesloten autorisatievraag. De open vraag is niet benodigd indien een raadplegend systeem een gerichte vraag kan stellen aan een dossier houdend systeem.
(optioneel) Raadplegend systeem A bevraagt Mitz middels de open autorisatievraag om de locaties van andere systemen die informatie hebben over een geïdentificeerde patiënt, waarbij deze patiënt ook toestemming heeft vastgelegd binnen Mitz.
Mitz beantwoordt en geeft de locaties terug van systemen die voldoen aan de gestelde vraag, in dit geval het systeem van dossier houdende zorgaanbieder B. Systeem A weet nu dat systeem B informatie heeft over de geïdentificeerde patiënt en dat systeem B ook toestemming heeft van de patiënt om een gegevenscategorie aan informatie uit te wisselen met een bepaalde categorie van zorgaanbieders. Er kunnen verschillende transacties plaatsvinden tussen systeem A en B. Bijvoorbeeld dat een systeem eerst
een documentlijst opvraagt bij systeem B.Systeem B geeft de metadata van documenten terug aan Systeem A. Voordat Systeem B dit doet wordt er een gesloten autorisatievraag gesteld door systeem B. Deze vraag bevat de benodigde identiteitsgegevens van de zorgverlener (Systeem A) en het type zorgaanbieder van Systeem A.
Als antwoord op de gesloten autorisatievraag ontvangt Systeem B of er gegevens beschikbaar gesteld moeten worden aan systeem A. Systeem B is verantwoordelijk om deze informatie te filteren en enkel datgeen waar de patiënt toestemming voor heeft gegeven beschikbaar te stellen aan Systeem A. Indien het raadplegende systeem, door een ander mechanisme, weet welke bronsystemen gegevens bevatten over de geïdentificeerde patiënt, dan zal deze enkel de gesloten autorisatievraag stellen.
Met betrekking tot Mitz kunnen relevante gegevens worden overgenomen uit Bijlage | Architectuurdocumenten - Mitz Afsprakenstelsel - Confluence (atlassian.net) implementatie handleiding open en gesloten vraag.