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 |
|
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 eenclient_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 deClient_jwt
te signeren.De autorisatieserver kan met de publieke key vervolgens de
Client_jwt
ontcijferen. De publieke key verkrijgt de autorisatieserver via dejwks_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. Hetclient_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
enjwks_uri
. Hetauthorization_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.
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 |
---|---|---|---|
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 |
---|---|
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 De eerste stap is dat de Client een 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 |
3. | De Autorisatieserver haalt in de eigen Clientregistratie gegevens op over de Client om het tokenverzoek te kunnen beoordelen. De volgende gegevens worden opgehaald:
|
4. | De Autorisatieserver haalt de |
5. | De Autorisatieserver ontcijfert de |
6. | De Autorisatieserver beoordeelt het tokenverzoek van de Client voor de gevraagde |
7. | De Autorisatieserver controleert of de Client staat geregistreerd bij |
8. | De Autorisatieserver controleert het PKIoverheid certificaat:
|
9. | Indien de validaties 5-8 allen succesvol zijn, dan genereert de Autorisatieserver een |
10. | Het |
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 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
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:
|
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