Technische documentatie
Fieldlab Bestaanszekerheid bij Levensgebeurtenissen

APIs

Er zijn verschillende APIs beschikbaar. Deze zijn te vinden op Links en resources onder het kopje APIs.

Voorbeeldrequest

Gebruik een tool als cURL of Postman om te testen. Gebruik een BSN uit de lijst van testpersonen.

Een voorbeeld van een request via cURL is:

curl 'https://rvig-brp-backend.bzlg.apps.digilab.network/v0/persons/100000001' \
  -H 'accept: application/json'

CORS headers

De APIs sturen CORS response headers. CORS-headers (Cross-Origin Resource Sharing) zijn een indicatie voor browsers dat webapplicaties die op een ander domein, poort of protocol draaien, veilig verzoeken kunnen sturen naar de API. Zonder deze headers blokkeert de browser zulke cross-origin verzoeken om veiligheidsredenen. In een productie-omgeving zullen CORS-headers gespecificeerd zijn, maar in deze testomgeving zijn de CORS-headers zo ingesteld dat elke frontend (origin *) de APIs kan aanroepen. Dit maakt het mogelijk om andere frontends te maken dan de opgezette voorbeeldapplicaties.

Authenticatie in een productie-omgeving

In een prodcutie-omgeving kan authenticatie (controle of de aanvrager toegang heeft tot de API) worden uitgevoerd via FSC. Dit is een standaard met bijbehorende referentie-implementatie voor federatieve authenticatie tussen overheidsorganisaties.

In een prodcutie-omgeving kan autorisatie (controle wat de aanvrager precies mag opvragen) worden uitgevoerd via FTV. Dit is een standaard met bijbehorende referentie-implementatie voor autorisatie op basis van policies (PBAC).

Voorbeeldapplicaties

Verschillende voorbeeldapplicaties zijn gelinkt op Links en resources onder het kopje Voorbeeldapplicaties.

Dit zijn frontends voor fictieve organisaties. Deze frontends vragen data op bij verschillende endpoints van de bovengenoemde API's.

De frontends vereisen geen login / authenticatie, omdat deze slechts voor demo-doeleinden zijn.

De frontends zijn gemaakt met het web framework Svelte en relatief gemakkelijk uitbreidbaar of vervangbaar.

Testpersonen

De volgende testpersonen zijn beschikbaar in de fieldlab-omgeving:

• BSN 100000001: Merijn van der Meer
• BSN 999991905: Linda Strijps
• BSN 900253010: Bertje von Deutekom
• BSN 900253022: Willem Waarde
• BSN 900253034: Marcello de Goede
• BSN 900253046: Caroline van der Oever
• BSN 900253058: Suzanne Wesseling
• BSN 900265425: Widolf van der Moes
• BSN 900265437: Koos over 't Wiel
• BSN 900265449: Circe Żywiałowska
• BSN 900265450: Christine du Leclercq
• BSN 900265462: Lennert uijt de Fruitplukker
• BSN 999991772: Frouke Jansen
• BSN 100000002: Maria Rodriguez
• BSN 100000003: Omar Yilmaz
• BSN 100000004: Fatima el Hassan
• BSN 300000001: Sophie Jansen
• BSN 999993653: Jan Jansen
• BSN 999993654: Maria Pietersen
• BSN 999993656: Peter Bakker
• BSN 999993657: Emma Visser
• BSN 999993658: Thomas Mulder
• BSN 999993659: Anna Schmidt
• BSN 999993660: Lisa de Jong
• BSN 777777777: Fatima Al-Zahra
• BSN 888888888: Sarah de Boer
• BSN 999993872: Peter-Jan van der Meijden
• BSN 999993670: Jan Pietersen

Eventueel zijn meer testpersonen toe te voegen door de seed data aan te passen in de repository. (voorbeeld)

Database (UBB)

De database die gebruikt wordt in dit fieldlab is de Atomic Claim Engine (ACE) van het project Uit Betrouwbare Bron (UBB). UBB is een open source project dat is gericht is op het ontwikkelen van een betrouwbaar register/database voor overheidsdata.

De ACE-database is een temporele database, die gegevens kan opslaan met bijbehorende registratietijd en geldigheidstijd.

Voor meer informatie, zie de projectwebsite.

FSC

FSC is een standaard voor connecties tussen overheidsorganisaties. OpenFSC is een referentie-implementatie daarvoor.

OpenFSC is een open source peer-to-peer-systeem dat federatieve authenticatie over beveiligde verbindingen mogelijk maakt middels contracten in een grootschalig, dynamisch API-ecosysteem met veel organisaties.

FSC zorgt voor veilige en gecontroleerde uitwisseling van gegevens tussen verschillende overheidsorganisaties. In plaats van dat elke organisatie rechtstreeks koppelt met elke andere, fungeert FSC als een tussenlaag die berichtenverkeer coördineert, beveiligt en logt.

Het systeem bestaat uit vier hoofdonderdelen: de FSC Directory, FSC Manager, FSC Outway en FSC Inway.

Directory

• De centrale adres- en registerdienst binnen een FSC-ecosysteem.
• Fungeert als een soort “telefoonboek” of servicecatalogus waarin alle aangesloten organisaties, hun diensten en technische eindpunten (Inways/Outways) zijn vastgelegd.

Outway

De Outway zorgt ervoor dat een organisatie veilig verbinding maakt met andere organisaties. Dit betekent:

• Versleutelde communicatie via mTLS.
• Verkeer gaat via bepaalde netwerkpoorten, volgens FSC-richtlijnen.
• De verbinding wordt opgezet op basis van het juiste contract.

Inway

De Inway regelt de ontvangst van verzoeken en controleert of een inkomende aanvraag voldoet aan de gemaakte afspraken. Dit houdt in:

• Verificatie van de afzender en verbinding.
• Toegang alleen op basis van een geldig contract.
• Bescherming tegen ongewenste of foutieve aanvragen.

Manager

De Manager houdt grip op de afspraken tussen organisaties. Dit omvat:

• Beheer van digitale contracten: wie mag welke API's vragen?
• Autoriseert toegang op basis van Contracten
• Ontdekt welke API's en deelnemers beschikbaar zijn.

Voorbeeldrequest

Als OpenFSC is geïmplementeerd, moet een request naar een Outway een zogenaamde FSC grant hash in een header bevatten. Dit ziet er bijvoorbeeld als volgt uit:

curl -H 'Fsc-Grant-Hash: $1$3$WZzMrz5W5NEjNHlztcQr6fQT5kOX6YlDlDbolM8ir1Gx80axkCuoYnFE-vyOXMfUUrD0fWgGH312dSleaNmiSQ' https://outway-endpoint

waarbij $1$3$… een voorbeeld is van een FSC grant hash en https://outway-endpoint de locatie van de Outway.

Voor meer informatie, zie de standaard en de OpenFSC-documentatie.

FSC in de fieldlab-omgeving

Outways in de fieldlab-omgeving zijn beschikbaar op:

• https://rvig-open-fsc-outway.bzlg.apps.digilab.network
• https://bd-open-fsc-outway.bzlg.apps.digilab.network
• https://toeslagen-open-fsc-outway.bzlg.apps.digilab.network
• https://ro-open-fsc-outway.bzlg.apps.digilab.network
• https://uwv-open-fsc-outway.bzlg.apps.digilab.network
• https://rvz-open-fsc-outway.bzlg.apps.digilab.network
• https://svb-open-fsc-outway.bzlg.apps.digilab.network
• https://ind-open-fsc-outway.bzlg.apps.digilab.network

Bovenstaande endpoints zijn 'beveiligd' met Basic Authentication. De credentials daarvoor zijn:

• Username: digilab
• Password: bzlg

Een request naar een van deze outways kan er als volgt uitzien:

Om als ro (Fictieve Rijksoverheid) te verbinden met de RegelRecht engine van bd (Fictieve Belastingdienst):

curl https://ro-open-fsc-outway.bzlg.apps.digilab.network \
  --user 'digilab:bzlg' \
  --header 'Fsc-Grant-Hash: some-hash'

waarbij de grant hash is te vinden in dit bestand onder FSC_GRANT_HASH_BELASTINGDIENST_ENGINE.

FTV

Federatieve Toegangsverlening (FTV) is een gestandaardiseerde benadering voor het beheren van gegevensuitwisseling tussen organisaties, waarbij regels buiten applicaties worden beheerd voor schaalbaarheid en flexibiliteit.

Het systeem is traceerbaar dankzij een loggingstandaard en de geschiedenis van toegangsregels, en het is leveranciersonafhankelijk door het gebruik van open standaarden.

Federatieve toegangsverlening (FTV) is een toepassing van Externalized Authorization Management (EAM), een methode om toegangsregels buiten applicaties te beheren. Om te laten zien hoe dat werkt, is een technische voorbeeldoplossing beschikbaar: de referentie-implementatie OpenFTV.

Met behulp van FTV kan autorisatie worden geregeld in policies. Dit heet Policy-Based Access Control (PBAC).

Voor meer informatie, zie de projectwebsite.

Events

In de fieldlab-omgeving wordt gebruik gemaakt van events. Als bijvoorbeeld iemands inkomen wijzigt, wordt daar een event voor aangemaakt. Andere systemen kunnen zich daarop abonneren om op de hoogte te blijven van wijzigingen.

De event-berichten worden verstuurd als Cloud Events, een standaard voor event-berichten.

Voor het versturen en ontvangen van events wordt gebruik gemaakt van NATS, een open source messaging systeem.

Voor het duurzaam opslaan van events wordt gebruik gemaakt van JetStream, een uitbreiding op NATS voor het opslaan van berichten.

Voorbeeld van een Cloud Event in de fieldlab-omgeving

{
    "data": {
        "claimType": "LoonUitDienstbetrekkingProposed"
    },
    "id": "4c3f2fd9-92b0-429f-9674-77932478ae15",
    "source": "nl.uitbetrouwbarebron.ace",
    "specversion": "1.0",
    "type": "ClaimCreated"
}

Vanuit het oogpunt van dataminimalisatie bevat de event geen data van wat de waarde van de aanpassing is, maar slechts de id van de claim. Via de Engine API kunnen meer details over de claim worden opgevraagd.

Subscriben op een NATS queue

Een voorbeeld van hoe je kunt subscriben op een NATS subject met de nats-box Docker image:

docker run --rm natsio/nats-box nats sub ">" --server=nats://nats-endpoint:4222

waarbij de waarde van nats-endpoint gekozen kan worden uit de onderstaande tabel.

Er kan voor gekozen worden om te subscriben op specifiekere events, bijvoorbeeld "Ace.ClaimCreated.>" (waarbij > fungeert als wildcard).

In werkelijkheid zul je een NATS client library gebruiken in je applicatie in plaats van de Docker nats-box image.