M2M identificatie, authenticatie en autorisatie

Titel	M2M identificatie, authenticatie en autorisatie
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming implementatie in beheer
Versie	0.9.1
Datum	27 Mei 2024
Auteur	Architectenraad Edu-V
Acties	Geen acties

Binnen Edu-V wisselen Leveranciers gegevens uit via M2M gegevensuitwisselingen. Hiervoor implementeert iedere Leverancier een identificatie, authenticatie en autorisatie oplossing. De werking hiervan wordt hieronder nader toegelicht op deze pagina en bestaat uit de volgende onderdelen:

1 NL GOV Assurance profile voor OAuth 2.0
2 Proces: interactieanalyse identificatie en authenticatie middels OAuth 2.0

NL GOV Assurance profile voor OAuth 2.0

Binnen Edu-V worden M2M gegevensuitwisselingen geïdentificeerd en geauthenticeerd op basis van het NL GOV Assurance profile voor OAuth 2.0. Dit NL GOV OAuth 2.0 profiel is onderdeel van de API Strategie van het Kennisplatform APIs. Het Kennisplatform APIs is een initiatief van onder meer Bureau Forum Standaardisatie, Geonovum, Kamer van Koophandel, VNG Realisatie en Logius die allen het manifest ondertekend hebben.

Edukoppeling

De werkgroep Edukoppeling heeft een Best Practice ontwikkeld voor implementatie van het NL GOV Assurance profile voor OAuth 2.0. Deze Best Practice is ook van toepassing op het Edu-V afsprakenstelsel. Edu-V conformeert zich aan de afspraken die zijn gemaakt in de werkgroep Edukoppeling waardoor we technische interoperabiliteit over alle onderwijssectoren borgen.

Het profiel gaat er in de basis vanuit dat er met standaardcomponenten een verbinding opgezet kan worden geïnitieerd vanuit een eindgebruiker (Authorization code flow) of tussen twee machines (Client Credentials flow). De Client Credentials flow is bijvoorbeeld van toepassing bij een batchproces.

Binnen Edu-V hebben we te maken met de variant Client Credentials flow. Leveranciers wisselen immers via hun referentiecomponenten gegevens uit met de referentiecomponenten van andere leveranciers. Dit zijn veelal batchprocessen.

Binnen de specificatie van het NL GOV profiel zijn de volgende onderdelen van toepassing op Edu-V:

Direct Access Client voor referentiecomponenten die een request doen op een API van een andere referentiecomponent. Deze referentiecomponenten voldoen aan de gestelde eisen in het profiel:
- Een verzoek aan het token endpoint wordt door de Client gedaan op basis van:
  - Private key jwt en met het grant_type client_credentials. Op dit punt wijken we af van de documentatie waarin authorization_code wordt voorgeschreven.
  - In het verzoek wordt de scope meegegeven van de resources die bevraagt gaan worden. Binnen Edu-V zijn de gegevensdiensten voorzien van specifieke scopes op basis van de vereiste uit het profiel voor protecting resources.
- De Client beschikt over public en private Client keys.
- Aangezien de Client door een andere organisatie wordt ingevuld dan de autorisatie- en resourceserver beschikt de leverancier over een PKIoverheid certificaat met een OIN.
- Een verzoek aan de resourceserver wordt gedaan met het verkregen token.
Autorisatieserver en resourceserver voor de referentiecomponenten die de API aanbieden en requests van Clients ontvangen. Deze referentiecomponenten voldoen aan de gestelde eisen in het profiel:
- Client registration met een unieke client identifier voor iedere referentiecomponent, ongeacht of deze referentiecomponenten in een enkele applicatie gebundeld zijn door een leverancier.
- Dynamic registration van clients hoeft niet ondersteund te worden.
- Het kunnen verwerken van een verzoek aan het token endpoint van de autorisatieserver en het teruggeven van een token response op basis van JWT Bearer Tokens. Introspectie, token revocation en refresh tokens worden niet toegepast.
- Het token heeft een maximale levensduur van één uur. Op dit vlak zijn we strikter dan de voorgeschreven zes uur voor Direct Access Clients.
- Het aanbieden van de discovery endpoints issuer, token_endpoint en jwks_uri. Het authorization_endpoint is niet verplicht. Ook op dit punt wijken we af van de specificatie.
- De resource server voldoet aan de vereisten zoals gesteld in het protected resource profile.
- Aangezien de Client door een andere organisatie wordt ingevuld dan de autorisatie- en resourceserver beschikt de leverancier over een PKIoverheid certificaat met een OIN.

Proces: interactieanalyse identificatie en authenticatie middels OAuth 2.0

In Figuur 1 is het interactiediagram voor de identificatie en authenticatie middels OAuth2.0 beschreven. In het geïllustreerde scenario wil Leverancier A het endpoint van Leverancier B gaan bevragen.

Hierbij dient opgemerkt te worden dat er ook gewerkt kan worden met push berichten. Het is dus niet per definitie zo dat Leverancier A ook de Afnemer is en Leverancier B de Bron is. In het geval van een push bericht is Leverancier A de Verzender en Leverancier B de Ontvanger. De Verzender zal in dat geval een POST request willen doen bij de Ontvanger. De bevrager van het endpoint is in dat geval de Verzender en de aanbieder van het endpoint de Ontvanger.

Interactieanalyse identificatie, authenticatie en autorisatie middels OAuth2.0

