Wat moet ik doen om een client in een klantenorganisatie aan te maken?

Welke stappen je moet ondernemen, hangt af of je organisatie en je klantorganisatie al gekend is in het Gebruikersbeheer Vlaanderen (IDM) of niet en of je al dan niet over de juiste rechten beschikt.

Tip
Doorloop onderstaande stappen eerst in de test-omgeving voordat je de aansluiting op de productie-omgeving inregelt. Alleen zo ben je zeker dat je opzet effectief werkt.

Uitgangssituatie

1. Je eigen organisatie is gekend in het Gebruikersbeheer Vlaanderen, zowel in de Productie-omgeving (PROD) als in de Test-omgeving (BETA). Is dit niet het geval?

   1. Is je organisatie geregistreerd in België, kijk dan hier hoe je je organisatie kan (laten) registreren.

   2. Is je organisatie een buitenlandse onderneming, neem dan contact op met 1700

      1. Bel 1700, elke werkdag van 9 tot 19 uur.

         Bellen vanuit het buitenland kan ook, maar is niet gratis: gebruik hiervoor het betalende nummer +32 2 553 1700.

      2. Mail naar veiligheidsbouwstenen@vlaanderen.be

2. Je heb het recht API Beheerder.

   1. Is dit niet het geval? Vraag dit dan aan via je lokale toegangsbeheerder. Dit kan via volgende linken:

      1. Entiteit van de Vlaamse Overheid: 

         1. Zelfregistratielink (PROD) 

         2.  Zelfregistratielink (BETA)

      2. Economische Actor: 

         1. Zelfregistratielink (PROD)

         2. Zelfregistratielink (BETA)

      3. Lokaal Bestuur:

         1.  Zelfregistratielink (PROD)

         2. Zelfregistratielink (BETA)

3. Je klantorganisatie is gekend in het Gebruikersbeheer Vlaanderen. Is dit niet het geval?

   1. Is je klant geregistreerd in België, vraag dan een wettelijk vertegenwoordiger van je klant om dit in orde te brengen.
      Deze wettelijk vertegenwoordigers kan je vinden via de public search van de KBO, onder het item ‘Functiehouders’.

   2. Is je klant een buitenlandse onderneming, neem dan contact op met 1700 (zie hoger).

4. Binnen je klantorganisatie is er een gebruiker met het recht van API-Beheerder.

   1. Is dit niet het geval? Laat dan je contactpersoon bij je klant dit recht voor zichzelf aanvragen via 1 van de volgende linken:

      1. Entiteit van de Vlaamse Overheid: 

         1. Zelfregistratielink (PROD)

         2. Zelfregistratielink (BETA)

      2. Economische Actor: 

         1. Zelfregistratielink (PROD)

         2. Zelfregistratielink (BETA)

      3. Lokaal Bestuur: 

         1. Zelfregistratielink (PROD) 

         2. ​​​​​​​Zelfregistratielink (BETA)

   2. Weet je niet of dit het geval is? Speel dan op zeker en laat je contactpersoon de nodige rechten aanvragen.

Stappenplan

Tip
Een algemene handleiding voor het Beheerportaal vind je op de desbetreffende helppagina van Toegangsbeheer Vlaanderen.

Stap 1: Instellen toegang tot Beheerportaal [Eenmalig]

Dit is in principe een eenmalige actie. Eens je rechten hebt voor je organisatie, moet je dit niet opnieuw doen.

Om toegang te hebben tot het Beheerportaal (en de juiste module “API- en Clientbeheer”) moet je binnen je organisatie over het gebruikersrecht “API-beheerder” beschikken in de het Gebruikersbeheer van de Vlaamse overheid (IDM).

Pas nadat je het recht “API-beheerder” hebt kan je de overige stappen in deze handleiding uitvoeren.

Stap 2: Aanmaken client

Maak een clientID aan in het ACM beheerportaal. Hierna is het de bedoeling dat zowel KLIP als je klant deze client goedkeuren.
De test-omgeving van het beheerportaal is beschikbaar via https://beheerportaal-ti.vlaanderen.be, de productie-omgeving via https://beheerportaal.vlaanderen.be.

1. Meld aan met een digitale sleutel naar keuze. Indien je rechten hebt voor meerdere organisaties, zal je ook moeten kiezen voor welke organisatie je wil aanmelden.

2. Als het de eerste keer is dat je aanmeldt in het Beheerportaal ga je initieel weinig informatie zien staan op het Startscherm. Klik op onder “Uw Bouwstenen” op “Toegangsbeheer”.

3. Je krijgt een overzicht van beschikbare componenten binnen de bouwsteen Toegangsbeheer. Klik op “API- en Clientbeheer”

4. Je bevindt je op een overzicht van je bestaande OAuth-Clients (verspreid over 3 tabbladden). Klik op “Nieuwe OAuth Client aanmaken”

