Technische info
Discovery URL
De Discovery-URL bevat de concrete URL’s van de specifieke endpoints van de oAuth Authorization Server, alsook de ondersteunde technologieën.
- voor test: https://authenticatie-ti.vlaanderen.be/.well-known/oauth-authorization-server/op
- voor productie: https://authenticatie.vlaanderen.be/.well-known/oauth-authorization-server/op
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
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.
Scopes
In het integratiedossier staat beschreven welke scopes er voor de Client toegelaten 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 Sesseion 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 oAuth Authorization Server zou de Client moeten concluderen dat het opvragen van Refresh Tokens niet meer mogelijk is.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 !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.