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 jwks_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 jwks_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
Interactieanalyse identificatie, authenticatie en autorisatie middels OAuth2.0 private_key_jwt

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:

Clientregistratie

Dit proces gaat er vanuit dat de Client van Leverancier A succesvol geregistreerd en aangesloten is op de Autorisatieserver van Leverancier B. Voor meer informatie zie de paragraaf Registratie op de pagina M2M gegevensuitwisselingen.

Stap

Toelichting

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 jwks_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