5. Vul de nodige gegevens in

   1. Geef een gebruiksvriendelijke naam aan de Client.
      Dit is de naam die in de logging van het KLIP-platform te zien zal zijn.

   2. Kies bij “Organisatie eigenaar” voor de optie “Namens een externe organisatie (delegatie)”

   3. Geef de unieke identifier in van de organisatie namens dewelke je een Client wil aanmaken

      1. Voor ondernemingen: gebruik het KBO-nummer (zonder punten)
         Je kan de KBO-nummers opzoeken via de publieke zoekfunctie van het KBO.

      2. Voor lokale besturen: gebruik het KBO-nummer (zonder punten)
         Je kan de KBO-nummers opzoeken via de publieke zoekfunctie van het KBO.

      3. Voor Vlaamse overheidsorganisaties: gebruik de OVO-code
         Je kan de OVO-nummers opzoeken via wegwijs.vlaanderen.be.

      4. Voor buitenlandse ondernemingen: neem contact op met 1700.

   4. Vink aan dat je editeerrechten wil voor deze Client. Dit gaat ervoor zorgen dat jij als dienstverlener achteraf deze Client kan gebruiken en beheren (in naam van je klant).

   5. Kies voor “Publieke JWK” (JSON Web Key) als authenticatiemethode en copy paste je publieke JWK (enkel het publieke deel van de sleutel, niet het private deel) in het venster. Indien gewenst kan je meerdere JWK’s toevoegen door op “nieuw toevoegen” te klikken.

      1. Tip: het Beheerportaal bevat ook een pagina waarop je zelf een JWK kan genereren.

   6. Klik op “Koppelen aan een nieuwe OAuth API”.

   7. Geef de referentie in van de KLIP-API ("dv-klip-api") en klik op “Vraag aan”.
      Je krijgt een bevestiging dat de koppeling is aangevraagd. Ga terug naar het aanmaakscherm via het kruisje.

6. Alle noodzakelijke velden zijn ingevuld. Klik op “Aanmaken” om het aanmaakproces te voltooien. Je Client wordt aangemaakt en staat nu onder de Clients “In beheer voor andere organisaties”. De status is “Actief”, maar je hebt nog “1 wachtende API” (je koppeling met de KLIP API wacht namelijk nog op goedkeuring)

Stap 3: Wijzigen permissies Client [Optioneel]

Als je wilt dat andere personen de Client ook kunnen bewerken, moet je hen editeer-rechten geven op het ACM Beheerportaal.

1. In het overzicht van “Mijn OAuth Clients” (tabblad “In beheer voor andere organisaties”), klik voor de gewenste Client op “Permissies wijzigen”

2. Je krijgt een overzicht van de personen die gekend zijn als API-beheerder (zowel binnen je eigen organisatie als binnen andere organisaties). Klik voor de gewenste persoon de checkbox “Editeer” aan. In principe is dit een persoon binnen je eigen organisatie. 

3. Klik helemaal onderaan op “Wijzigen” om de wijzigingen in permissies effectief door te voeren.

Stap 4a: Laat de client goedkeuren door je klant

Stappen 4a en 4b moeten beide gebeurd zijn voor je de client kan gebruiken. De volgorde waarin ze gebeuren maakt niet uit.

Omdat je als dienstverlener in delegatie werkt van een bepaalde klant, moet de klant ook zijn expliciet akkoord geven voor deze delegatie op het ACM Beheerportaal.

1. Hiervoor moet hij ook toegang hebben tot het portaal via het Gebruikersbeheer van de Vlaamse overheid (IDM).

2. Hij meldt zich aan op het portaal en naar het tabblad Delegaties gaan. Daar kan hij jouw aanvraag zien en goedkeuren of afwijzen.

3. Als hij je aanvraag goedkeurt, zal er een groen vinkje verschijnen naast de naam van de Client op de detailpagina. 

Stap 4b: KLIP keurt je client goed

Nadat je een nieuwe Client hebt aangemaakt, zal de KLIP-Product Owner je toegangsaanvraag goedkeuren op het ACM Beheerportaal.

Dit is een extra beveiligingsmaatregel om ervoor te zorgen dat alleen geautoriseerde partijen toegang krijgen tot de API. Je kan de status van je aanvraag zien op de detailpagina van de Client onder het tabblad API’s. Als je aanvraag is goedgekeurd, zal er een groen vinkje verschijnen naast de naam van de API.

Stap 5: Test connectie met de KLIP-API

Test of je met deze Client een token kan opvragen en de KLIP-API kan bereiken zoals voorheen.

Pas de configuratie of code van je toepassing aan zodat die voortaan OAuth-tokens bij ACM kan komen opvragen in plaats van bij Geosecure. Maak hiervoor gebruik van het client credentials grant type, waarbij je toepassing zich identificeert met behulp van het JWK dat je hebt ingesteld.  

1. Je vraagt het token op via https://authenticatie.vlaanderen.be/op/v1/token.

2. Geef volgende parameters mee: grant_type=client_credentials en API-specifieke scopes (elke scope gescheiden door een spatie) onder de vorm van scope=<naam van de eerste scope> <naam van de tweede scope>.

3. Gebruik JWK om een JWT te genereren en die geef die mee als header met de naam client_assertion.

4. Als alles goed gaat, zal je een token ontvangen dat je kan gebruiken om de API aan te roepen. 

5. Als de test geslaagd is, kan je ervoor kiezen om definitief over te schakelen naar de nieuwe Client.

6. Je bent daarna klaar met de migratie voor deze Client.