De wijze van identificeren, authenticeren en autoriseren is afhankelijk van de gegevensdiensten die Leverancier A wil gaan uitwisselen. Afhankelijk van de gegevensclassificatie voor het informatieobject zijn er additionele authenticatie en autorisatieregels van toepassing. Het betreft:

VERTROUWELIJK van toepassing op uitwisseling van vertrouwelijke informatieobjecten
activering van toepassing op uitwisseling van informatieobjecten waarbij Onderwijsorganisatie regie heeft op de uitwisseling

In onderstaand schema is per gegevensclassificatie weergegeven of de maatregelen al dan niet van toepassing zijn.

Classificatie	OAuth 2.0 profiel	VERTROUWELIJK	activering

Classificatie	OAuth 2.0 profiel	VERTROUWELIJK	activering
I	NL GOV OAuth 2.0 Client Credentials (optioneel) verzoek kan ook direct naar resourceserver	Nee	Nee
II	NL GOV OAuth 2.0 Client Credentials	Nee	Ja
III	NL GOV OAuth 2.0 Client Credentials	Ja	Nee
IV	NL GOV OAuth 2.0 Client Credentials	Ja	Ja

Het proces bestaat uit de volgende stappen:

Stap	Toelichting

Stap	Toelichting
1.	Leverancier A wil een endpoint van Leverancier B gaan bevragen. De API Client van Leverancier A doet een authenticatierequest bij de Autorization Server van Leverancier B. de Aanvraag van een Token gaat middels de NL GOV OAuth 2.0 Client Credentials flow zodra Vertrouwelijk en/of activering van toepassing zijn. Voor gegevensclassificatie I is deze stap optioneel. Er kan dan direct een verzoek worden gedaan op de resourceserver (vanaf stap 5) en zonder gebruik te maken van een Token.
2.	De Authorization Server van Leverancier B beoordeelt het token verzoek. Tevens wordt gecontroleerd of Leverancier A geautoriseerd is om voor de aangevraagde scope gegevens uit te wisselen.
3.	Indien deze correct zijn dan genereert de Authorization Server een Token voor Leverancier A.
4.	Het Token wordt door de Authorization Server van Leverancier A naar de Client van Leverancier B gestuurd.
5.	Leverancier A gebruikt het Token om een endpoint bij Leverancier B te bevragen. Voor gegevensclassificatie I is het niet verplicht om een token te gebruiken om een request te doen aan de resourceserver.
6.	Leverancier B controleert bij een API Request het Token en past hierbij een controle toe op: Geldigheid van het Token Beschikt de Client over de scopes die van toepassing zijn op het bevraagde endpoint Deze stap kan overgeslagen worden voor gegevensclassificatie I.
7.	Indien activering van toepassing is (classificatie II en IV) dan worden de volgende extra maatregelen getroffen: De Resource Server controleert of de gegevensdienst voor de onderwijsorganisatie is geactiveerd. Hiervoor maakt de Resource Server gebruik van de registratie van de actieve gegevensuitwisselingen uit de consentregistratie. De Resource Server heeft hiervoor een passende implementatie van de autorisaties die voortkomen uit de verlening van consent.
8.	Indien de controles succesvol zijn geeft Leverancier B toegang tot het endpoint en wordt aan het request voldaan. De response wordt gestuurd naar Leverancier A.

Release notes

Deze uitwerking is gebaseerd op basis van de volgende stappen:

0.0.1: Op basis van uitkomsten uit Werkgroep Edukoppeling is een interactieanalyse uitgewerkt voor de aankomende Secure API OAuth profielen.
0.0.2: Verwijzing toegevoegd naar Edukoppeling profiel 2023-07-24 Edukoppeling - Secure API OAuth Client Credentials profielen v0.8 (concept)
0.0.3: Definities gewijzigd op basis van herziening referentiecomponenten en gegevensdefinities.
0.0.4: De pagina is besproken tijdens de bijeenkomst van de Architectenraad Edu-V en is gereed voor de ROSA-architectuurscan.
0.0.5: De werkgroep Edukoppeling gaat het Secure API OAuth Client Credentials profiel niet verder ontwikkelen en direct verwijzen naar het NL GOV Assurance profile voor OAuth 2.0. Dit leidt ook tot wijzigingen binnen de toepassing van M2M identificatie, authenticatie en autorisatie voor Edu-V. De wijzigingen zijn verwerkt op deze pagina. In een separate paragraaf zijn een aantal expliciete keuzes gemaakt uit het NL GOV profiel voor de toepassing binnen Edu-V.
0.0.6: Vanuit de wijziging in het architectuurkader is het edu_org_id verwijderd uit de query parameter. Dit heeft geleid tot wijzigingen in de uitwerking van de interactie-analyse.
0.9.0: Het Architectuurkader Edu-V is vastgesteld als startpunt voor de implementatie. Tevens is instemming verleend op verdere doorontwikkeling van het Architectuurkader Edu-V op basis van de Architectuurprincipes. Dit akkoord is verleend op het Bestuurlijk Overleg van 27 mei 2024.
- De M2M identificatie, authenticatie en autorisatie wordt tijdens de eerste release geïmplementeerd. Na een succesvolle implementatie wordt de uiteindelijke 1.0.0 versie vastgesteld.
0.9.1: Verwijziging naar Best Practice Edukoppeling voor NL GOV Assurance profile voor OAuth 2.0 toegevoegd.