M2M identificatie, authenticatie en autorisatie

Titel

M2M identificatie, authenticatie en autorisatie

Status

DRAFT ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT

Stadium

POC PILOT BEHEER

Versie

0.0.2

Datum

26 juli 2023

Auteur

Architectenraad Edu-V

Acties

  • Geen acties

Binnen Edu-V wisselen Deelnemers gegevens uit via M2M gegevensuitwisselingen. Hiervoor implementeert iedere Deelnemer een identificatie, authenticatie en autorisatie oplossing. De werking hiervan wordt hieronder nader toegelicht in een interactieanalyse.

Globale beschrijving

Deze pagina beschrijft op hoofdlijnen de beoogde werking van het identificeren, authenticeren en autoriseren van M2M gegevensuitwisselingen op basis van de Edukoppeling Secure API OAuth profielen. De gedetailleerde informatie is te vinden in de beschrijving van het profiel op de website van Edustandaard:

2023-07-24 Edukoppeling - Secure API OAuth Client Credentials profielen v0.8 (concept)

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 Ontvanger is en Leverancier B de Verzender. Het kan ook omgekeerd zijn. 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 gegevenssoorten die Leverancier A wil gaan uitwisselen. Afhankelijk van de gegevensclassificatie voor de gegevenssoort zijn er additionele authenticatie en autorisatieregels van toepassing. Het betreft:

  • VERTROUWELIJK van toepassing op uitwisseling van vertrouwelijke gegevens

  • activering van toepassing op uitwisseling van gegevens waarbij Onderwijsorganisatie regie heeft op de uitwisseling

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

Classificatie

Edukoppeling profiel

VERTROUWELIJK

activering

Classificatie

Edukoppeling profiel

VERTROUWELIJK

activering

I

Secure API OAuth client credentials profiel (GCI)

Nee

Nee

II

Secure API OAuth client credentials profiel (GCII)

Nee

Ja

III

Secure API OAuth client credentials profiel (GCIII)

Ja

Nee

IV

Secure API OAuth client credentials profiel (GCIV)

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 een standaard OAuth2.0 client credentials flow.

Leverancier A neemt de volgende zaken op in de Request:

  • Client ID, ontvangen van Leverancier B voor de referentiecomponent van Leverancier A

  • Client secret, ontvangen van Leverancier B voor de referentiecomponent van Leverancier A

  • Scope, Leverancier A geeft aan welke gegevenssoort uitgewisseld gaat worden. Zie voor de lijst met scopes: Gegevenssoorten, Verzenders en Ontvangers.

Indien Vertrouwelijk van toepassing is (classificatie III en IV) dan worden de volgende extra maatregelen getroffen:

  • Request wordt gedaan via mTLS gebruik makend van een PKI-overheidscertificaat geregistreerd met het OIN van de Leverancier.

2.

De Authorization Server van Leverancier B beoordeelt de aanvraag van Leverancier A en controleert de credentials. Tevens wordt gecontroleerd of Leverancier A geautoriseerd is om voor de aangevraagde scope gegevens uit te wisselen.

Indien Vertrouwelijk van toepassing is (classificatie III en IV) dan worden de volgende extra maatregelen getroffen:

  • Leverancier B controleert de identiteit van Leverancier B aan de hand van het OIN en het PKI-overheidscertificaat.

3.

Indien deze correct zijn dan genereert de Authorization Server een Token voor Leverancier A.

  • Het Formaat voor het Token is voorgeschreven. Dit wordt nader uitgewerkt in de Secure API OAuth profielen van Edukoppeling (RFC, Signing, etc.)

  • In het Token wordt het Client Id en de aangevraagde Scope opgenomen.

Indien Vertrouwelijk van toepassing is (classificatie III en IV) dan worden de volgende extra maatregelen getroffen:

  • Het Token heeft een maximale geldigheid van 1 uur.

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. Het Token wordt conform de standaard van OAuth2.0 opgenomen in de Authorization Header bij iedere API request.

Indien activering van toepassing is (classificatie II en IV) dan worden de volgende extra maatregelen getroffen:

  • In de request wordt verplicht de parameter edu_org_id opgenomen. Leverancier A wil gegevens gaan uitwisselen voor de opgegeven edu_org_id.

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

7.

Indien activering van toepassing is (classificatie II en IV) dan worden de volgende extra maatregelen getroffen:

  • De Resource Server controleert of de gegevensuitwisseling van de gegevenssoort voor de onderwijsorganisatie is geactiveerd.

  • Hiervoor maakt de Resource Server gebruik van de registratie van de actieve gegevensuitwisselingen van de component Consentmanagement.

  • De controle wordt toegepast op basis van:

    • Het Client Id (voor de Referentiecomponent van Leverancier A) en eventueel het bijbehorende OIN van Leverancier A.

    • Het edu_org_id van de Onderwijsaanbieder opgenomen in de request door Leverancier A in stap 5).

    • De gegevenssoort van het endpoint dat bevraagd wordt door Leverancier A in het request.

  • In dit schema wordt de controle toegepast in de component Consentmanagement. Het is ook mogelijk dat deze controle wordt toegepast op de Resource Server zelf. Dat is een implementatiekeuze.

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: