Nieuwe OAuth client

U klikte in het startscherm onder "Uw Bouwstenen" op "Toegangsbeheer", vervolgens op "API- en Clientbeheer", en nadien op "Mijn OAuth Clients". In onderstaand scherm klikte u op de knop "Nieuwe OAuth client aanmaken" om een nieuwe client aan te maken voor uw organisatie waarmee u een API van de Vlaamse Overheid kan bevragen:

Open

U ziet dit scherm:

Open

We lichten de verschillende velden hieronder graag even toe. Als u technische vragen heeft bij één van deze componenten - of algemene vragen bij de OAuth Client Credentials Grant - kan u desgewenst steeds de algemene documentatie van het Toegangsbeheer (ACM) raadplegen. Per component wordt in onderstaande bovendien gerefereerd aan het specifieke documentatie-luikje ("doc").

Overzicht specificaties van een nieuwe client

Gebruiksvriendelijke naam

Dit is de gebruiksvriendelijke naam van uw client. Als client-eigenaar of -editeerder kan u deze naam desgewenst later nog aanpassen. Wij adviseren om een naam te kiezen waardoor u deze nieuwe client gemakkelijk van uw andere clients kan onderscheiden.

Organisatie eigenaar

Standaard worden hier de coördinaten opgenomen van de organisatie namens de welke u aangemeld bent op het Beheerportaal.

Opgelet: u kan ook een nieuwe client aanmaken voor een andere organisatie. Dat is een afspraak die bijvoorbeeld vaak gemaakt wordt tussen lokale besturen en hun dienstenleveranciers: de leverancier wordt belast met het aanmaken van de client, maar de client is wel eigendom van het bestuur. U kan deze optie lichten door hier in de listbox “Namens een externe organisatie (delegatie)” aan te klikken. Er verschijnen vervolgens twee extra rubriekjes: "Externe organisatie" (zie onder) en “Rechten” (zie onder). Indien u als leverancier dit pad bewandelt, zal u het bestuur zélf (bvb. Stad Zottegem) aanduiden als eigenaar van de client. De medewerker van het bestuur die de rechtmatige eigenaar is van de client, zal dan in een volgende fase zelf het eigenaarschap moeten claimen in het Beheerportaal. Meer informatie omtrent het claimen van een client, kan men terugvinden op deze pagina.

Externe organisatie

Indien u onder "Organisatie eigenaar" (zie boven), "Namens een externe organisatie (delegatie)" selecteerde, dient u in deze listbox de code van de externe organisatie op te nemen waarvoor u de client in kwestie wenst aan te vragen.

• Indien de externe organisatie een agentschap of departement van de Vlaamse Overheid is, voert u de OVO-code van het agentschap of departement in. U kan OVO-codes terugvinden via het Organisatieregister.

• Indien de externe organisatie een onderneming is, voert u het KBO-nummer van de onderneming in. U kan KBO-nummers terugvinden via de KBO Public Search. Gelieve het KBO-nummer in dit veld in te voeren zonder “BE”-prefix en zonder punten.

• Indien de externe organisatie een lokaal bestuur is, voert u het KBO-nummer van het bestuur in - niét de OVO-code. U kan KBO-nummers terugvinden via de KBO Public Search. Gelieve het KBO-nummer in dit veld in te voeren zonder “BE”-prefix en zonder punten.

Rechten [NIEUW]

Indien u onder "Organisatie eigenaar" (zie boven), "Namens een externe organisatie (delegatie)" selecteerde, kan u in deze checkbox aangeven of u zelf al dan geen editeer-rechten wenst voor deze client. Editeerders kunnen dezelfde operationele beheerstaken voor hun rekening nemen als de rechtmatige eigenaars van de client, maar zijn geen aanspreekpunt. Editeerders ontvangen derhalve geen updates of bevestigingsmailtjes uit het Beheerportaal; eigenaars wél. Meer informatie omtrent eigenaar- en editeer-rechten, kan u terugvinden op deze pagina.

Selecteer een eigenaar

Indien u onder “Organisatie eigenaar” (zie boven) gewoon uw eigen organisatie selecteerde, kan u hier instellen wie de eigenaar van deze nieuwe client mag gaan worden. Standaard zal uw naam hier verschijnen, maar u kan desgewenst ook een andere persoon binnen uw organisatie aanduiden als toekomstige eigenaar van deze nieuwe client. Aan elke client dient exact één eigenaar te worden toegewezen. Meer informatie omtrent dit eigenaarschap, kan u op deze pagina terugvinden.

Opgelet: als u de listbox openklikt, zal u enkel die medewerkers van uw organisatie zien staan die in het Gebruikersbeheer (IDM) geregistreerd zijn als “API-beheerder en Client-beheerder” binnen uw organisatie. Hoe die registratie precies plaatsvindt, kan u op deze pagina terugvinden.

Communicatie email adres [NIEUW]

De eigenaar van een client is het primaire aanspreekpunt van deze client. Als u een aanvraag indient om met uw client in te tekenen op een API van de Vlaamse Overheid (zie onder), zal de eigenaar van de API uw aanvraag goed- of afkeuren. De eigenaar van de client wordt daarvan op zijn/haar beurt via mail op de hoogte gebracht.

Het kan natuurlijk dat de eigenaar van de client op dat moment met verlof of afwezig is. Opdat de communicatie toch tot bij de juiste personen zou terecht komen, kan u hier in dit veld een e-mailadres toevoegen dat ook alle toekomstige communicatie omtrent deze client zal ontvangen. Dat mag een generiek e-mailadres zijn (bvb. info@gemeenteabc.be), of het adres van een (externe) collega.

Stuur eigenaar een email bij belangrijke wijzigingen [NIEUW]

Als een editeerder een (belangrijke) wijziging aanbrengt aan een client, kan het wenselijk zijn dat de eigenaar daarvan via mail verwittigd wordt - denk bijvoorbeeld aan het vervangen van een JWK (zie onder). Dat zal standaard ook het geval zijn, tenzij u de slider hier naar links schuift. Meer informatie omtrent eigenaar- en editeer-rechten, kan u terugvinden op deze pagina.

Wie kan de eigenaar van deze Client wijzigen? [NIEUW]

Als de eigenaar op het punt staat om de organisatie te verlaten of zijn/haar takenpakket binnen de organisatie wijzigt, is het zonder meer aangewezen dat er een nieuwe eigenaar aangesteld wordt. De eigenaar kan dat steeds zelf doen, maar deze taak kan ook gedelegeerd worden naar één van de medewerkers van de organisatie die in het Gebruikersbeheer (IDM) geregistreerd is als “Lokale Beheerder”.

Deze delegatie wordt in twee flavours aangeboden:

• De “Lokale Beheerder” mag standaard een nieuwe eigenaar aanduiden in het Beheerportaal.

  • Dit is de aanbevolen setting.

• De “Lokale Beheerder” dient eerst als editeerder te worden toegevoegd door de eigenaar van de client. Eenmaal hij/zij toegevoegd is, kan hij/zij een nieuwe eigenaar aanduiden.

  • Dit is niet de aanbevolen setting: als de eigenaar de organisatie op dat moment namelijk reeds verlaten heeft, ontstaat hier namelijk het risico dat de Lokale Beheerder niet meer kan toegevoegd worden als editeerder. Een tussenkomst van de helpdesk van Digitaal Vlaanderen is dan noodzakelijk.

Authenticatie (doc)

Wanneer u met uw client een API zal gaan bevragen, dient uw client zich via één (of meerdere) van de ondersteunde methodes te authenticeren bij het Toegangsbeheer (ACM). U bent niet noodzakelijk verplicht om hier dadelijk een keuze te maken, en u kan de toegelaten authenticatiemethode(s) voor uw client desgewenst later desgewenst wijzigen.

JWKS endpoint (doc)

Indien u onder "Authenticatie" (zie boven), "Publiek JWKS-endpoint" selecteerde, dient u hier de URL van het endpoint aan te vullen. Opgelet: deze vorm van authenticatie vereist, in tegenstelling tot de andere methodes, wel een (kleine) controle en configuratie-aanpassing van het ACM-team - het team dat het Beheerportaal ontwikkeld heeft en onderhoudt. Zodra u uw client aangemaakt heeft (zie onder), ontvangt het ACM-team een automatisch mailtje dat binnen één werkdag wordt opgenomen en uitgevoerd.

Gelieve op voorhand zelf te controleren dat het endpoint dat u hier ingeeft, aan volgende voorwaarden voldoet:

• De URL moet pubiek beschikbaar zijn en luisteren op HTTPS.

• Er moet vanzelfsprekend een geldig server certificaat aanwezig zijn en geïssued worden door een publieke Certificate Authority of VO DCBaaS.

• De URL moet luisteren op de standaard HTTPS-poort (443).

• De nodige caching headers zouden gezet moeten worden zodat afnemers weten hoe lang de JWK’s gecached mogen worden.

• De beschikbaarheid van dit JWKS endpoint is cruciaal voor de correcte werking van de authenticaties.

Publieke JWK (doc)

Indien u onder "Authenticatie" (zie boven), "Publieke JWK" selecteerde, dient u hier de desbetreffende publieke sleutel (JWK) toe te voegen. Opgelet: deze sleutel dient aan een aantal voorwaarden te voldoen:

• We verwachten hier een publieke sleutel uit een asymmetrisch keypaar (symmetrische keys bieden immers geen meerwaarde t.o.v. de client/secret die ook gebruikt kan worden).

• Gelieve er steeds op te letten dat enkel het publieke deel doorgestuurd wordt: als er een private key meegestuurd wordt, dan dient dit keypaar als gecompromitteerd beschouwd te worden.

• Als key-type (kty) kan er gekozen worden voor RSA (aanbevolen) of voor EC (Elliptic Curve).

