Versions Compared

Old Version 28

changes.mady.by.user Koen Voermans

Saved on

compared with

New Version Current

changes.mady.by.user Koen Voermans

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Titel

M2M identificatie, authenticatie en autorisatie

Status

Status
titleIn ontwikkeling
Status
titleROSA-Architectuurscan
Status
titleBEsluitvorming
Status
colourYellow
titleimplementatie
Status
titlein beheer

Versie

0.9.02

Datum

27 Mei September 2024

Auteur

Architectenraad Edu-V

Acties

  • Geen acties

...

Info

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). De Client Credentials flow is bijvoorbeeld van toepassing bij een batchproces.

Binnen Edu-V hebben we te maken met de variant Client Credentials flowvan uitwisseling tussen twee machines. 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:

    • Status
      colourGreen
      titlemust
      Een verzoek aan het token endpoint wordt door de Client gedaan op basis van:

      • Status
        colourGreen
        titlemust
        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 en voor een client_id.

      • Status
        colourBlue
        titleSHOULD
        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.

    • Status
      colourGreen
      titlemust
      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 PKIoverheid certificaat met Client keys bestaande uit een publieke en een private key.

    • Status
      colourGreen
      titlemust
      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 jaks_uri.

    • Status
      colourGreen
      titlemust
      Een verzoek aan de resourceserver wordt gedaan met het verkregen tokentoken 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:

    • Status
      colourGreen
      titlemust
      Client registration met een unieke client identifier _id voor iedere referentiecomponent, ongeacht of deze referentiecomponenten in een enkele applicatie gebundeld zijn door een leverancier.applicatie.

      • Status
        colourGreen
        titleMUST
        De client_id wordt bepaald door de leverancier die de autorisatieserver aanbiedt.

      • Status
        colourRed
        titleSHOULD 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.

    • Status
      colourPurple
      titleCOULD
      Dynamic registration van clients hoeft niet ondersteund te worden.

    • Status
      colourGreen
      titlemust
      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.

    • Status
      colourGreen
      titlemust
      Het token heeft een maximale levensduur van één uur. Op dit vlak zijn we strikter dan de voorgeschreven zes uur voor Direct Access Clients.

    • Status
      colourPurple
      titleCOULD
      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.

    • Status
      colourGreen
      titlemust
      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

    • Status
      colourGreen
      titlemust
      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.

    • Status
      colourGreen
      titlemust
      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

...

Het proces bestaat uit de volgende stappen:

Tip

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.

B gestuurd

Stap

Toelichting

1.

Leverancier A wil een endpoint van Leverancier B gaan bevragen. De API Client van Leverancier A doet gaat een authenticatierequest tokenverzoek bij de Autorization Server 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

Status
colourYellow
titleVertrouwelijk
en/of
Status
colourBlue
titleactivering
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 511) 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 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.

410.

Het Access Token wordt door de Authorization Server van Leverancier A naar 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.

511.

Leverancier A gebruikt het Access Token om een endpoint bij 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.

612.

Leverancier B controleert bij een API Request het Access Token en past hierbij een controle toe op:

  • Geldigheid 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.

713.

Indien

Status
colourBlue
titleactivering
van toepassing is (classificatie II en IV) dan worden de volgende extra maatregelen getroffen:

  • De Resource Server Resourceserver controleert of de gegevensdienst voor de onderwijsorganisatie is geactiveerd.

  • Hiervoor maakt de Resource Server Resourceserver gebruik van de registratie van de actieve gegevensuitwisselingen uit de consentregistratie.

  • De Resource Server Resourceserver heeft hiervoor een passende implementatie van de autorisaties die voortkomen uit de verlening van consent.

814.

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.

...

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.