M2M identificatie, authenticatie en autorisatie

Titel	M2M identificatie, authenticatie en autorisatie
Status	IN ONTWIKKELING ROSA-ARCHITECTUURSCAN BESLUITVORMING IMPLEMENTATIE IN BEHEER
Versie	0.9.2
Datum	27 September 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:

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 met Direct Access Clients).

Binnen Edu-V hebben we te maken met de variant van uitwisseling tussen twee machines. Leveranciers wisselen immers via hun referentiecomponenten gegevens uit met de referentiecomponenten van andere leveranciers.

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:
- MUST Een verzoek aan het token endpoint wordt door de Client gedaan op basis van:
  - MUST Private key jwt en met het grant_type client_credentials en voor een client_id.
  - SHOULD In het verzoek worden de scopes 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.
- MUST De Client beschikt over een PKIoverheid certificaat met Client keys bestaande uit een publieke en een private key.
- MUST De publieke key wordt door de Client beschikbaar gesteld middels een jaks_uri.
  - De private key wordt door de Client gehanteerd om in de private_key_jwt flow de Client_jwt te signeren.
  - De autorisatieserver kan met de publieke key vervolgens de Client_jwt ontcijferen. De publieke key verkrijgt de autorisatieserver via de jaks_uri.
- MUST Een verzoek aan de resourceserver wordt gedaan met het token dat door de Autorisatieserver is uitgegeven aan de Client.
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:
- MUST Client registration met een unieke client_id voor iedere applicatie.
  - MUST De client_id wordt bepaald door de leverancier die de autorisatieserver aanbiedt.
  - SHOULD NOT client_id is bij voorkeur niet gelijk aan het OIN. Het OIN wordt gehanteerd om de organisatie vast te stellen. Het client_id is gericht op de identificatie en de authenticatie van de applicatie van de leverancier.
- COULD Dynamic registration van clients hoeft niet ondersteund te worden.
- MUST 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.
- MUST Het token heeft een maximale levensduur van één uur. Op dit vlak zijn we strikter dan de voorgeschreven zes uur voor Direct Access Clients.
- COULD 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.
- MUST De resource server voldoet aan de vereisten zoals gesteld in het protected resource profile.
- MUST De autorisatieserver verifieert of de client_id van de Client en de OIN uit het PKIoverheid certificaat overeenkomen met de gegevens in de eigen Clientregistratie.
- MUST De autorisatieserver verifieert de geldigheid, certificaateketen en de CRL voor het door de Client gehanteerde PKIoverheid certificaat.

De bovenstaande implementatiekeuzes van het NL GOV OAuth profiel zijn nader uitgewerkt in een interactieanalyse.

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.

m2m_identificatie_authenticatie_oauth_private_key_jwt.png

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
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
1.	Leverancier A wil een endpoint van Leverancier B gaan bevragen. De API Client van Leverancier A gaat een tokenverzoek bij de Autorisatieserver van Leverancier B. de Aanvraag van een Token gaat middels de NL GOV OAuth 2.0 Client Credentials flow in de variant `private_key_jwt` zodra VERTROUWELIJK en/of ACTIVERING van toepassing zijn. De eerste stap is dat de Client een `Client_jwt` gaat opstellen, hierin de gevraagde `scopes` specificeert, en deze signeert met de `private key` uit de `Client keys` van het eigen PKIoverheid certificaat. Voor gegevensclassificatie I is deze stap optioneel. Er kan dan direct een verzoek worden gedaan op de resourceserver (vanaf stap 11) en zonder gebruik te maken van een Token.
2.	Leverancier A doet een tokenverzoek bij de Autorisatieserver van Leverancier B en voor een Client met een `client_id` van de applicatie die gegevens gaat opvragen of versturen en benut de `Client_jwt` als een assertion in het `private_key_jwt` mechanisme.
3.	De Autorisatieserver haalt in de eigen Clientregistratie gegevens op over de Client om het tokenverzoek te kunnen beoordelen. De volgende gegevens worden opgehaald: `jwks_uri` om de public_key op te halen bij de Client. `scopes` om te kunnen valideren of de Client het recht heeft op de gevraagde `scopes`. `OIN`: om te kunnen valideren of de Client ook geregistreerd staat bij de OIN die de aanvraag voor het token doet.
4.	De Autorisatieserver haalt de `public key` van het PKIoverheid certificaat van Leverancier A op middels de `jaks_uri`.
5.	De Autorisatieserver ontcijfert de `Client_jwt` met de in de vorige stap verkregen `public key`.
6.	De Autorisatieserver beoordeelt het tokenverzoek van de Client voor de gevraagde `scopes`.
7.	De Autorisatieserver controleert of de Client staat geregistreerd bij `OIN` van het PKIoverheid certificaat van leverancier A.
8.	De Autorisatieserver controleert het PKIoverheid certificaat: Geldigheidsduur van het certificaat; Certificaatketen en issuer CRL
9.	Indien de validaties 5-8 allen succesvol zijn, dan genereert de Autorisatieserver een `Access Token` voor Leverancier A.
10.	Het `Access Token` wordt door de Autorisatieserver van Leverancier B naar de Client van Leverancier A gestuurd.
De identificatie, authenticatie en de autorisatie op gegevensdiensten (scopes) is na stap 10 afgerond. De stappen 11-14 zijn vervolgens van toepassing op iedere interactie tussen de Client van Leverancier A en de Resourceserver van Leverancier B zo lang het Token geldig is.
11.	Leverancier A gebruikt het `Access Token` om een endpoint op de resourceserver van Leverancier B te bevragen. Voor gegevensclassificatie I is het niet verplicht om een token te gebruiken om een request te doen aan de resourceserver.
12.	Leverancier B controleert bij een API Request het `Access Token` en past hierbij een controle toe op: Geldigheidsduur van het `Access Token` Beschikt de Client over de scopes die van toepassing zijn op het bevraagde endpoint Deze stap kan overgeslagen worden voor gegevensclassificatie I.
13.	Indien ACTIVERING van toepassing is (classificatie II en IV) dan worden de volgende extra maatregelen getroffen: De Resourceserver controleert of de gegevensdienst voor de onderwijsorganisatie is geactiveerd. Hiervoor maakt de Resourceserver gebruik van de registratie van de actieve gegevensuitwisselingen uit de consentregistratie. De Resourceserver heeft hiervoor een passende implementatie van de autorisaties die voortkomen uit de verlening van consent.
14.	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.
0.9.2: Op basis van RFC008, RFC009, RFC010 en RFC011 is de werking van private_key_jwt in combinatie met het PKIoverheid certificaat nader toegelicht.