Scenario's voor overschakeling van de API-clients

Doel van deze presentatie: uitleggen welke stappen klanten gaan moeten zetten om hun API-Clients (Clients die een bepaalde API aanspreken) te migreren naar de nieuwe Identity Provider ACM (Toegangsbeheer van de Vlaamse overheid).

Dit schema is een voorbeeld van een Client Credential Grant, een eenvoudige OAuth-flow die een bepaalde toepassing toelaat om (namens zichzelf, als toepassing) een call te doen naar een bepaalde API. De flow gaat als volgt:

1. De toepassing ("Client", in het groen) wil de KLIP API aanspreken, maar deze wordt beschermd door de ACM OAuth Authorization Server (in het oranje). De toepassing heeft daarom eerst een token (een toegangsticket) van ACM nodig. De toepassing doet daarvoor een call naar het token endpoint van de ACM OAuth Authorization Server en authentiseert zich daarbij aan de hand van een JSON Web Key (zie verder voor meer info).
2. Indien de Client  de nodige toelatingen heeft, krijgt hij een token terug. Dit token is beperkt in de tijd en is opaque (= het heeft op zichzelf geen betekenis, alleen de leverancier van het token kent de betekenis).
3. De toepassing doet nu zijn gewenste call naar de KLIP API (in het blauw) en voegt daarbij het token toe om te bewijzen dat hij toegang heeft
4. De KLIP API ontvangt de request van de toepassing, maar controleert eerst het token van de toepassing door het token aan te bieden aan het introspection-endpoint van de ACM OAuth Authorization Server
5. De ACM OAuth Authorization Server bezorgt een antwoord aan de KLIP API over de validiteit van het token, met name of het token geldig is en welke scopes (rechten) het token heeft op de KLIP API (+ eventueel bijkomende informatie over de Client).
6. De KLIP API verwerkt nu volledig de request van de toepassing (b.v. lezen of schrijven van bepaalde informatie in KLIP) en bezorgt een antwoord aan de toepassing.

Belangrijk bij deze flow is dat de toepassing ("Client") op voorhand moet geregistreerd zijn bij de ACM OAuth Authorization Server.

Bovenstaand schema is een voorbeeld van een eenvoudige architectuur. In de praktijk gaat er b.v. langs de zijde van de KLIP API een API Gateway zijn die bepaalde handelingen namens de KLIP API doet, maar het principe blijft hetzelfde.

