Configuratie van de API

U klikte in het scherm "Mijn OAuth API's" op de naam van één van de API's waarvan u eigenaar dan wel editeerder of editeerder bent. In onderstaand voorbeeld gaan we zo bijvoorbeeld uit van de API "Vlaams Mandatensysteem T&IVoorbeeld API". U belandt op ziet onderstaand scherm op in het tabblad "Configuratie van de API":

Image Removed

Image Added

We lichten de verschillende schermcomponenten 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 de API

Gebruiksvriendelijke naam

Dit is de gebruiksvriendelijke naam van uw API. Als API-eigenaar of -editeerder kan u deze naam desgewenst later nog aanpassen.

Wij adviseren om steeds een naam te gebruiken waardoor u deze API gemakkelijk van uw andere API’s kan onderscheiden.

ClientID

Dit is de client ID ClientID van uw API. In een OAuth-context is deze client ID Dit is de 'publieke' identifier van uw API. Niettegenstaande deze identifier strikt genomen publiek is, is het aangewezen dat deze identifier niet zomaar raadbaar is; derhalve zal dit steeds een string zijn van 36 karakters. U kan deze client ID desgewenst kopiëren naar het klembord door op knop naast de client ID ClientID te klikken. Deze identifier wordt aangemaakt door het Toegangsbeheer-team (ACM-team); u kan deze voor uw API dus voor een goed begrip niet wijzigen. In bovenstaande screenshot werd hier een zwart kadertje overheen geplaatst.

Referentie

De naam die u hier opneemt, kan door clients gebruikt worden om een aanvraag in te dienen om te koppelen met deze API. U kan deze naam desgewenst aanpassen. In bovenstaande screenshot werd hier een zwart kadertje overheen geplaatst.uw API: beschouw dit als een soort gebruiksvriendelijke naam van uw API, een identifier die intuïtief en duidelijk is voor uw afnemers. Neem de Referentie van uw API zeker ook op in de documentatie voor uw eindgebruikers!

Resources

Deze resources zijn één of meerdere endpoints/URL's die uniek zijn binnen uw systeem. Een client kan bij de aanvraag van een access token, deze resource meegeven om aan te geven dat het over deze API gaat (als een alternatief op het meegeven van de client ID van uw API als audience).

Organisatie eigenaar

Hier worden de coördinaten opgenomen van de organisatie die eigenaar is van deze API. Deze coördinaten worden aangevuld door het Toegangsbeheer-team (ACM-team); u kan deze voor uw API dus voor een goed begrip niet wijzigen.

Communicatie email adres [NIEUW]

De eigenaar van een API is het primaire aanspreekpunt van de API. Als iemand 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 API 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 API 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 API, 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 API 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.

Toegelaten authenticatiemethodes voor de API (doc)

Dit zijn de authenticatiemethodes die uw API mag gebruiken bij de introspectie van access tokens bij het Toegangsbeheer (ACM). U kan de toegelaten authenticatiemethodes voor uw API hier desgewenst wijzigen.

JWKS endpoint (doc)

Indien u onder "Toegelaten authenticatiemethodes voor de API" (zie boven), "Publiek JWKS-endpoint" selecteerde, dient u hier de URL van het endpoint aan te vullen. Opgelet: deze URL dient aan een aantal voorwaarden te voldoen:

• 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 "Toegelaten authenticatiemethodes voor de API" (zie boven), "Publieke JWK" selecteerde, dient u hier de desbetreffende publieke sleutel (JWK) te documenteren. 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.

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 "Toegelaten authenticatiemethodes voor de API" (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.

Toegelaten authenticatiemethodes voor Clients (doc)

Net zoals uw API zich bij de introspectie moet authenticeren bij het Toegangsbeheer (ACM) (zie sectie "Toegelaten authenticatiemethodes voor de API"), dienen de clients van uw API zich via één van de ondersteunde methodes te authenticeren bij het Toegangsbeheer (ACM) wanneer zij uw API wensen te consumerenbevragen. U kan aan deze clients, als API-eigenaar, opleggen dat zij hiervoor één welbepaalde methode gebruiken, dan wel dat uw clients zich via elk van de ondersteunde methodes mogen authenticeren. U mag deze policy volledig autonoom opleggen.

Het gebruik van x5c bij publieke JWK's is vereist (doc)

Indien u onder "Toegelaten authenticatiemethodes voor Clients" (zie boven), "Publiek JWKS-endpoint" of "Publieke JWK" selecteerde, verschijnt er een extra kopje waarbij u, als API-eigenaar, kan opleggen dat de clients van uw API hun JWK-sleutel dienen te koppelen aan een x5c-certificaat. Dat zou betekenen dat wanneer de clients van uw API zich authenticeren bij het Toegangsbeheer (ACM), het Toegangsbeheer de geldigheid (tijdframe, revocation en CA) van dit x5c-certificaat zal controleren. 

Toelaten van nieuwe OAuth-Clients (die toegang vragen tot de API)

U kan hier voor uw API instellen of elke aanvraag van een client die uw API wenst te consumeren bevragen eerst moet goedgekeurd worden (zie OAuth-Clients die wachten op goedkeuring), dan wel dat elke aanvraag automatisch mag goedgekeurd worden.

Vertrouwde API gateways (doc)

U kan hier instellen of en welke API gateways namens uw API introspecties van de access tokens mogen doen. In bovenstaand voorbeeld werden de gekoppelde API gateways van deze API voor een goed begrip vervangen door "***". 

Scopes (doc)

Hier kan u een oplijsting terugvinden van de scopes die clients kunnen aanvragen bij het consumeren bevragen van uw API. U kan aangeven of deze scopes als 'default' mogen ingesteld worden, dan wel als 'preset':

• Default: default scopes wordt steeds aan uw API gevraagd, ook al vraagt de client deze niet expliciet op.

• Preset: preset scopes worden standaard aangevinkt voor nieuwe clients die uw API wensen te consumerenbevragen. 

  • Opgelet: de clients van uw API dienen deze preset scopes wel nog steeds expliciet toe te voegen aan hun requests om uw API via het Toegangsbeheer (ACM) te consumerenbevragen.

In bovenstaand voorbeeld werden de scopes van deze API voor een goed begrip vervangen door "***". 

Wanneer u klaar bent met de configuratie van API aan te passen, dient u deze aanpassingen steeds bekrachtigen door onderaan het scherm op "Wijzigen" te klikken. Indien u de aanpassingen niet wenst op te slaan, kan u steeds op "Annuleren" klikken.

Onderaan het scherm kan u desgewenst ook de "Meta gegevens" van uw API raadplegen: wie is in het Beheerportaal geregistreerd als eigenaar van deze API, aan welke organisatie is deze gebruiker gekoppeld, en wat is de status van deze gebruiker?