DRAFT

1. Introductie

1.1 Doelstelling van deze pagina

Deze pagina beschrijft welke acties klanten (of hun dienstverleners) moeten zetten om zelf een OAuth-Client aan te vragen voor de connectie met de webservices van het Vastgoedintegratieplatform (VIP). Dit proces loopt via het Beheerportaal van het Toegangsbeheer (ACM), een online webtoepassing waar medewerkers van organisaties zelf OAuth-Clients kunnen aanmaken en beheren voor de connecties met API’s van de Vlaamse overheid (die werken met het Toegangsbeheer als Identity Provider).

Naast het Beheerportaal is er ook nog een werkwijze om via een API geautomatiseerd Clients voor de VIP-API aan te maken. Deze werkwijze is buiten scope van deze Confluence-pagina.

1.2 Wat is het Beheerportaal?

Het Beheerportaal is een online webtoepassing van het Toegangsbeheer van de Vlaamse overheid (ACM) die als doel heeft om zoveel mogelijk interacties van klanten met het Toegangsbeheer in selfservice door de klant (of hun dienstverlener) te laten doen. Op termijn willen we zoveel mogelijk componenten van onze dienstverlening (REST-API’s, SOAP-API’s, OpenID Connect-aansluitingen, SAML-aansluitingen, enz.) via dit portaal laten verlopen. Het Beheerportaal moet de doorlooptijd van aansluitingen (b.v. voor het VIP-platform) drastisch verkorten en de zelfredzaamheid van klanten verhogen.

Het Beheerportaal is een gloednieuwe toepassing. Het OAuth-beheer en het VIP-platform zijn onze piloten voor dit project. Vooral op het vlak van User Interface en typische Quality of Life-functionaliteiten is er nog verbetering mogelijk. Feedback of suggesties mogen jullie altijd bezorgen aan sammy.roos@vlaanderen.be.

1.3 Twee verschillende scenario’s…

In de onderstaande handleiding maken we we onderscheid tussen 2 scenario’s:

Scenario 1: een klant maakt zelf een OAuth-Client aan voor de eigen organisatie

In dit scenario is het dus de klant zelf die volledig alle handelingen doet. Er is geen dienstverlener in het proces betrokken.

Bijvoorbeeld: een entiteit van de Vlaamse overheid of een lokaal bestuur vraagt volledig zelfstandig een Client aan voor de VIP-API.

Scenario 2: een dienstverlener maakt een OAuth-Client aan namens een andere organisatie (haar klant)

In dit scenario ligt de lead volledig bij de dienstverlener. Het is de dienstverlener die de Client zal aanmaken “namens” haar klant. De klant zal enkel eenmalig een goedkeuring moeten geven voor de creatie van de Client (in haar naam).

Bijvoorbeeld: Stad Oudenaarde vraagt aan dienstverlener X om in haar naam een Client aan te vragen voor de VIP-API.

1.4 … in twee verschillende omgevingen

We maken ook een onderscheid tussen 2 verschillende omgevingen, waar de werkwijze (in het bijzonder voor scenario 2) ietwat anders is:

Aanmaken van een Client in de T&I-omgeving (testomgeving)

In de testomgeving gebruiken we een vereenvoudigd proces voor scenario 2 (waar geen aparte goedkeuring nodig is van de klant). In beide scenario’s gebeurt ook het instellen van toegang tot het Beheerportaal volgens een vereenvoudigde procedure.

Aanmaken van een Client in PRD-omgeving (productieomgeving)

In de productieomgeving gebruiken we het volledige proces voor scenario 2 (waar wél een aparte goedkeuring nodig is van de klant). In beide scenario’s gebeurt ook het instellen van toegang tot het Beheerportaal volgens de officiële procedure.

2. Beschrijving van het proces in T&I

2.1 Scenario 1: Klant maakt zelf Client voor de eigen organisatie (T&I)

2.1.1 Overzicht

2.1.2 Acties voor de klant

Instellen toegang tot Beheerportaal [Eenmalig]

Aanvullen

Aanmaken Client

Ga naar het Beheerportaal in T&I
Meld aan met een digitale sleutel naar keuze. Indien je rechten hebt voor meerdere organisaties, ga je ook moeten kiezen voor welke organisatie je wil aanmelden.
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”

Enkel bij de eerste keer aanmelden moet je deze weg volgen. Vanaf de volgende keer ga je rechtstreeks een “recente component” of een “favoriet” kunnen openen vanop het Startscherm, wat veel snellere navigatie is.

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

Je krijgt een overzicht van beschikbare acties binnen de component “API- en Clientbeheer”. Klik op “Mijn OAuth-Clients”

TIP: je kan binnen het Beheerportaal bepaalde pagina’s als “Favoriet” in te stellen (via de slider aan de rechtzijde in b.v. bovenstaande screenshot). Hierdoor gaat de pagina in kwestie onderaan je Startpagina als favoriet staan zodat je veel sneller naar deze pagina kan navigeren in de toekomst. Je kan dit b.v. doen met “Mijn OAuth Clients”, maar ook met een pagina van een specifieke Client of API.

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

Vul de verplichte gegevens in:
- Geef een gebruiksvriendelijke naam aan de Client. Dit is de naam die in de logging van het VIP-platform te zien zal zijn.
- Duidt de organisatie aan die eigenaar is van de Client. In dit scenario mag je je eigen organisatie gewoon laten staan.
- Selecteer een persoon als eigenaar van de Client. Je kan kiezen uit alle personen die “API-beheerder” zijn voor jouw organisatie.

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.

Klik op “Koppelen aan een nieuwe OAuth API”.

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

Alle noodzakelijke velden zijn ingevuld. Klik op “Aanmaken” om het aanmaakproces te voltooien. Je Client wordt aangemaakt en staat nu onder de Clients “Voor eigen organisatie”

Wijzigen permissies Client [Optioneel]

Dit is een optionele stap. Als de persoon die de Client heeft aangemaakt in de vorige stap de enige persoon is die de Client moet kunnen zien/beheren, mag je deze stap overslaan.

Testen connectie met VIP API

Nadat de VIP-beheerder de Client heeft goedgekeurd (zie hieronder: Goedkeuren Client), kan je de Client onmiddellijk gebruiken om een Access Token aan te vragen en de VIP API aan te spreken.

2.1.3 Acties voor de VIP-beheerder

Instellen toegang tot Beheerportaal [Eenmalig]

Goedkeuren Client

2.2 Scenario 2: Dienstverlener maakt Client namens een andere organisatie (T&I)

2.2.1 Overzicht