• Als algoritme (alg) zijn er meerdere opties mogelijk, waaronder:

  • RS256 RSASSA-PKCS1-v1_5 met SHA-256 (aanbevolen)

  • RS384 RSASSA-PKCS1-v1_5 met SHA-384

  • RS512 RSASSA-PKCS1-v1_5 met SHA-512

  • P-256 and SHA-256 (voor EC)

  • P-384 and SHA-384 (voor EC)

  • P-521 and SHA-512 (voor EC)

• De key-grootte moet minimaal 2048 bytes zijn.

  • Een key-grootte van 4096 bytes is aanbevolen.

• Meer info is terug te vinden in RFC7517.

• Een publieke sleutel (JWK) bevat een unieke ID, namelijk de “KID”. Aan een client kan slechts een specifieke “KID” éénmaal gekoppeld worden. Het is dus niet mogelijk om twee publieke sleutels (JWK) met dezelfde “KID” te koppelen aan één client. Indien een publieke sleutel (JWK) van een client dient vernieuwd te worden dan moet de oude publieke sleutel (JWK) eerst verwijderd te worden van de client voordat de nieuwe publieke sleutel (JWK) kan toegevoegd worden.

Merk tenslotte ook op dat het algoritme HS256 niet aanvaard wordt. Bij dit algoritme wordt namelijk symmetrische encryptie gebruikt en zou de public key als secret gebruikt worden.

Client/Secret (doc)

Indien u onder "Authenticaties" (zie boven), "Client/Secret (minst veilige optie)" selecteerde, kan u hier uw client secret kopiëren - of eventueel wijzigen indien uw vorige client secret werd gecompromitteerd. Merk op dat uw client secret strikt confidentieel behandeld dient te worden en onder geen beding gedeeld mag worden met derden. Authenticatie middels client ID en client secret wordt steeds als de minst veilige authenticatiemethode beschouwd.

OAuth API's waartoe deze Client toegang heeft

Hier kan u aangeven welke API('s) u met deze client wenst te bevragen. Merk op dat clients die niet binnen de maand gekoppeld worden op minstens één API, automatisch verwijderd worden in het Beheerportaal. U geeft dan ook best meteen mee met welke API('s) u uw client wenst te koppelen. Dat kan door de knop "Koppelen aan een nieuwe OAuth API (op basis van ClientID of referentie)" aan te klikken:

In bovenstaand zoekvenster kan u dan, op basis van minimum 3 karakters, ingeven met welke API u uw client wenst te integreren. Dat kan op basis van de ClientID van de API, of op basis van de referentie:

• ClientID: in een OAuth-context is deze client ID de 'publieke' identifier van de API in kwestie. 

  • Indien u de client ID van de API niet kent, zoekt u best op basis van de referentie.

• Referentie: API-eigenaars zullen aan hun API's steeds een referentie meegeven - een soort gebruiksvriendelijke naam.

  • Indien u de referentie van de API niet kent, neemt u best contact op met de eigenaar van de API die u wenst te bevragen. De eigenaar van de API dient zowel de ClientID als de referentie van zijn/haar API’s op te nemen in de documentatie.

Indien u de ClientID en/of referentie van de API wél kent, kan u deze API in bovenstaande listbox selecteren, en vervolgens op "Vraag aan" klikken: op deze manier lanceert u effectief een aanvraag richting de eigenaar van deze API om deze met uw client te kunnen bevragen. De API-eigenaar wordt voor een goed begrip vanuit het Beheerportaal via mail verwittigd op het moment dat u de aanvraag indient. Dat mailtje gaat steeds uit van het generieke adres beheerportaal-noreply@vlaanderen.be, en zal er als volgt uitzien:

In het bericht zijn uw coördinaten en de coördinaten van uw client opgenomen, alsook de details van de API waarop uw aanvraag betrekking heeft. Voorts wordt een linkje meegegeven via de welke de API-eigenaar uw aanvraag kan goed- of afkeuren.

Zodra de API-eigenaar uw aanvraag effectief behandeld heeft in het Beheerportaal, zal u hier op uw beurt via mail van verwittigd worden. Dat mailtje gaat eveneens uit van het generieke adres beheerportaal-noreply@vlaanderen.be, en zal er als volgt uitzien indien uw aanvraag werd goedgekeurd:

Eenmaal goedgekeurd, dient u geen verdere actie te nemen in het Beheerportaal: de koppeling is geslaagd.

Custom client attributen (doc)

Onder "Custom client attributen" kan u desgewenst één of meerdere gecustomiseerde attributen toevoegen aan uw client. Opgelet: alle custom attributen worden geprefixed met 'setbyclient_'. Het is absoluut niet verplicht om custom client attributen te definiëren. Informeer bij de eigenaar van de API die u wenst te bevragen, of u hier een attribuut dient toe te voegen; normaal gezien is dat geen verplichting. Als dat wel het geval zou zijn, moet de eigenaar van de API dit zeker opgenomen hebben in zijn documentatie.

Ter illustratie:

Klik steeds op het plus-teken om het custom attribuut te bewaren en toe te voegen aan uw client.

Aanmaken

Onderaan het scherm klikt u tenslotte op "Aanmaken" om uw client aan te maken, of op "Annuleren" als u deze client wenst te schrappen.

Op deze pagina: