Standaard voor Federatieve Toegangsverlening

Logius Standaard
Werkversie

Laatst gepubliceerde versie:
https://gitdocumentatie.logius.nl/publicatie/dk/ftv
Redacteur:
Auteur:
Project Federatieve Toegangsverlening (MinBZK)

Dit document is ook beschikbaar in dit niet-normatieve formaat:


Samenvatting

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.

Noot: Relatie tot identificatie en authenticatie

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].

Status van dit document

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.

1. Introductie

1.1 Doel

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:

Noot: Relatie tot autorisatie op basis van OAuth

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].

2. Architectuur

Deze sectie beschrijft de algemene architectuur voor het verlenen van toegang bij toepassing van deze standaard.

2.1 Definities

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.

Toegangsevaluatie Het beslissen tot het geheel of gedeeltelijk toestaan van verwerkingsverzoeken op basis van subject, object, verwerking en context.

Toegangsbeslissing De beslissing met betrekking tot het geheel of gedeeltelijk toestaan van een verwerkingsverzoek.

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.

Aanvrager De systemen bij de afnemer die verwerkingsverzoeken daadwerkelijk indienen.

Verwerker De systemen bij de aanbieder die verwerkingsverzoeken daadwerkelijk ontvangen en uitvoeren.

2.2 Context

Deze standaard formaliseert het patroon van Externalized Access Management. Dit patroon staat ook wel bekend als Policy Based Access Control (PBAC), Relation Based Access Control (ReBAC) of Attribute Based Access Control (ABAC.)

In dit patroon wordt een verwerkingsverzoeken bij ontvangst door een Policy Enforcement Point vastgelegd in een gezamenlijk overeengekomen informatiemodel. Deze informatie wordt aangeboden aan een Policy Decision Point die een beslissing neemt.

Het Policy Decision Point neemt de beslissing op basis van

Informatiemodel
verwerkingsverzoek
Beslissing
Autorisatieregels
Additionele informatie
Policy Enforcement Point
Policy Decision Point
Policy Administration Point
Policy Information Point
Figuur 1 Authorisatie Architectuur

2.3 Componenten

De standaard architectuur voor toegangsverlening kent de volgende conceptuele componenten. Deze componenten kunnen als losstaande applicaties worden neer gezet maar ook in verschillende samenstellingen gecombineerd worden.

2.3.1 Policy Enforcement Point (PEP)

Een Policy Enforcement Point (PEP) ontvangt verzoeken tot gegevensverwerking en is in staat deze uit te voeren of af te wijzen.

Een Policy Enforcement Point is verantwoordelijk voor het:

  • samenvatten van het verwerkingsverzoeken in een afgesproken informatiemodel
  • aanbieden van het informatiemodel aan een Policy Decision Point
  • opvolgen van de instructies in de door de Policy Decision Point geretourneerde toegangsbeslissing

Policy Enforcement Points bestaan over het algemeen uit gateways die 'voor' de applicatie staan of uit componenten binnen de applicatie het Policy Decision Point aanroepen.

2.3.2 Policy Decision Point (PDP)

Een Policy Decision Point (PDP) beslist op basis van beschikbare informatie of een verwerkingsverzoek toegestaan of afgewezen dient te worden.

Een Policy Decision Point is verantwoordelijk voor het:

  • verrijken van het informatiemodel met behulp van informatie uit het Policy Information Point
  • beschikbaar hebben van de autorisatieregels
  • evalueren van verwerkingsverzoeken op basis van het informatiemodel en de actuele autorisatieregels

Een Policy Decision Point is veelal een externe applicatie of een sidecar/container die naast de applicatie draait. Het kan echter ook een component binnen de applicatie zijn. In dat geval dient wel extra aandacht te worden besteed aan het centraal beschikbaar maken van logs voor verantwoording.

2.3.3 Policy Administration Point (PAP)

Een Policy Administration Point maakt op gecontroleerde en herleidbare wijze beleidsregels beschikbaar aan één of meerdere Policy Decision Points.