Er is beslist om voortaan enkel nog met JSON Web Key (JWK's) te werken en niet meer met Client Secrets. Een JWK is namelijk vanuit een veiligheidsinvalshoek superieur aan een Client Secret:

• Een Client Secret is een shared key en moet dus gekend zijn door beide partijen. De sleutel staat dus op 2 plaatsen, een dubbel risico op een lek.
• Een JWK is een sleutelpaar (een private en een publieke sleutel die cryptografisch aan elkaar gelinkt zijn). De private sleutel verlaat de toepassing niet, enkel de publieke sleutel wordt aan de andere partij (ACM) bezorgd. Er is dus maar 1 plaats waar de private sleutel wordt opgeslaan.

Een aantal bijkomende opmerkingen m.b.t. JWK's:

• We kunnen zowel met ongetekende JWK's werken (zonder certificaten) en met getekende JWK's (op basis van certificaten, via het "x5c"-attribuut in de JWK). Het ACM-portaal staat beide toe. Individuele API's kunnen daar echter een bepaalde policy opleggen (onderdeel van hun configuratie met ACM) aan Clients die ACM met hen willen connecteren. Daarover zal echter steeds gecommuniceerd worden waar nodig.
• Vanuit een veiligheidsoogpunt raden wij zoveel mogelijk aan om met aparte sleutelparen (JWK's) te werken voor aparte Clients. Je kan in theorie JWK's hergebruiken, maar dit verhoogt natuurlijk het risico en de impact van een lek van de sleutel.
• Naast het werken met een JWK ondersteunen we binnen het ACM-platform ook het werken met een JWKS (JSON Web Key Set). Dit is een endpoint die je zelf als klant voorziet en waarvan je de URL doorgeeft aan ACM. Op dit endpoint kan je zelf je JWK's publiceren voor je Client(s). Bij authenticatie van je Client zoekt ACM dan op dit JWKS-endpoint je publieke sleutel op. Dit heeft als voordeel dat je zelf je JWK's kan roteren (zonder daarvan ACM op de hoogte te moeten stellen). Het nadeel is dat je JWKS-endpoint natuurlijk steeds beschikbaar moet zijn of je Client gaat zich niet kunnen authentiseren.

Uiteraard zijn veel gegevens vandaag al beschikbaar in de Geosecure-databank. Waar mogelijk zetten we deze zelf over, zodat de klant deze informatie niet opnieuw moet aanleveren.

Het doel van het ACM Selfservice Portaal ("Beheerportaal") is om op termijn alle interacties tussen klanten en het Toegangsbeheer (ACM) aan te bieden als selfservice via het het portaal. Dit is een grote vereenvoudiging van de huidige processen, die vaak asynchroon zijn en via e-mail gebeuren.

Klanten kunnen zelf hun toegang tot het Beheerportaal instellen door gebruikers het recht "API-beheerder" toe te kennen voor hun organisatie in het Gebruikersbeheer van de Vlaamse overheid (IDM). Wettelijk vertegenwoordigers (zoals opgegeven in het KBO) zullen dit niet moeten doen. Zij kunnen automatisch als "API-beheerder" binnen in het Beheerportaal voor hun organisatie.

Een aantal bijkomende opmerkingen:

• De JWK van een Client kan gemigreerd worden omdat het de publieke sleutel is die is opgeslaan in de huidige Geosecure-databank. Deze is sowieso publiek. Er is dus geen risico op het compromitteren van de private sleutel (die alleen bij de klant bekend is). Het laat klanten ook toe om hun huidige sleutelparen te blijven gebruiken.
• De oude ClientID van bestaande Clients bij Geosecure zal door ACM opgeslaan worden als een apart attribuut van de Client (omdat sommige API's en componenten binnen de Vlaamse overheid die oude ID nog nodig hebben). Klanten zullen voortaan echter moeten werken met de nieuwe ClientID die door ACM zal toegekend worden.
• We zullen een gedetailleerde handleiding ter beschikking stellen met de exacte verschillen tussen Geosecure en ACM op het vlak van token-requests en token-responses.

De grootste wijzigingen situeren zich dus vooral in de volgende gevallen:

• Als je vandaag een Client Secret gebruikt, dan ga je moeten overstappen naar JWK
• Als je vandaag Authorization Code Grant (in B2B-variant) gebruikt, dan ga je moeten overschakelen naar verschillende Client Credential Grants

Hieronder worden de verschillende scenario's in detail uitgelegd. Belangrijk hierbij is dat we hier geen onderscheid maken tussen test- en productieomgeving. Het is een generiek proces. Voor Clients in de testomgeving zal je het proces in de testomgeving moeten doorlopen. Voor Clients in de productieomgeving zal je het proces in de productieomgeving moeten doorlopen.

Samenvatting:

• Je hebt momenteel 1 Client Credential Grant-Client bij Geosecure, met een JWK
• Je stapt over naar 1 Client Credential Grant-Client bij ACM (1:1-relatie), met een JWK
• De Client zal automatisch aangemaakt worden door Digitaal Vlaanderen via de bulkmigratie. De JWK wordt overgenomen in de bulkmigratie.

Stappenplan

1. Digitaal Vlaanderen zet je Client over als onderdeel van de bulkmigratie
2. Digitaal Vlaanderen bezorgt je een gerichte communicatie wanneer je kan starten met jouw migratieacties voor deze Client
3. Je geeft een of meerdere van je medewerkers/collega's toegang tot het ACM Selfservice Portaal via het Gebruikersbeheer van de Vlaamse overheid (IDM)(= grofmazige toegang tot het portaal)
4. Je meldt aan op het ACM Selfservice Portaal en stelt (voor je specifieke Client, door Digitaal Vlaanderen gemigreerd) in welke persoon de eigenaar is van de Client en eventueel welke andere personen daarnaast "editeer"-rechten hebben op de Client (= fijnmazige toegang per individuele Client).
5. Je doet de nodige aanpassingen aan de configuratie/code van je toepassing zodat die voortaan OAuth-tokens bij ACM kan komen opvragen (in plaats van bij Geosecure)
6. Je test of je met deze Client een token kan opvragen en de gewenste API (b.v. de KLIP API) kan bereiken zoals voorheen
7. Van zodra de test geslaagd is kan je ervoor kiezen om definitief over te schakelen naar de nieuwe Client. Je bent daarna klaar met de migratie voor deze Client.

Samenvatting:

• Je hebt momenteel 1 Client Credential Grant-Client bij Geosecure, met een Secret
• Je stapt over naar 1 Client Credential Grant-Client bij ACM (1:1-relatie), met een JWK
• De Client zal automatisch aangemaakt worden door Digitaal Vlaanderen via de bulkmigratie. De JWK wordt niet overgenomen tijdens de bulkmigratie aangezien er geen is. Je zal zelf een JWK moeten maken.

Stappenplan

1. Digitaal Vlaanderen zet je Client over als onderdeel van de bulkmigratie
2. Digitaal Vlaanderen bezorgt je een gerichte communicatie wanneer je kan starten met jouw migratieacties voor deze Client
3. Je geeft een of meerdere van je medewerkers/collega's toegang tot het ACM Selfservice Portaal via het Gebruikersbeheer van de Vlaamse overheid (IDM)(= grofmazige toegang tot het portaal)
4. Je meldt aan op het ACM Selfservice Portaal en stelt (voor je specifieke Client, door Digitaal Vlaanderen gemigreerd) in welke persoon de eigenaar is van de Client en eventueel welke andere personen daarnaast "editeer"-rechten hebben op de Client (= fijnmazige toegang per individuele Client).
5. Je stelt een JWK in voor de Client op het ACM Selfservice Portaal (aangezien je voortaan niet meer met Client Secret mag werken en er nog geen JWK was)
6. Je doet de nodige aanpassingen aan de configuratie/code van je toepassing zodat die voortaan OAuth-tokens bij ACM kan komen opvragen (in plaats van bij Geosecure)
7. Je test of je met deze Client een token kan opvragen en de gewenste API (b.v. de KLIP API) kan bereiken zoals voorheen
8. Van zodra de test geslaagd is kan je ervoor kiezen om definitief over te schakelen naar de nieuwe Client. Je bent daarna klaar met de migratie voor deze Client.

Samenvatting:

• Je hebt momenteel 1 B2B Authorization Code Grant-Client bij Geosecure, met een JWK
• Je stapt over naar 1 of meerdere Client Credential Grant-Client(s) bij ACM (1:n-relatie, een per klant waarvoor je als dienstverlener optreedt), telkens met een JWK
• De Clients zullen niet automatisch aangemaakt worden door Digitaal Vlaanderen via de bulkmigratie. De JWK wordt niet overgenomen tijdens de bulkmigratie aangezien er geen bulkmigratie gebeurt in dit scenario. Je moet de Client(s) zelf aanmaken.

Stappenplan (per Client die je moet aanmaken)

1. Digitaal Vlaanderen bezorgt je een gerichte communicatie wanneer je kan starten met jouw migratieacties voor deze Client
2. Je geeft een of meerdere van je medewerkers/collega's toegang tot het ACM Selfservice Portaal via het Gebruikersbeheer van de Vlaamse overheid (IDM)(= grofmazige toegang tot het portaal)
3. Je meldt aan op het ACM Selfservice Portaal en creëert een nieuwe Client. Je bepaalt daarbij namens welke klant je de Client wil aanmaken (in delegatie) en welke API je met deze Client wil gebruiken.
4. (Parallel) Indien dat nog nodig is stel je op het ACM Selfservice Portaal in welke andere personen daarnaast "editeer"-rechten hebben op de Client (= fijnmazige toegang per individuele Client).
5. (Parallel) Indien dat nog niet gebeurd is tijdens de creatie stel je een JWK in voor de Client op het ACM Selfservice Portaal (aangezien er geen bulkmigratie heeft plaatsgevonden en er dus geen JWK is overgenomen).
6. Je doet de nodige aanpassingen aan de configuratie/code van je toepassing zodat die voortaan OAuth-tokens bij ACM kan komen opvragen (in plaats van bij Geosecure)
7. (Parallel) Na de creatie van je Client moet de eigenaar van de API (waar je toegang toe wilt) bij Digitaal Vlaanderen je toegangsaanvraag goedkeuren op het ACM Selfservice Portaal
8. (Parallel) In dit scenario werk je als dienstverlener in delegatie van een bepaalde klant. De klant moet zijn expliciet akkoord daarvoor geven in het ACM Selfservice Portaal (zie volgende stap). De klant moet dus een een of meerdere van zijn medewerkers toegang geven tot het ACM Selfservice Portaal via het Gebruikersbeheer van de Vlaamse overheid (IDM)(= grofmazige toegang tot het portaal)
9. (Parallel) Na de creatie van je Client moet de klant je delegatieaanvraag goedkeuren op het ACM Selfservice Portaal
10. Je test of je met deze Client een token kan opvragen en de gewenste API (b.v. de KLIP API) kan bereiken zoals voorheen
11. Van zodra de test geslaagd is kan je ervoor kiezen om definitief over te schakelen naar de nieuwe Client. Je bent daarna klaar met de migratie voor deze Client.

Verdere opmerkingen

• In dit scenario ga je van 1 Client in de oude situatie naar meerdere Clients in de nieuwe situatie. Aangezien je vroeger maar 1 JWK gebruikte is de vraag of je die ene JWK nu mag gebruiken voor alle nieuwe Clients. Zoals eerder vermeld raden wij zoveel mogelijk aan om per Client met een aparte JWK te werken, vanuit een veiligheidsinvalshoek. Het platform maakt het echter niet onmogelijk om dezelfde JWK te hergebruiken. De keuze ligt dus ultiem bij jullie, maar wij bevelen sterk aan om aparte JWK's per Client te gebruiken.

Deze werkwijze is identiek als deze van scenario 3 aangezien je in beide scenario's zelf de creatie van de Client moet doen. Zie scenario 3 voor de uitleg bij de stappen.

Je kan ons steeds contacteren via het e-mailadres uitfaseringgeosecure@vlaanderen.be