Technische info
Flow
De ACM IDP biedt enkel ondersteuning voor de “Authorization Code Flow”: dit is de veiligste en meest gebruikte OpenID Connect flow.
Discovery URL
De Discovery-URL bevat de concrete URL’s van de specifieke endpoints van de OpenID Connect Provider, alsook de ondersteunde technologieën.
- voor test: https://authenticatie-ti.vlaanderen.be/op/.well-known/openid-configuration
- voor productie: https://authenticatie.vlaanderen.be/op/.well-known/openid-configuration
Implementaties die ondersteuning bieden voor het discovery endpoint kunnen volgende “issuer” gebruiken:
- voor test:
https://authenticatie-ti.vlaanderen.be/op - voor productie:
https://authenticatie.vlaanderen.be/op
Zorg er wel voor dat uw software het Userinfo Endpoint (dat in de discovery URL vermeld staat) niet gebruikt indien uw use case dit niet nodig heeft !
Keys
De keys van de ACM IDP roteren automatisch: zorg er dus voor dat je deze niet gewoon éénmalig bij de configuratie opslaat.
Om de efficiëntie te verhogen wordt er aangeraden om deze keys te cachen, maar daarbij moet de cache-control max-age zeker gerespecteerd worden: deze geeft aan hoeveel seconden deze pagina maximaal gecached mag worden. Gelieve de keys zeker niet langer dan 6 uur te cachen.
ID-token
Na een succesvolle authenticatie bezorgt de OpenID Connect Provider een ID-token aan de Client, hetgeen een JWT is met daarin claims betreffende de identiteit van de gebruiker.
Bij ontvangst van een ID-token MOET de Client de nodige validaties uitvoeren, waaronder:
- De Client moet de signature van het ID-token valideren (cfr. JWS-validatie) waarbij het algoritme gebruikt wordt dat in de JWT als Header Parameter meegestuurd wordt. De Client dient de keys te gebruiken die door de Issuer worden aangeboden (cfr. de keys). De validatie van de TLS-sessie om het Token Endpoint te gebruiken mag volgens de standaard ook gebruikt worden ter validatie van de Issuer (ipv de signature van het ID-token)
- de Client valideert dat de “iss"-claim (issuer) wel degelijk die van de OpenID Connect Provider is: zie de uitleg omtrent de Discovery URL voor de concrete waarde voor de ACM IDP
- de Client dient te valideren dat zijn eigen ClientID vermeld staat in de “aud"-claim (audience): deze claim kan een array zijn met daarin meerdere waarden
- de huidige tijd mag zeker niet na de expiry time liggen, dat vermeld wordt in de “exp"-claim (expiry time)
- het verschil tussen de “iat"-claim (issued at) en de huidige tijd mag niet te groot zijn (het mag dus niet te lang geleden zijn dat het ID-token geïssued werd): de Client mag bepalen welke waarde aanvaardbaar is
- indien er bij het Authenticatie Request een nonce-waarde meegestuurd werd, dan MOET er in het ID-token een “nonce"-claim aanwezig zijn met exact dezelfde waarde als in het Authenticatie Request
- als er een acr-claim gevraagd werd, dan moet de Client valideren dat de waarde van de “acr"-claim geldig is
Scopes & claims
In het integratiedossier staat beschreven welke scopes er voor de Client toegelaten worden en welke claims men dan in het ID-token mag verwachten.
Voor een OpenID Connect integratie dient de scope “openid” meegegeven te worden.
Aanmelden
Het aanmeld-proces wordt op deze link uitvoerig beschreven.
Tip
Het gebruik van een “nonce” wordt sterk aanbevolen: deze mitigeert potentiële replay attacksTip
Het gebruik van een “state” wordt sterk aanbevolen: deze kan CSRF aanvallen mitigerenClient Authenticatie
Voor de authenticatie van de Client bij het Token Endpoint worden verschillende mogelijkheden aangeboden:
- Client authenticatie op basis van ClientID en Secret
- ClientID en Secret via POST-parameters
- ClientID en Secret via Basic Authentication
- Client authenticatie via een JWT token
Tip
Client authenticatie via een JWT token is de veiligste optie en geniet de voorkeur.
In het integratiedossier kan aangegeven worden of Client/Secret en/of JWT-token toegestaan zijn voor de specifieke Client.
Afmelden
Een toepassing kan (na het afmelden binnen de eigen toepassing) de sessie op de ACM IDP beëindigen door te redirecten naar het End Session Endpoint.
Optioneel kunnen er een ClientID en een post-logout URI meegestuurd worden, waardoor er naar een specifieke pagina geredirect kan worden na het afmelden. Deze post-logout URL dient op voorhand geregistreerd te worden. Gelieve alle vereiste post-logout URI’s te documenteren in het integratiedossier.
Gericht aanmelden
De toepassing kan meegeven onder welke identiteit (als welke doelgroep of organisatie) de gebruiker wenst aan te melden. Indien dit een geldige keuze is, dan zal de gebruiker transparant en zonder interactie voor de keuze van de identiteit aangemeld worden.
De identiteit wordt weergegeven als een base64 encoded JSON string die bij het aanmelden meegegeven wordt als een login_hint parameter.
Switch identiteit
Indien je de gebruiker niet wil afmelden in ACM, maar je wil enkel dat hij van identiteit kan switchen (kiezen voor een andere organisatie of doelgroep), dan kan je de “switch identiteit” initiëren.
Net zoals bij het afmelden dient men eerst lokaal in de toepassing af te melden en dan door te verwijzen naar het End Session Endpoint, maar men geeft hierbij de extra parameter “switch” mee. De ACM IDP zal enkel de sessie voor de specifieke toepassing afsluiten en de gebruiker moet niet opnieuw aanmelden binnen ACM, maar kan een nieuwe organisatie of doelgroep kiezen.
Session timeouts
De toepassing bepaalt zelf de session timeouts van de eigen toepassing.
Bij een authenticatie wordt er enkel een sessie opgebouwd op de ACM IDP gedurende de authenticatie. Deze sessie bepaalt ook of men een single sign-on kan krijgen als men voor het vervallen van deze sessie naar een andere ACM-ontsloten toepassing zou navigeen. Maar de sessie op de ACM IDP heeft geen impact op de sessie van de toepassig zelf.
Refresh Token
De Client kan duidelijk maken dat hij ook een Refresh Token wenst te ontvangen door de scope “offline_access” toe te voegen.
Tip
Het feit dat men gebruik wenst te maken van Refresh Tokens dient voor de desbetreffende Client expliciet in het integratiedossier meegegeven te worden. Ook de duurtijd hoe lang men Refresh Tokens mag inruilen wordt in het integratiedossier vastgelegd (en is maximaal 8 uur): deze duurtijd geldt niet voor ieder nieuw Refresh Token, maar wordt geteld vanaf het initiële Authenticatie Request.Tip
Gelieve te valideren dat de Client meteen stopt met opvragen van nieuwe refresh tokens na het verlopen van de periode waar Refresh Tokens gebruikt kunnen worden: bij de eerste weigering van de OP zou de Client moeten concluderen dat het opvragen van Refresh Tokens niet meer mogelijk is.Userinfo endpoint
De OpenID Connect standaard voorziet dat Clients de claims met de identiteit van de gebruiker ook kunnen opvragen op het Userinfo Endpoint. Het ID-token is een JWT en dus signed en het bevat meer claims waarmee de integriteit van het ID-token gevalideerd kan worden. Daarom geniet het gebruik van ID-tokens de voorkeur op het gebruik van het Userinfo Endpoint.
Men dient in het integratiedossier expliciet aan te geven dat de Client gebruik wenst te maken van het Userinfo Endpoint.
Tip
Gelieve te valideren dat de Client geen onnodige Requests stuurt naar het Userinfo Endpoint indien de Client niet opengesteld werd voor het gebruik van het Userinfo Endpoint.Cross client ID-token
In sommige scenario’s is het nuttig om -naast het ID-token dat men voor de eigen Client vroeg- ook een ID-token aan te vragen namens een andere Client.
Dit kan de Client doen door de parameter “audience:server:client_id” toe te voegen aan de scope (met client_id de CLientID van de doeltoepassing). Beide Clients moeten daar uiteraard mee instemmen.
De Client waarvoor het ID-token bestemd is, dient alle gebruikerlijke validaties van een ID-token te voltooien: ook de audiance “aud” zal duidelijk maken dat het ID-token voor hem bestemd is en de “aud” kan dus ook gevalideerd worden.
Authenticatiemiddelen
Bij het Authenticatie Request kan men optioneel de parameter “acr_values” meegeven, met daarbij een (door een spatie gescheiden) lijst van URN’s van authenticatiemiddelen: de mogelijke URN’s staan vermeld in het integratiedossier.
In het ID-token wordt dan het gekozen authenticatiemiddel weergegeven in de parameter “acr”.
Indien er via acr_values slechts één authenticatiemiddel werd meegestuurd, dan zal de gebruiker standaard toch dat ene authenticatiemiddel dienen te selecteren. Indien men wenst dat de selectie van het authenticatiemiddel in dat geval wordt overgeslagen, dan kan dit aangegeven worden in het integratiedossier.
Het wordt niet aanbevolen om alle authenticatiemiddelen die in het integratiedossier toegelaten worden ook nog bijkomend te definiëren als acr_values: dat kent zeer weinig voordelen, maar heeft wel als nadeel dat er bij iedere wijzigiging van de toegelaten authenticatiemiddelen (eentje toevoegen, verwijderen of wijziging van URN) er ook wijzigingen in de toepassing vereist zijn.
Indien men gewoon de “acr” claim wenst te ontvangen zonder specifieke acr_values mee te sturen, dan kan men in het Authenticatie Request de scope “acr” mee opvragen.
PKCE
Bij publieke Clients (zoals mobiele apps en Single Page Applications) die de OpenID Connect Authorization Code Flow gebruiken, zijn er aanvallen mogelijk waarbij de Authorization Code onderschept wordt. Proof Key for Code Exchange (PKCE), “pixy” genaamd, biedt een techniek om dit soort aanvallen te mitigeren.
De Client kan bij het Authenticatie Request een code_challenge doorsturen en bij het opvragen van de tokens een code_verifier: de ACM IDP kan dan valideren dat het token-request effectief komt van de Client die de authenticatie opstartte.
Tip
Voor publieke Clients (zoals mobiele apps en Single Page Applications) is het gebruik van PKCE een absolute vereiste: voor zulke Clients zou men in het integratiedossier ook best aangeven dat Authenticatie Requests zonder PKCE “code challenge” voor deze Client geweigerd dienen te worden.Tip
Hoewel deze extentie specifiek werd voorzien om beveiligingsproblemen voor publieke Clients op te lossen, valt het aan te bevelen om PKCE ook voor web-toepassingen te gebruiken !Response Mode
In het authenticatierequest kan je de parameter “response_mode” meegeven: deze bepaalt op welke manier de Authorization Code teruggestuurd zal worden: query (default), form_post of fragment.
Tip
Indien uw Client de response_mode “form_post” ondersteunt, dan valt het aan te bevelen om dit standaard te gebruiken. “form_post” is immers een veiligere methode en het verhindert dat de Authorization Code in de URL van de browser verschijnt, waarbij een gebruiker deze per ongeluk zou kunnen hergebruiken (bij een refresh van een pagina), waar deze Authorization Code slechts voor eenmalig gebruik bedoeld is.Rate limit
Om allerhande aanvallen (zoals bijvoorbeeld het raden van Authorization Codes) tegen te gaan, worden het aantal foutieve verzoeken per afzender bijgehouden. Indien het aantal foutieve verzoeken vanaf een bepaald IP-adres een limiet overschreidt, dan wordt er gedurende een bepaalde tijd geen enkel verzoek meer voor dit IP-adres verwerkt.