Een Policy Administration Point is verantwoordelijk voor het:

  • beschikbaar maken van actuele beleidsregels aan Policy Decision Points
  • archiveren van historische beleidsregels
  • gecontroleerd uitrollen van nieuwe en aangepaste beleidsregels

Er zijn meerdere commerciële Policy Administration Points beschikbaar. Aangezien een Policy Administration Point vooral geversioneerde deployments nodig heeft kan een Git-repository ook als PAP fungeren.

2.3.4 Policy Information Point (PIP)

Een Policy Information Point (PIP) kan het door de Policy Enforcement Point samengestelde informatiemodel verrijken met additionele informatie indien nodig.

Een Policy Information Point is verantwoordelijk voor het:

  • uitbreiden van het informatiemodel met (semi-)statisch informatie
  • uitbreiden van het informatiemodel met dynamische informatie
  • herleidbaar maken welke informatie gebruikt is voor historische toegangsbeslissingen

In de praktijk worden Policy Information Points veelal in de PDP geïntegreerd. Let hierbij echter wel op dat de verwantwoording van gebruikte informatie gewaarborgd blijft.

2.4 Flows

2.4.1 Effectueren van toegangsbeslissingen

AanvragerPEPPDPVerwerkerVerwerkingsverzoekInformatiemodel verwerkingsverzoekBeslissingVerwerkingsverzoekAntwoordAntwoordAfwijzingalt[Indien toegestaan][Indien afgewezen]AanvragerPEPPDPVerwerker
Figuur 2 Effectueren van toegangsbeslissingen

Een door de gebruiker ingediend verwerkingsverzoek wordt ontvangen door een Policy Enforcement Point. Deze vat het verwerkingsverzoek samen in Informatiemodel en levert dit aan het Policy Decision Point.

Het Policy Decision Point evalueert het verzoek en retourneert de resulterende toegangsbeslissing aan de Policy Enforcement Point. Het Policy Enforcement Point zet het dan door naar de verwerkende applicatie of wijst het af.

2.4.2 Evalueren van toegangsbeslissingen

PEPPDPPIPPAPBeleidsregelsSemi-statische informatieInformatiemodel verwerkingsverzoekDynamische informatieBeslissingPEPPDPPIPPAP
Figuur 3 Evalueren van toegangsbeslissingen
Om toegangsbeslissingen snel uit te kunnen voeren maakt het Policy Administration Point autorisatieregels pro-actief beschikbaar aan het Policy Decision Point. Waar mogelijk maakt het Policy Informatie Point ondersteunende informatie ook pro-actief beschikbaar aan het Policy Decision Point.

Na het ontvangen van het informatiemodel van een verwerkingsverzoek haalt het Policy Decision Point met behulp van het Policy Information Point dynamische informatie op indien nodig. Daarna evalueert het policy decision point het verwerkingsverzoek op basis van het samengestelde informatiemodel en de autorisatieregels. De resulterende toegangsbeslissing, inclusief verantwoordingsidentifiers, worden aan het Policy Enforcement Point aangeleverd.

3. Functionele Specificatie

3.1 Beheer van autorisatieregels

3.1.1 Autorisatieregels horen beschikbaar te zijn voor alle betrokkenen

De autorisatieregels horen, op basis van federatief model, beschikbaar gemaakt te worden voor alle betrokkenen.

3.1.2 Actuele en historische autorisatieregels moeten beschikbaar zijn

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.

Noot: Documentatie volstaat niet

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.

3.1.3 Autorisatieregels horen uniform vastgelegd te worden

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.

3.1.4 Betrokkenen moeten autorisatieregels zelfstandig kunnen evalueren

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.

3.1.5 Autorisatieregels horen laagdrempelig aanpasbaar te zijn

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.

3.2 Vastlegging en verantwoording van toegangsbeslissingen

3.2.1 Historische toegangsbeslissingen horen beschikbaar te zijn voor betrokkenen

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.

Noot: Preventie en detectie

