Scopes & claims

Bij het Authenticatie verzoek stuurt de Client de gewenste scopes mee en de ACM IDP voorziet de voorziene claims voor deze scope in het ID-token

Het gebruik van de scope “openid” bij het Authenticatie verzoek is verplicht voor een OpenID Connect authenticatie.

Welke scopes en claims aan een Client toegekend kunnen worden, kan zeer grannulair bepaald worden bij de ACM IDP. Welke specifieke scopes voor de Client mogelijk zijn, kan dus niet weergegeven worden in de Discovery URL die publieke info bevat voor alle Clients.

Tip

In het integratiedossier staat beschreven welke scopes er voor de Client toegelaten worden en welke claims men dan in het ID-token mag verwachten.

Het opvragen van een scope die niet toegestaan is voor deze Client zal ervoor zorgen dat het Authenticatie Request meteen negatief beantwoord zal worden (zonder dat de gebruiker zich dient te authenticeren in ACM).

Voorbeelden:

scope	claim	Omschrijving
openid	sub	PersoonsID van de gebruiker (= unieke identifier binnen ACM die deze gebruiker identificeert)
profile	given_name	voornaam van de gebruiker
profile	family_name	naam van de gebruiker
rrn	rrn	rijksregisternummer van de gebruiker
vo	vo_id	unieke VO IDM ID van de gebruiker
vo	vo_doelgroepcode	de code van de doelgroep (GID, EA, LB, OV, BUR, VER)
vo	vo_orgcode	de code van de gekozen organisatie (KBO-nummer, OVO-code, OV-instellingsnummer)
vo	vo_orgnaam	de naam van de gekozen organisatie
wettelijkvertegenwoordiger	wv_orgcode	gekozen organisatie als wettelijk vertegenwoordiger
mijntoepassing	mijntoepassing_rol_3d	WebIDM 3D-rol van de gebruiker voor deze toepassing
ssm_mandaat	ssm_mandaatgever	organisatiecode van de SSM-mandaatgever

login_hint

Indien je de scope login_hint opvraagt bij het authenticatierequest, dan zal je in het id-token (of in de UserInfo response) een extra claim ontvangen met als naam login_hint.

Deze login_hint claim geeft weer onder welke hoedanigheid de gebruiker werd aangemeld voor deze authenticatie (voor welke organisatie, als wettelijk vertegenwoordiger, als burger, …).

Deze login_hint dient als opaque waarde te worden behandeld: het is niet de bedoeling dat deze geïnterpreteerd wordt (er zijn immers plannen om het formaat ervan in sommige use cases te gaan wijzigen).

Deze login_hint claim is nuttig om mee te sturen naar andere toepassingen om in die toepassing meteen gericht te kunnen aanmelden onder dezelfde hoedanigheid en zo een single sign-on ervaring te bekomen. Meer informatie omtrent het gericht aanmelden kan u vinden op deze pagina.

Tip

Op dit ogenblik moet de scope login_hint nog expliciet aangevraagd worden in het integratiedossier. In een latere fase zal deze scope automatisch operationeel gemaakt worden voor alle OpenID Connect integraties.

setbyapi

Een API heeft de mogelijkheid om een claim te koppelen op een specifieke client. Wanneer de API een token, dat door die client werd aangevraagd, ontvangt zullen deze claims zichtbaar worden voor de API bij introspectie van dat token (zie valideer Access Token).

Deze claims zullen steeds beginnen met de naam setbyapi_ en zijn niet zichtbaar voor de client zelf. Het zijn dus als het ware claims van de client, die door de API werden gedefinieerd in het beheerportaal.

Tip

In migratie scenario’s waarbij een API de client_id van voor de migratie wenst te kennen, zou men deze kunnen koppelen in een attribuut setbyapi_legacy_client_id

API gateways

Deze attributen worden gekoppeld op de relatie tussen een API en zijn client. Het systeem herkent beide partijen aan de hand van de authenticatie op het introspection endpoint (= de API) enerzijds en de client waaraan het token werd afgeleverd (= de client) anderzijds.

In een scenario waarbij een API gateway gebruikt wordt, zal de API gateway echter de introspectie van het token uitvoeren en is het niet mogelijk om de relatie tussen de de client en de api niet langer te identificeren op basis van de authenticatie van op het introspection endpoint. Voor dergelijke usecases kan een API gateway een request header X-Forwarded-Audience toevoegen met als waarde de client_id van de API of een resource_uri die aan de API werd gekoppeld.