Situering
Deze dienstverlening kadert binnen het Solid-domein van MAGDA Platform, en meerbepaald binnen het MAGDA Solid Attestation Service aanbod die het voor afnemers en bronnen eenvoudig maakt om authentieke data te ontsluiten via de Solid datakluis in de vorm van een Verifiable Credential.
De Holder Service maakt het mogelijk voor een Holder applicatie, zoals Mijn Burgerprofiel, om authentieke data ontsloten via een MAGDA brondienst in geattesteerde vorm op te vragen als een Verifiable Credential die voldoet aan de vereisten van het Solid ecosysteem op vlak van uitgever, handtekening, geldigheidsperiode en eventuele intrekking. Hierbij hoeft de Holder applicatie slechts één API call uit te voeren naar de Holder Service om authentieke data op te vragen, om te zetten in een OSLO-compliant datamodel en te ondertekenen als Verifiable Credential die opgeslagen kan worden in bijvoorbeeld de Solid datakluis van de burger.
Verwante diensten
Gebruiksvoorwaarden
Om gebruikt te kunnen maken van deze dienst dient men een aansluitingsprocedure te doorlopen op de MAGDA Solid dienstverlening, in kader van een integratie met het Solid-ecosysteem van Vlaams Datanutsbedrijf.
Functionaliteiten
Deze API maakt het mogelijk voor een Holder applicatie, zoals Mijn Burgerprofiel, om authentieke data ontsloten via een MAGDA brondienst op te vragen als een Verifiable Credential die voldoet aan de vereisten van het Solid ecosysteem op vlak van uitgever, handtekening, geldigheidsperiode en eventuele intrekking.
Op dit moment worden onderstaande gegevenstypes ontsloten via de Holder API:
Vraag
POST /credentials/derive
In de request naar dit endpoint geeft de afnemer een Query mee, waarin minstens het type aanwezig is van het authentieke gegeven waarvoor men een attestatie wil ophalen.
Antwoord
POST /credentials/derive
De respons bevat een Verifiable Presentation, die alle Verifiable Credentials bevat dewelke voldoen aan de Query uit de request.
Werking
Aandachtspunten
Deze API maakt gebruik van ACM OAuth-namens-een-gebruiker authenticatie, om zowel de client als de aangemelde burger waarvoor het attest wordt opgehaald te authenticeren.
In de OAuth-namens-een-gebruiker authenticatie moeten volgende audiences gebruikt worden om de Holder API aan te spreken:
De scope dv_magda_attestations_holder is vereist voor het aanspreken van de Holder API.
Responsetijden & Beschikbaarheid
Deze dienst heeft volgende gemiddelde performantie in performantietesten behaald:
Gemiddelde respons tijd | 1 sec |
90 percentiel | 2 sec |
95 percentiel | 3 sec |
Max error rate | < 1% |
Merk op dat rate limiting toegepast wordt op deze dienstverlening, met een maximum van 10 requests/seconde.
Logging
De opvragingen die gebeuren via deze webservice dienen te worden bewaard zoals beschreven op de pagina "MAGDA logging". Dit houdt in dat een afnemer die de Verifier Service aanroept minstens volgende gegevens moet bijhouden in haar audit log:
Gegeven | Omschrijving |
|---|
Referentie | Unieke identificatie van de request, die met MAGDA platform werd gedeeld via ten minste één van volgende HTTP request-headers: X-Request-ID
X-Correlation-ID
X-Tracing-ID
|
Wat | Identificatie van de MAGDA API die werd aangesproken (e.g. het gebruikte endpoint) |
Wie | Identificatie van de toepassing van de afnemer |
Gebruiker | INSZ nummer of andere unieke identifier van de gebruiker van de toepassing van de afnemer |
Waarom | Finaliteit waarvoor deze vraag werd gesteld |
Wanneer | tijdstip waarop de vraag / het antwoord verwerkt wordt |
Over wie | Identificatie van het data subject waarop deze bevraging toepassing heeft. |