Deze werkwijze ondersteunt ook effectieve beveiligingsanalyse voor het detecteren van ongewenste toegang waarbij meerdere applicaties betrokken zijn.

3.2.2 Toegangsbeslissingen horen verantwoord te kunnen worden

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.

3.2.3 Afnemers horen de doelbinding voor verwerkingsverzoeken te specificeren

Afnemers horen bij elk verwerkingsverzoek de doelbinding voor verwerkingsverzoeken aan te geven. Hierbij kan verwezen worden naar het Register van Verwerkingsactiviteiten.

TODO:

  • Stem af met o.a. Logboek Dataverwerkingen of dit inderdaad in Register van Verwerkingsactiviteiten opgenomen is?

3.3 Aanpassen van verwerkingsverzoeken

3.3.1 Verwerkingsverzoeken mogen niet inhoudelijk aangepast worden

Autorisatieregels mogen verwerkingsverzoeken inhoudelijk niet aanpassen. Alleen metadata van het verzoek mag weggelaten of uitgebreid worden.

Voor een HTTP verzoek betekent dit bijvoorbeeld dat:

  • een header toegevoegd mag worden; bijvoorbeeld om additionele vereisten (obligations) mee te gegeven vanuit de autorisatieregels
  • ;
  • een header weggelaten mag worden; bijvoorbeeld indien een authenticatie token gevoelige informatie bevat die niet vereist is voor onderliggende systemen
  • een header uitgebreid mag worden; bijvoorbeeld door het toevoegen van het huidige verwerkende systeem aan een trace van Logboek Dataverwerkingen of door de PEP-host toe te voegen aan de `X-Forwarded-For' header.
  • hostname en applicatie path aangepast mag worden; mits dit het gedrag van de onderliggende systemen niet beïnvloedt
Noot: Gegevensminimalisatie in verzoek

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.

3.3.2 Autorisatieregels horen geen gebruik te maken van de inhoud van een antwoord

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.

3.3.3 Toegestane verwerkingsverzoeken mogen voorgesteld worden

Aanbieders en afnemers mogen een overzicht geven van toegestane verwerkingsverzoeken.

Dit kan bijvoorbeeld gebeuren op basis van:

  • een standaard verzoek; bijvoorbeeld een voorgesteld "Mijn Zaken" verwerkingsverzoek wat alle zaken toont die toegewezen zijn aan de huidige gebruiker en niet langer dan 30 dagen geleden gesloten zijn.
  • een afgewezen verzoek; bijvoorbeeld als te veel informatie gevraagd wordt een aangepast verzoek voorstellen dat alleen _toegestane_ velden opvraagt.
  • een bepaalde context; bijvoorbeeld alle mogelijke toegestane verzoeken voor een gegeven gebruiker
Noot: Mogelijkheid en wenselijkheid

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.

3.3.4 Applicaties mogen functionaliteit aanpassen op basis van de aanvrager

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

  • Is dit echt wenselijk vanuit principe? Het is vanuit praktisch oogpunt niet te voorkomen; maar dat kan ook als "should not" opgenomen worden in de standaard.

3.4 Additionele keten-vereisten

3.4.1 Autorisatieregels mogen vereisten opleggen aan verwerkende applicaties

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:

  • een /mijn-zaken endpoint dat vanuit de autorisatieregels beperkt wordt tot de zaken van de vragende gebruiker die niet langer dan 30 dagen geleden gesloten zijn
  • het niet cachen of opslaan van gegevens
  • het sturen van een notificatie
.
Noot: Behoud van verantwoordelijkheid

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.

Noot: Vereisen van bevestiging

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.

3.4.2 Eisen aan betrokkenen horen middels verifieerbare verklaringen opgelegd te worden

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.

Noot: Toestaan van meerdere issuers

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.

4. Informatiemodel toegangsbeslissing

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.

4.1 Subject (Aanvrager)

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.

4.1.1 HTTP verzoek

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"
}

4.1.2 FSC verzoek

In het geval van een FSC verzoek wordt de Peer ID als identificatie van de aanvrager gebruikt.

Dus bijvoorbeeld:

{
    "type": "fsc-peer",
    "id": "1234567890"
}

4.2 Action (Verwerkingsactiviteit)

De informatie m.b.t. de verwerkingsactiviteit moet opgenomen worden onder het veld action met het verplichte veld name en het optionele veld properties.

4.2.1 AVG verwerkingshandelingen

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" }

4.2.2 HTTP Method

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" }

4.2.3 HTTP Content

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 body. De waarde moet Base64 encoded zijn.

Dus bijvoorbeeld:

{ 
    "name": "POST",
    "properties": {
        "body": "YnNuPTEyMzQ1Njc4Mg=="
    }
}

4.2.4 Verwijzing naar Register van Verwerkingsactiviteiten

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" }

4.3 Resource (Object)

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.

4.3.1 HTTP Uniform Resource Identifier

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"
        }
    }
}

4.3.2 HTTP Query Parameters

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 query_params.

  • Splits de HTTP Query in tokens op basis van het ampersand (&) teken.
  • Alle tekens voor het gelijkteken (=) of het einde van het token vormen de parametersleutel.
  • Alle tekens na het gelijkteken (=) vormen de parameterwaarde. Indien het token geen gelijkteken bevat is de parameterwaarde een JSON null waarde.
  • Converteer parametersleutels en -waardes van [percent encoding](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) naar [JSON String](https://datatracker.ietf.org/doc/html/rfc8259#section-7) representatie.
  • Neem elke parametersleutel en -waarde op als veld en waarde in een JSON Object.
  • Indien parametersleutels meerdere keren voorkomen worden de waarden opgenomen in een JSON Array van waardes in de volgorde van voorkomen.

Bijvoorbeeld de query parameter:

active=true&filter=last_name%3DJanssen&filter&filter=geboortejaar%3C2000&test+%26%3D=%0A+%22&empty=&=value&tag

wordt opgenomen als


{
    "properties": {
        "query_params": {
            "active": "true",
            "filter": [
                "last_name=Janssen",
                null,
                "geboortejaar<2000"
            ],
            "test &=": "\n \"",
            "empty": "",
            "": "value",
            "tag": null
        }
    }
}

4.4 Context

Overige informatie m.b.t. de context van de verwerkingsactiviteit moet opgenomen worden onder het veld context.

4.4.1 Tijdstip

Het tijdstip van het verzoek moet worden opgenomen in de context onder het veld timestamp in het ISO 8601 formaat gekwalificeerd met een tijdszone. Gebruik van de UTC tijdszone wordt aanbevolen.

Noot: Gebruik als tijdstip voor formele historisering

Het hier opgenomen tijdstip dient gebruikt te worden als tijdstip voor formele historisering bij het ophalen van ondersteunende gegevens. Op die wijze wordt het risico van inconsistenties tussen verschillende gegevensbronnen geminimaliseerd.

Dit dient waarde moet gebruikt worden voor het herleidbaar opvragen van ondersteunende gegevens doormiddel van formele

4.4.2 HTTP Headers

Indien de toegangsbeslissing een HTTP verzoek betreft moeten de HTTP Headers opgenomen worden als een array van Field Lines onder het veld headers. Let op dat indien headers meerdere keren voorkomen dienen deze gecombineerd te worden conform het omschreven algoritme voor combined Field Lines.

Dus deze headers

Content-Type: application/json
tracestate: rojo=00f067aa0ba902b7
tracestate: congo=t61rcWkgMzE

worden:

{ 
    "headers": {
        "Content-Type": "application/json",
        "tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE"
    }
}

4.4.3 HTTP Version

Indien de HTTP versie opgenomen wordt moet deze in de context opgenomen als waarde conform RFC9110 onder het veld http_version.

4.4.4 HTTP Client Certificate

Indien een client-side X509 certificaat opgenomen wordt moet deze in de context opgenomen in het PEM formaat worden opgenomen onder het veld x509_client_certificate.

4.4.5 W3C Trace Context

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.

4.4.6 Ondersteunde types van resterende autorisatieregels

Een toegangsbeslissing kan resterende autorisatieregels bevatten. Denk hierbij bijvoorbeeld aan filters om toe te passen op onderliggende datasets.

De ondersteunde types van resterende autorisatieregels MOGEN in de context worden opgenomen als een array van string waardes onder het veld residual-policy-accept.

Dus bijvoorbeeld:

{
    "residual-policy-accept": [
        "application/x-fhir-query", 
        "application/vnd.odrl+turtle" 
    ]
}

5. Toegangsevaluatie API

De Toegangsevaluatie API definieert het berichtenuitwisselingspatroon tussen een client (PEP) en een autorisatieservice (PDP) voor het uitvoeren van een enkele toegangsevaluatie. De toegangsevaluatie reseltuurt in een toegangsbeslissing.

5.1 Het Toegangsevaluatie API verzoek

Het Toegangsevaluatie verzoek is een 4-tuple bestaande uit de vier eerder gedefinieerde entiteiten:

subject: : VERPLICHT. Het subject (of aanvrager) van het type Subject

action: : VERPLICHT. De actie (of verwerkingsactiviteit) van het type Action.

resource: : VERPLICHT. De resource van het type Resource.

context: : OPTIONEEL. De context (of omgeving) van het type Context.

5.1.1 Voorbeeld (niet-normatief)

{
  "subject": {
    "type": "user",
    "id": "alice@acmecorp.com"
  },
  "resource": {
    "type": "account",
    "id": "123"
  },
  "action": {
    "name": "can_read",
    "properties": {
      "method": "GET"
    }
  },
  "context": {
    "time": "1985-10-26T01:22-07:00"
  }
}

5.2 Toegangsevaluatie API antwoord

De eenvoudigste vorm van een antwoord is simpelweg een boolean die een toegangsbeslissing vertegenwoordigt, aangegeven door een "decision" veld.

decision: VERPLICHT. Een boolean waarde die specificeert of de toegangsbeslissing is om de operatie toe te staan of te weigeren.

In deze specificatie zijn er, aangenomen dat de evaluatie succesvol was, slechts 2 mogelijke antwoorden:

Het antwoord object MOET het decision veld met een boolean waarde bevatten.

5.2.1 Toegangsbeslissing

Het volgende is een niet-normatief voorbeeld van een eenvoudige beslissing:

{
  "decision": true
}

5.2.2 Aanvullende Context in een antwoord

Naast een "decision" kan een antwoord een "context" veld bevatten dat elk JSON object kan zijn. Deze context kan aanvullende informatie bevatten die door de PEP gebruikt kan worden als onderdeel van het besluitvormingsproces. Voorbeelden zijn:

  • XACML's notie van "advies" en "verplichtingen"
  • Hints voor het weergeven van UI-status
  • Instructies voor step-up authenticatie

5.2.3 Step-up indicaties

In sommige gevallen wordt een verwerkingsverzoek afgewezen met een reden die de afnemer zelf kan addresseren. Hierbij kan je bijvoorbeeld denken aan het toevoegen van 2-factor authentication; maar ook aan het invullen van vereiste velden of aanbieden van vereiste 'claims'.

Indien de vereiste actie technisch gedefinieerd kan worden MAG deze opgenomen worden in de "context" van de beslissing als een step-up indicatie. De PDP kan zelf naar wens step-up indicaties in de context opnemen. Bij voorkeur worden deze afgestemd met de PEP zodat zij ook geautomatiseerd de step-up actie kunnen voltooien.

Binnen de context van de Nederlandse overheid zijn de onderstaande standaard step-up acties gedefinieerd.

5.2.3.1 Vereiste authenticatie klasse

Indien de huidige Authentication Context Class Reference (ACR) niet volstaat MAG een lijst van toegestane waardes in het veld "allowed_acr_values" opgenomen worden. Zie bijvoorbeeld:

{
  "allowed_acr_values": ["eidas-loa-substantial","eidas-loa-high"]
}
5.2.3.2 Connectiviteits vereisten

Indien de huidige verbinding niet volstaat MAG een lijst van toegestane verbindingsidentifiers in het veld "allowed_connectivity" opgenomen worden. Bijvoorbeeld:

{
  "allowed_connectivity": ["nl.pkioverheid", "nl.fsc", "nl.diginetwerk"]
}
5.2.3.3 Ondersteuning voor resterende autorisatieregels

Indien sommige gevallen kan een request alleen toegestaan worden indien het Policy Enforcement Point bepaalde resterende autorisatieregels uit kan voeren. Denk hierbij bijvoorbeeld aan filters op de dataset.

De soorten autorisatieregels die de PEP moet kunnen ondersteunen MOETEN worden opgenomen in de het veld "allowed_residual_policy_types" als een array van policy types.

{
  "allowed_residual_policy_types": [
    "application/vnd.rego",
    "application/x-fhir-query",
    "application/scim.filter"
  ]
}

Indien een combinatie van meerdere soorten autorisatieregels ondersteund moeten worden MAG dit worden opgenomen als een array van policy types. Indien dus rego volstaat maar zowel FHIR én SCIM vereist zijn kan dit als volgt opgegeven worden:

{
  "allowed_residual_policy_types": [
    "application/vnd.rego",
    [
      "application/x-fhir-query",
      "application/scim.filter"
    ]
  ]
}

5.2.4 Verantwoordingsidentifiers

In veel gevallen is het gewenst of vereist dat historische toegangsbeslissingen verklaard kunnen worden.

Indien additionele informatie vereist is om toegangsbeslissingen te verklaren kunnen verwijzingen naar deze informatie opgenomen worden in het veld "audit_identifiers". Denk hierbij bijvoorbeeld aan timestamps, versienummers en hashes.

Het is de verwachting dat deze identifiers opgenomen zullen worden in transactie- en auditlogs. Daarom is het van belang om de grootte en gevoeligheid van deze identifiers zo beperkt mogelijk te houden.

5.2.4.1 Versie van toegangsbeleid

De gebruikte versie van het toegangsbeleid moet opgenomen worden onder het veld "policy_version" binnen het veld "audit_identifiers".

Dit is een vrij JSON element en kan diverse vormen hebben. Bijvoorbeeld het onderstaande object indien semantische versionering wordt gebruikt:

{
  "audit_identifiers": {
    "policy_version": "1.2.16"
  }
}

Of het onderstaande object indien meerdere Git policy repositories gebruikt worden:

{
  "audit_identifiers": {
    "policy_version": { 
      "shared-policies": "a2b59b691d25c77dda6a5229afab2f845f898071",
      "policy-burgerzaken": "55238d4a56261eab8fa54e72cef9f6ef97e7c88b"
    }
  }
}
5.2.4.2 HTTP Requests

Indien ondersteunende informatie wordt opgehaald op basis van HTTP Requests moeten deze een W3C Trace Context starten of doorgeven conform [Logboek dataverwerkingen].

Indien mogelijk wordt de informatie opgehaald op basis van formele historisering op het tijdstip zoals gespecificeerd in de context sectie van het informatiemodel.

Indien formele historisering niet beschikbaar is wordt aangeraden om door middel van een Web Archive (WARC)een archief bij te houden van deze requests. Dit kan mogelijk doormiddel van het gebruik van een WARC proxy. Let hierbij echter wel op dat de bewaartermijnen van de gegevens in deze archieven gewaarborgd wordt.

De W3C Trace Context identifiers om gearchiveerde requests te kunnen identificeren kunnen worden opgenomen als JSON object onder het veld "requests" binnen het veld "audit_identifiers". Dit gebruikte veldnamen dienen de aard van het request te omschrijven.

Zie bijvoorbeeld:

{
  "audit_identifiers": {
    "requests": { 
      "anomaly-detection": "00-480e22a2781fe54d992d878662248d94-b4b37b64bb3f6141-00"
    }
  }
}

5.2.5 Redenen

Redenen MOGEN worden verstrekt door de PDP.

5.2.5.1 Reden Veld

Een Reden Veld is een JSON object dat sleutels en waarden heeft van het type string. De volgende zijn niet-normatieve voorbeelden van Reden Veld objecten:

{
  "en": "location restriction violation"
}
5.2.5.2 Reden Object

Een Reden Object specificeert een bepaalde reden. Het is een JSON object dat de volgende velden heeft:

id: : VERPLICHT. Een string waarde die de reden specificeert binnen het bereik van een bepaalde antwoord.

reason_admin: : OPTIONEEL. De reden, die NIET met de gebruiker gedeeld MAG worden, maar nuttig is voor administratieve doeleinden die aangeeft waarom de toegang werd geweigerd. De waarde van dit veld is een Reden Veld object.

reason_user: : OPTIONEEL. De reden, die met de gebruiker gedeeld MAG worden die aangeeft waarom de toegang werd geweigerd. De waarde van dit veld is een Reden Veld object.

Het volgende is een niet-normatief voorbeeld van een Reden Object:

{
  "id": "0",
  "reason_admin": {
    "en": "Request failed policy C076E82F"
  },
  "reason_user": {
    "en-403": "Insufficient privileges. Contact your administrator",
    "es-403": "Privilegios insuficientes. Póngase en contacto con su administrador"
  }
}

5.2.6 Voorbeeldantwoord met aanvullende context (niet-normatief)

{
  "decision": true,
  "context": {
    "id": "0",
    "reason_admin": {
      "en": "Request failed policy C076E82F - eIDAS LoA"
    },
    "reason_user": {
      "en": "eIDAS level 'substantial' or higher is required.",
      "nl": "eIDAS niveau 'substantieel' of hoger is vereist."
    },
    "allowed_acr_values": ["eidas-loa-substantial","eidas-loa-high"]
  }
}

6. Conformiteit

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.

De trefwoorden MAG, MOET, MOETEN, MOGEN en OPTIONEEL in dit document moeten worden geïnterpreteerd als in BCP 14 [RFC2119] [RFC8174] als, en alleen als deze in hoofdletters zijn weergegeven, zoals hier getoond.

7. Lijst met figuren

A. Index

A.1 Begrippen gedefinieerd door deze specificatie

A.2 Begrippen gedefinieerd door verwijzing

B. Referenties

B.1 Normatieve referenties

[Logboek dataverwerkingen]
Logboek dataverwerkingen. Eelco Hotting; Vedran Bilanovic. n.t.b.. URL: https://logius-standaarden.github.io/logboek-dataverwerkingen/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[W3C Verifiable Credentials]
Verifiable Credentials Data Model v1.1. Manu Sporny; Dave Longley; David Chadwick. 3 maart 2022. URL: https://www.w3.org/TR/vc-data-model/

B.2 Informatieve referenties

[FSC - Core]
FSC - Core. Eelco Hotting; Ronald Koster; Henk van Maanen; Niels Dequeker; Edward van Gelderen; Pim Gaemers. 8 december 2023. URL: https://commonground.gitlab.io/standards/fsc/core/draft-fsc-core-00.html
[NL GOV Assurance profile for OAuth]
NL GOV Assurance profile for OAuth 2.0. Frank Terpstra; Jan van Gelder. 9 juli 2020. URL: https://gitdocumentatie.logius.nl/publicatie/api/oauth/
[OpenID NLGov]
OpenID NLGov 1.0.1. Remco Schaar; Frank van Es; Joris Joosten; Jan Geert Koops. 18 september 2023. URL: https://gitdocumentatie.logius.nl/publicatie/api/oidc/
[REST API Design Rules]
NLGov REST API Design Rules 2.0.0. Jasper Roes; Joost Farla. Maart 2024. URL: https://gitdocumentatie.logius.nl/publicatie/api/adr/
[SAML]
Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0. Scott Cantor; John Kemp; Rob Philpott; Eve Maler. 15 maart 2005. URL: https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
Logius Standaard - Werkversie