Voor REST API’s biedt het Vlaams Toegangsbeheer (ACM) een OAuth Authorization Server aan, waarin de autorisaties voor de afnemertoepassingen of voor de gebruikers en de scopes geverifieerd kunnen worden. Voor server-naar-server trafiek - dus in naam van de afnemertoepassing zelf - kan een REST API resource de autorisatie laten afhandelen door de OAuth Authorization Server (ACM IDP) via de Client Credentials Grant. Wat is de OAuth Client Credentials Grant precies, en wat betekent dit concreet voor mijn REST API's? Ontdek het hier!

Wat is de OAuth Client Credentials Grant?

Via de Client Credentials Grant kan een toepassing een Access Token aanvragen. Het is bedoeld voor niet-interactieve toepassingen zoals een backoffice-toepassing, een service die op een backend draait, een daemon of een CLI. Hierbij wordt het token geïssued voor de toepassing zelf en niet voor een eindgebruiker. De afnemertoepassing ontvangt een specifieke ClientID voor iedere API die deze wil bevragen. De autorisatie bij de OAuth Authorization Server van een REST-call naar een API verloopt in volgende stappen:

1. De afnemertoepassing (= de Client) vraagt een token aan bij het Token Endpoint en authenticeert zich hiervoor.

2. Indien de authenticatie succesvol was, dan ontvangt de Afnemer toepassing een Access Token.

3. De Afnemer toepassing bezorgt het Access Token aan de API (= de Resource).

4. De API valideert het Access Token bij het OAuth Introspection Endpoint.

5. Het OAuth Introspection Endpoint valideert het Access Token en geeft de scopes voor dit request mee.

6. De API bezorgt de afnemer toepassing de gevraagde informatie.

Een gedetailleerde toelichting bij elk van deze stappen, kan men desgewenst terugvinden in de ACM-documentatie. 

Wat betekent dit concreet voor uw REST API's?

Indien u één of meerdere REST API's beheert, kan u middels een integratie met het Vlaams Toegangsbeheer (ACM) afdwingen dat de afnemertoepassingen van uw API, uw API op een beveiligde manier moeten bevragen. Op die manier kan u vermijden dat partijen met slechte intenties uw API's kunnen gebruiken en de verstrekte informatie/gegevens kunnen misbruiken. OAuth (Open Authorization) is in de IAM-wereld de aangewezen internationale standaard voor de beveiliging van API's, en wordt wereldwijd bijzonder breed ingezet. Er dient steeds een onderscheid te worden gemaakt tussen REST API's die geconsumeerd worden in een server-naar-server context, i.e. REST API's die geconsumeerd worden in naam van de afnemertoepassing zélf enerzijds, en anderzijds REST API's die geconsumeerd worden namens een gebruiker die zich eerder via het Vlaams Toegangsbeheer (ACM) aanmeldde op de afnemertoepassing:

• Server-naar-server: in deze context geldt de OAuth Client Credentials Grant.

• Namens-een-gebruiker: in deze context geldt de OAuth Authorization Code Grant of de OAuth Token Exchange Grant

Wenst u één of meerdere van uw REST API's te integreren met het Vlaams Toegangsbeheer (ACM)? Elke entiteit van de Vlaamse Overheid, elk Vlaams lokaal bestuur en elke leverancier die bijdraagt tot de taakstelling van de Vlaamse Overheid, kan zo'n integratie volledig kosteloos afnemen van Digitaal Vlaanderen: er wordt geen aansluitingskost in rekening gebracht noch wordt er een recurrente operationele kost gefactureerd. U mag hiervoor te allen tijde contact opnemen met ons aansluitingsteam via integraties@vlaanderen.be. 

Hoe kan ik het Beheerportaal gebruiken om mijn REST API's te beheren?

Heeft u reeds één of meerdere REST API's van het server-naar-server type geïntegreerd met het Vlaams Toegangsbeheer (ACM)? Dan kan u uw API's en de clients die uw API mogen bevragen, volledig autonoom beheren in het Beheerportaal. Of dus; indien uw API geconsumeerd mag worden door een nieuwe client, kan u dit volledig autonoom inregelen in het Beheerportaal zonder dat hiervoor een tussenkomst van één van de analisten van het aansluitingsteam (integraties@vlaanderen.be) aan de orde is. De koppeling tussen uw API en de client wordt achterliggend volautomatisch verwerkt door het Vlaams Toegangsbeheer (ACM). Hieronder kan u een gebruikershandleiding op maat terugvinden:

Module OAuth Client Credentials Grant: API beheren

Hoe kan ik het Beheerportaal gebruiken om een geïntegreerde REST API te bevragen?

Beheert u één of meerdere toepassingen waarmee u een REST API van het server-naar-server type wenst te bevragen én is deze REST API geïntegreerd met het Vlaams Toegangsbeheer (ACM)? Dan kan u in het Beheerportaal volledig autonoom een aanvraag indienen om deze API te kunnen bevragen. Er is hiervoor geen tussenkomst nodig van één van de analisten van het aansluitingsteam (integraties@vlaanderen.be). De beheerder van de REST API die u wenst te bevragen, wordt via het Beheerportaal op de hoogte gebracht van uw aanvraag. Indien de beheerder uw aanvraag goedkeurt, wordt de koppeling tussen uw toepassing (client) en de API in kwestie volautomatisch verwerkt door het Vlaams Toegangsbeheer (ACM). Hieronder kan u een gebruikershandleiding op maat terugvinden:

Module OAuth Client Credentials Grant: API-Client beheren

Heeft u vragen bij het gebruik van het Beheerportaal?

• U mag bij vragen te allen tijde met ons contact opnemen via de 1700 - het gratis infonummer van de Vlaamse Overheid, voorheen bekend als de Vlaamse Infolijn. Onze ondersteuners helpen u via die weg graag verder met het beheer van uw API, of met uw aanvraag om een API die met het Vlaams Toegangsbeheer (ACM) geïntegreerd is, te mogen bevragen. 

• Raadpleegt u deze documentatie in het kader van de afbouw van GeoSecure? Heeft u in deze context specifieke vragen die uws inziens niet voldoende uitgebreid aan bod komen in deze handleiding? Neem gerust contact op met uitfaseringgeosecure@vlaanderen.be; onze collega's helpen jullie van daaruit met graagte verder! 

Op deze pagina: