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.

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>.jar naar de map providers van 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

Waarom dit nodig is

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.

Attribuutkoppeling

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.

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 Redirect: open de Settings en zet Default Identity Provider op XFA.

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.

Geavanceerde instellingen

Voor geavanceerdere instellingen, zoals de factor beperken tot bepaalde gebruikers of XFA alleen in bepaalde gevallen laten draaien, gebruik je de conditional authenticators van Keycloak binnen de flow XFA Device Verification. Zie daarvoor de documentatie van Keycloak.