Dit document is ook beschikbaar in dit niet-normatieve formaat:
Dit document valt onder de volgende licentie:
Creative Commons Attribution 4.0 International Public License
Dit document bevat een standaard voor toegangsverlening tot API's ten behoeve van de verwerking van overheidsgegevens voor de uitvoering van overheidstaken.
Onder toegangsverlening wordt verstaan het beslissen tot het geheel of gedeeltelijk toestaan van verzoeken tot gegevensverwerking.
In de context van deze standaard gebeurt toegangsverlening op basis van een reeds vastgesteld subject. Voor identificatie en authenticatie kan verwezen worden naar o.a. [FSC - Core], [OpenID NLGov] en [SAML].
Dit is een werkversie die op elk moment kan worden gewijzigd, verwijderd of vervangen door andere documenten. Het is geen door het TO goedgekeurde consultatieversie.
Het verantwoord verlenen en verkrijgen van toegang tot overheidsgegevens is cruciaal voor het effectief aanpakken van complexe maatschappelijke uitdagingen.
Deze standaard biedt aanbieders en afnemers een gestandaardiseerde en transparante aanpak voor fijnmazige toegangsverlening.
Door eenduidige normen, eisen en aanbevelingen te introduceren, maakt de standaard het eenvoudiger om:
In de context van deze standaard worden OAuth scopes, indien beschikbaar, gezien als gegeven eigenschappen van het subject. Voor het beschikbaar maken van OAuth scopes kan verwezen worden naar [NL GOV Assurance profile for OAuth].
Gegevensverwerking Het inzien, zoeken, aanpassen, opslaan of verwijderen van gegevens.
Verwerkingsverzoek Een verzoek tot verwerking van gegevens van de afnemer aan de aanbieder door middel van een API.
Toegangsbeslissing Het beslissen tot het geheel of gedeeltelijk toestaan van verwerkingsverzoeken op basis van subject, object, verwerking en context.
Autorisatieregel Een technisch gespecificeerde regel op basis waarvan de toegangsbeslissing voor een verwerkingsverzoek genomen wordt.
Betrokkenen De aanbieder, afnemers en toezichthouders die betrokken zijn bij de verwerking.
Verwerkende applicaties De systemen, zowel bij aanbieder als afnemer, die verwerkingsverzoeken daadwerkelijk indienen, uitvoeren en ontvangen.
De autorisatieregels horen, op basis van federatief model, beschikbaar gemaakt te worden voor alle betrokkenen.
Zowel actuele autorisatieregels als historische autorisatieregels moeten beschikbaar zijn.
De actuele autorisatieregels zijn de regels die gebruikt zullen worden voor een verwerkingsverzoek dat op dit moment ingediend zou worden.
De historische autorisatieregels zijn de regels die gebruikt zijn voor de verwerkingsverzoeken in het verleden. Voor elk historisch verwerkingsverzoek moeten de corresponderende autorisatieregels geïdentificeerd kunnen worden.
Het is van belang dat de autorisatieregels technisch eenduidig gedefinieerd zijn. Documentatie van geïmplementeerde regels volstaat hiervoor dus niet gezien de mogelijkheid tot verschillen tussen de implementatie en documentatie.
Voor effectieve validatie van autorisatieregels hoort dit binnen een organisatie op uniforme wijze vastgelegd te worden.
Wanneer dit niet het geval is loopt de organisatie het risico dat de diverse vormen van vastlegging niet gelijk geïnterpreteerd worden.
Het moet mogelijk zijn voor betrokkenen om verwerkingsverzoeken zelfstandig te evalueren op basis van de beschikbare autorisatieregels zonder dat zij daarvoor het verwerkingsverzoek ook echt in moeten dienen.
Autorisatieregel horen consequent aangepast te worden aan de actuele situatie. Om dit te borgen horen aanpassingen laagdrempelig mogelijk te zijn zonder lange doorlooptijden of complexe aanpassingen in applicaties te vereisen.
Elke historische toegangsbeslissing hoort beschikbaar gemaakt te kunnen worden voor de betrokkenen. Dit is vereist voor effectieve verantwoording van historisch verwerkingsverzoeken.
Dit kan op federatieve wijzen gebeuren waarbij historische toegangsbeslissingen proactief of op verzoek gedeeld kunnen worden met de relevante betrokkenen.
Deze werkwijze ondersteunt ook effectieve beveiligingsanalyse voor het detecteren van ongewenste toegang waarbij meerdere applicaties betrokken zijn.
Alle gegevens die gebruikt worden in het maken van de toegangsbeslissingen horen beschikbaar te zijn voor verantwoording. Alleen wanneer dit wettelijk niet toegestaan is of niet proportioneel gegeven de gevoeligheid van de gegevens kan hier van worden afgeweken.
Dit is vereist aangezien het veelal niet mogelijk is om te bepalen welke gegevens op een gegeven moment beschikbaar waren voor de toegangsbeslissing.
Afnemers horen bij elk verwerkingsverzoek de doelbinding voor verwerkingsverzoeken aan te geven. Hierbij kan verwezen worden naar het Register van Verwerkingsactiviteiten.
TODO:
Autorisatieregels mogen verwerkingsverzoeken inhoudelijk niet aanpassen. Alleen metadata van het verzoek mag weggelaten of uitgebreid worden.
Voor een HTTP verzoek betekent dit bijvoorbeeld dat:
Dit betekent dat vereiste gegevensminimalisatie in het verwerkingsverzoek gespecificeerd moet worden. Voor REST API's kan de Customization extensie hoort de [REST API Design Rules] hier voor gebruikt worden.
In sommige gevallen kan de toegangsbeslissing alleen genomen worden op basis van de gegevens die het verwerkingsverzoek retourneert.
Het is niet wenselijk dat tijdens de evaluatie van de toegangsbeslissing in de inhoud van het bericht gekeken moet worden. Dit vergroot gevoeligheidsproblematiek en is foutgevoelig indien de structuur wijzigt.
In dat geval hoort de deze informatie gestructureerd beschikbaar gemaakt te worden in de metadata van het antwoord.
In het geval van een HTTP verzoek mogen dus alleen status codes en headers daar voor gebruikt worden.
Aanbieders en afnemers mogen een overzicht geven van toegestane verwerkingsverzoeken.
Dit kan bijvoorbeeld gebeuren op basis van:
Niet alle verwerkingsverzoeken die mogelijk zijn, zijn ook wenselijk. Het voorstellen van verwerkingsverzoeken vergemakkelijkt het breder indienen van verwerkingsverzoeken. Daarom is het van belang dat een bewuste overweging gemaakt wordt of het voorstellen van de toegestane verzoeken gewenst is in de gegeven context.
Applicaties mogen gegevens over de aanvrager ontvangen en op basis daarvan functionaliteit aanpassen.
Het is dus bijvoorbeeld toegestaan om een in een verwerkingsverzoek voor "Mijn Zaken" de gebruikersnaam uit een authenticatie token te gebruiken om alleen zijn of haar zaken te tonen.
De verwachting is dat applicaties met het hoogste volwassenheidsniveau van toegangsverlening dit niet nodig zullen hebben.
TODO
Waar mogelijk heeft het de voorkeur om alle toegangsregels voor een toegangsbeslissing gelijktijdig te valideren. Het verzoek kan de geheel toegestaan of afgewezen worden.
Vanuit technische overwegingen is dit niet altijd haalbaar. In die gevallen mogen additionele vereisten opgelegd worden aan applicaties.
Denk hierbij bijvoorbeeld aan:
De uitvoerder van de autorisatieregel blijft verantwoordelijk voor de uitvoering van het toegangsbeleid. De organisatie als geheel is dus verantwoordelijk dat de verwerkende applicatie de vereiste ook correct implementeert.
Soms is het risico dat een vereiste niet wordt uitgevoerd zeer groot. Dan kan het eerste verzoek beter afgewezen worden. De applicatie wordt dan gevraagd om een tweede verzoek in te dienen waarin de applicatie expliciet bevestigen te kunnen voldoen aan de vereiste.
Voor het opleggen van vereisten aan betrokkenen wordt gebruikt gemaakt van [W3C Verifiable Credentials].
Denk hierbij bijvoorbeeld aan het vereisen dat de applicatie in de afgelopen periode een pen-test heeft doorlopen of dat de aanvragende organisatie ISO 27001 gecertificeerd is.
De aanbieder kan kiezen om alleen zichzelf als issuer van de Verifiable Credential te accepteren. Het wordt echter aangeraden om, waar mogelijk, een netwerk van derde partijen te realiseren die de vereisten kunnen verifiëren.
Het informatiemodel omschrijft de structuur van alle informatie die gebruikt wordt voor het maken van individuele toegangsbeslissingen.
Er is gekozen om het informatiemodel te baseren op de OpenID AuthZEN Authorization API.
Hieronder worden specifieke uitbreidingen op dit informatiemodel benoemd voor gebruik bij de uitvoering van Nederlandse overheidstaken.
De informatie m.b.t. de aanvrager moet opgenomen worden onder het veld subject met de verplichte velden type en id en het optionele veld properties.
Het is wenselijk om, waar mogelijk, het subject te definiëren op basis van gevalideerde gegevens. Gebruik dus bijvoorbeeld de gevalideerde gebruikersnaam en niet het JWT token dat de gebruikersnaam bevat en nog gevalideerd dient te worden.
In het geval van een generiek HTTP verzoek kan soms geen aanvrager bepaald worden. Gebruik in dat geval ip-address als type en het IP-adres conform RFC4001 als id.
Dus bijvoorbeeld:
{
"type": "ip-address",
"id": "127.0.0.1"
}
In het geval van een FSC verzoek wordt de Peer ID als identificatie van de aanvrager gebruikt.
Dus bijvoorbeeld:
{
"type": "fsc-peer",
"id": "1234567890"
}
De informatie m.b.t. de verwerkingsactiviteit moet opgenomen worden onder het veld action met het verplichte veld name en het optionele veld properties.
Bij voorkeur wordt action benoemd in termen van de verwerkingshandeling in het kader van AVG.
De toegestane waardes zijn: verzamelen, vastleggen, ordenen, structureren, opslaan, bijwerken of wijzigen, opvragen, raadplegen, gebruiken, doorzenden, verspreiden, beschikbaar stellen, samenbrengen, met elkaar in verband brengen, afschermen, wissen en vernietigen.
Indien een andere naam wordt gekozen kan de AVG handeling alsnog opgenomen worden in de properties van de action worden onder het veld nl.avg.verwerkingshandeling.
Dus bijvoorbeeld:
{ "nl.avg.verwerkingshandeling": "beschikbaar stellen" }
In het geval van een generiek HTTP verzoek kan soms geen verwerkingsactiviteit bepaald worden. In dat geval kan de HTTP Request Method als naam van de actie gebruikt worden.
Dus bijvoorbeeld:
{ "name": "POST" }
Indien het HTTP verzoek Content bevat, zoals bijv. een Message Body voor een PUT of POST verzoek, moet deze opgenomen worden in de optionele properties onder het veld request_content onder het veld http. De waarde moet Base64 encoded zijn.
Dus bijvoorbeeld:
{
"name": "POST",
"properties": {
"http": {
"request_content": "YnNuPTEyMzQ1Njc4Mg=="
}
}
}
Indien een verwijzing naar de verwerkingsactiviteit in een Register van Verwerkingsactiviteiten opgenomen wordt moet deze in de properties van de action opgenomen worden onder het veld dpl.core.processing_activity_id.
Dus bijvoorbeeld:
{ "dpl.core.processing_activity_id": "https://rvva.example.com/123" }
De informatie m.b.t. het object waar de verwerkingsactiviteit betrekking op heeft moet opgenomen worden onder het veld resource met de verplichte velden type en id en het optionele veld properties.
In het geval van een generiek HTTP verzoek kan deze opgenomen worden als een resource van het type uri met als id de Uniform Resource Identifier zonder query en fragment.
Ter ondersteuning van de autorisatieregels kunnen componenten van de URI ook opgenomen worden in de optionele properties. Daarvoor moet als veldnaam de ABNF rule name van het URI component gebruikt worden binnen het http veld.
Als voorbeeld kan de URI https://example.com:8443/application/resources/1?active=true dus worden opgenomen als:
{
"type": "uri",
"id": "https://example.com:8443/application/resources/1",
"properties": {
"http": {
"scheme": "https",
"host": "example.com",
"port": "8443",
"path": "/application/resources/1",
"query": "active=true"
}
}
}
HTTP Query Parameters worden regelmatig gebruikt als conventie om sleutel-waardeparen aan verzoeken mee te geven. Om fouten in het verwerken hiervan te voorkomen raden we aan om deze uniform beschikbaar te maken als JSON object in het veld parameters binnen het http veld.
&) teken.=) of het einde van het token vormen de parametersleutel.=) vormen de parameterwaarde. Indien het token geen gelijkteken bevat is de parameterwaarde een JSON null waarde.Bijvoorbeeld de query parameter:
active=true&filter=last_name%3DJanssen&filter&filter=geboortejaar%3C2000&test%26%3D=%0A%22&expand
wordt opgenomen als
{
"properties": {
"http": {
"parameters": {
"active": "true",
"filter": [
"last_name=Janssen",
null,
"geboortejaar<2000"
],
"test&=": "\n\""
"expand": null
}
}
}
}
Overige informatie m.b.t. de context van de verwerkingsactiviteit moet opgenomen worden onder het veld context.
Indien de toegangsbeslissing een HTTP verzoek betreft moeten de HTTP Headers opgenomen worden als een array van Field Lines onder het veld headers binnen het http veld.
Dus bijvoorbeeld:
{
"http": {
"request_content": "eyJkZWNpc2lvbiI6dHJ1ZX0="
}
}
Indien de HTTP versie opgenomen wordt moet deze in de context opgenomen als waarde conform RFC9110 onder het veld version binnen het http veld.
Indien een client-side X509 certificaat opgenomen wordt moet deze in de context opgenomen in het PEM formaat worden opgenomen onder het veld client_certificate binnen het http veld.
Ten behoeve van integratie met [Logboek dataverwerkingen] moeten beschikbare W3C Trace Context's opgenomen worden in het informatiemodel van de toegangsbeslissing.
Indien HTTP headers niet beschikbaar zijn, maar de trace informatie wel beschikbaar is moeten deze in de context opgenomen worden onder de velden tracestate en traceparent.
De tijd van het verzoek dient opgenomen te worden in de context onder het veld timestamp in het ISO 8601 formaat gekwalificeerd met een tijdszone. Gebruik van de UTC tijdszone wordt aanbevolen.
Naast onderdelen die als niet normatief gemarkeerd zijn, zijn ook alle diagrammen, voorbeelden, en noten in dit document niet normatief. Verder is alles in dit document normatief.