XFA instellen als authenticatiefactor in Keycloak
Stel XFA in Keycloak in om toestelverificatie toe te voegen nadat de gebruiker zich heeft geauthenticeerd. XFA draait als stap na het aanmelden, toetst het toestel aan het ingestelde beleid en laat het aanmelden doorgaan wanneer de beslissing over het toestel toegang toelaat. Gebruik deze pagina om de nodige instellingen te controleren en de flow te testen voor je uitrolt.
Let op: deze gids gaat ervan uit dat je organisatie een XFA-account heeft en dat jij daar beheerder van bent, zowel in XFA als in Keycloak. Heb je nog geen XFA-account, maak er dan een aan op https://dashboard.xfa.tech/signup.
Maak een integratie aan in het XFA-dashboard
Meld je aan bij het XFA-dashboard, ga naar de pagina Enforcement, klik op New en kies Keycloak als type integratie.
Op die pagina staan verschillende waarden die je in de volgende stappen nodig hebt (Client ID, Client Secret en de OpenID Connect-endpoints). Er staat ook een veld Redirect URI, dat je hieronder invult met een waarde uit Keycloak.
Laat deze pagina openstaan tijdens de volgende stappen.
Installeer de XFA login-hint-provider op Keycloak
Keycloak geeft de identiteit van de al geauthenticeerde gebruiker standaard niet door aan een externe identity provider. XFA heeft die identiteit (het e-mailadres van de gebruiker) nodig om te weten welk toestel het moet controleren. Een kleine opensource-provider voor Keycloak lost dat op: die leest de geauthenticeerde gebruiker uit de sessie en zet de parameter login_hint op de doorverwijzing naar XFA. Je vindt de provider op github.com/gl-ventures/xfa-keycloak-login-hint-mapper.
-
Kloon de repository van de provider en bouw hem (of gebruik de kant-en-klare jar):
mvn clean package -
Kopieer de resulterende
login-hint-idp-<version>.jarnaar de mapprovidersvan Keycloak:cp target/login-hint-idp-*.jar /opt/keycloak/providers/ -
Bouw Keycloak opnieuw zodat de provider geregistreerd wordt, en herstart daarna de draaiende instantie om hem actief te maken:
/opt/keycloak/bin/kc.sh build# then restart Keycloak, e.g. restart the service or container running it,# or start it again directly:/opt/keycloak/bin/kc.sh start
De provider haalt het e-mailadres uit de geauthenticeerde Keycloak-sessie (getAuthenticatedUser()), niet uit een parameter die de client meestuurt. Zo weet je zeker dat het toestel dat XFA controleert van de gebruiker is die zich echt heeft aangemeld.
Maak de XFA-identity provider aan in Keycloak
Kies in de Keycloak Admin Console je realm en ga naar Identity providers. Klik op Add provider en kies OpenID Connect v1.0.
Vul het volgende in, met de waarden van de XFA-dashboardpagina die je hebt laten openstaan.
Provider
- Alias:
XFA(precies deze alias wordt hieronder in de Post Login Flow gebruikt) - Display name:
XFA
OpenID Connect-instellingen
- Zet Use discovery endpoint uit. Daarmee verschijnen de velden waarin je de endpoints handmatig invult.
- Authorization URL
- Token URL
- User Info URL
- Issuer
- Zet Validate Signatures aan om het veld JWKS URL te tonen en vul daar de JWKS URL in.
- Zet Client authentication op Client secret sent in the request body.
- Client ID
- Client Secret
Sla de provider op. Keycloak toont nu een Redirect URI voor deze identity provider (die ziet eruit als https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Kopieer die waarde terug naar het veld Redirect URI op de XFA-dashboardpagina en sla de XFA-integratie op.
Geavanceerde instellingen
Open de provider die je net hebt aangemaakt en klap het onderdeel Advanced open (dat staat standaard dicht):
- Zet Default Scopes op
openid email profile. - Zet Pass login_hint aan, zodat Keycloak het e-mailadres van de geauthenticeerde gebruiker (gezet door de provider die je hierboven hebt geïnstalleerd) doorgeeft aan XFA.
Laat de standaardmappers staan. XFA geeft het email-adres (en sub) van de gebruiker terug in het ondertekende token, waarmee Keycloak het resultaat van de controle koppelt aan de al geauthenticeerde gebruiker.
Voeg XFA toe aan de Post Login Flow
XFA moet draaien nadat de gebruiker zich heeft geauthenticeerd, dus je stelt het in als Post Login Flow op je primaire authenticatie.
1. Maak een authenticatieflow aan
Ga in de Admin Console naar Authentication > Flows en maak een nieuwe flow aan (bijvoorbeeld XFA Device Verification) van het type Basic flow.
Voeg twee executions toe, allebei op Required, in deze volgorde:
- IdP Redirector (login_hint): die komt uit de jar die je hebt geïnstalleerd. Open de Settings (het tandwiel) en zet Default Identity Provider op
XFA. - Identity Provider Redirector: open de Settings en zet Default Identity Provider op
XFA.
2. Koppel hem als Post Login Flow
Open de primaire authenticatie die de eerste aanmeldstap uitvoert (bijvoorbeeld je Microsoft-identity provider onder Identity providers), ga naar de geavanceerde instellingen en zet Post login flow op de flow XFA Device Verification die je net hebt aangemaakt.
Nadat een gebruiker zich gewoon heeft aangemeld, stuurt Keycloak hem nu door naar XFA om zijn toestel te laten controleren voordat de sessie tot stand komt.
Rol XFA uit naar meer groepen
Voer de XFA-post-login-flow alleen uit voor groepen met xfa-test=true. Begin met een kleine testgroep en geef na het testen meer groepen dit attribuut. Gebruikers zonder dat attribuut op hun gebruiker of groepen melden zich aan zonder deze XFA-toestelcontrole.
Gebruik Keycloak 26.x met de hierboven geïnstalleerde login-hint-provider. De voorwaarde voor groepsattributen is beschikbaar in Keycloak 26.0; de huidige providerbuild is gericht op 26.7.2. Stel bij een nieuwe integratie deze beperking in voordat je de post-login-flow koppelt.
- Maak een kleine groep, zoals
XFA test, onder Groups. - Voeg het attribuut
xfa-testmet de waardetruetoe op het tabblad Attributes van die groep. - Sla het groepsattribuut op met Save.
- Voeg een testgebruiker zonder beheerdersrechten toe aan de groep via Users > de gebruiker > Groups > Join Group.
- Open Authentication > Flows >
XFA Device Verification. - Maak met Add sub-flow een subflow van het type Generic met de naam
XFA groups. - Zet Requirement van de subflow op Conditional.
- Voeg met Add condition de voorwaarde Condition - user attribute toe binnen die subflow.
- Zet Requirement van de voorwaarde op Required.
- Open Settings van de voorwaarde met het tandwielpictogram.
- Configureer de voorwaarde met Alias
xfa-groups-condition, Attribute namexfa-test, Expected attribute valuetrueen Include group attributes ingeschakeld. Laat Negate output en regex uitgeschakeld. - Sla de voorwaarde op met Save.
- Verplaats IdP Redirector (login_hint) met de sleepgreep naar de subflow, onder de voorwaarde.
- Verplaats Identity Provider Redirector naar de subflow, onder IdP Redirector (login_hint).
- Controleer dat beide redirectors op Required staan, beide Default Identity Provider
XFAbehouden en geen van beide buiten de voorwaardelijke subflow staat. - Test een nieuwe aanmelding met het groepslid zonder beheerdersrechten. De gebruiker hoort na de gewone aanmelding bij XFA terecht te komen.
- Test een nieuwe aanmelding met een gebruiker buiten de gemarkeerde groepen. Die gebruiker hoort zich zonder deze XFA-controle te kunnen aanmelden.
- Voeg
xfa-test=truetoe aan de Attributes van de volgende groep die je wilt opnemen. - Sla het groepsattribuut op met Save.
- Herhaal de aanmeldtests voordat je nog een groep toevoegt.
Gebruik deze markering alleen op groepen. De voorwaarde leest ook gebruikersattributen, dus dezelfde markering rechtstreeks op een gebruiker zetten neemt die gebruiker ook op. Als je bij de eerste configuratie XFA test en de voorwaardelijke subflow al hebt aangemaakt, behoud je die en ga je verder bij de teststappen.