XFA als Authentifizierungsfaktor in Keycloak einrichten

Richten Sie XFA in Keycloak ein, um eine Geräteverifizierung hinzuzufügen, nachdem sich der Benutzer authentifiziert hat. XFA läuft als Schritt nach der Anmeldung, prüft das Gerät anhand der eingestellten Richtlinie und lässt die Anmeldung weitergehen, wenn die Entscheidung über das Gerät den Zugriff zulässt. Nutzen Sie diese Seite, um die nötigen Einstellungen zu prüfen und den Ablauf zu testen, bevor Sie ausrollen.

Hinweis: Diese Anleitung geht davon aus, dass Ihre Organisation ein XFA-Konto hat und dass Sie dort Administrator sind, sowohl in XFA als auch in Keycloak. Haben Sie noch kein XFA-Konto, legen Sie eines an unter https://dashboard.xfa.tech/signup.

Eine Integration im XFA-Dashboard anlegen

Melden Sie sich am XFA-Dashboard an, gehen Sie auf die Seite Enforcement, klicken Sie auf Neu und wählen Sie Keycloak als Typ der Integration.

Auf dieser Seite stehen mehrere Werte, die Sie in den nächsten Schritten brauchen (Client ID, Client Secret und die OpenID Connect-Endpoints). Dort steht auch ein Feld Redirect URI, das Sie weiter unten mit einem Wert aus Keycloak füllen.

Lassen Sie diese Seite während der nächsten Schritte offen.

Keycloak gibt die Identität des bereits authentifizierten Benutzers standardmäßig nicht an einen externen Identity Provider weiter. XFA braucht diese Identität (die E-Mail-Adresse des Benutzers), um zu wissen, welches Gerät es prüfen soll. Ein kleiner Open-Source-Provider für Keycloak löst das: Er liest den authentifizierten Benutzer aus der Sitzung und setzt bei der Weiterleitung zu XFA den Parameter login_hint. Sie finden den Provider unter github.com/gl-ventures/xfa-keycloak-login-hint-mapper.

Klonen Sie das Repository des Providers und bauen Sie den Provider (oder nutzen Sie die fertige jar):
```
mvn clean package
```
Kopieren Sie die entstandene login-hint-idp-<version>.jar in das Verzeichnis providers von Keycloak:
```
cp target/login-hint-idp-*.jar /opt/keycloak/providers/
```

Bauen Sie Keycloak neu, damit der Provider registriert wird, und starten Sie danach die laufende Instanz neu, damit er aktiv wird:

/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

Warum das nötig ist

Der Provider holt die E-Mail-Adresse aus der authentifizierten Keycloak-Sitzung (getAuthenticatedUser()), nicht aus einem Parameter, den der Client mitschickt. So ist sichergestellt, dass das Gerät, das XFA prüft, dem Benutzer gehört, der sich wirklich angemeldet hat.

Den XFA-Identity-Provider in Keycloak anlegen

Wählen Sie in der Keycloak Admin Console Ihren Realm und gehen Sie zu Identity providers. Klicken Sie auf Add provider und wählen Sie OpenID Connect v1.0.

Tragen Sie Folgendes ein, mit den Werten von der XFA-Dashboardseite, die Sie offen gelassen haben.

Provider

Alias: XFA (genau dieser Alias wird unten im Post Login Flow verwendet)
Display name: XFA

OpenID Connect-Einstellungen

Schalten Sie Use discovery endpoint aus. Damit erscheinen die Felder, in die Sie die Endpoints von Hand eintragen.
Authorization URL
Token URL
User Info URL
Issuer
Schalten Sie Validate Signatures ein, um das Feld JWKS URL zu zeigen, und tragen Sie dort die JWKS URL ein.
Stellen Sie Client authentication auf Client secret sent in the request body.
Client ID
Client Secret

Speichern Sie den Provider. Keycloak zeigt nun eine Redirect URI für diesen Identity Provider (sie sieht aus wie https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Kopieren Sie diesen Wert zurück in das Feld Redirect URI auf der XFA-Dashboardseite und speichern Sie die XFA-Integration.

Erweiterte Einstellungen

Öffnen Sie den Provider, den Sie gerade angelegt haben, und klappen Sie den Bereich Advanced auf (er ist standardmäßig zu):

Stellen Sie Default Scopes auf openid email profile.
Schalten Sie Pass login_hint ein, damit Keycloak die E-Mail-Adresse des authentifizierten Benutzers (gesetzt durch den oben installierten Provider) an XFA weitergibt.

Attributzuordnung

Lassen Sie die Standardmapper stehen. XFA gibt die email-Adresse (und sub) des Benutzers im signierten Token zurück, womit Keycloak das Ergebnis der Prüfung dem bereits authentifizierten Benutzer zuordnet.

XFA muss laufen, nachdem sich der Benutzer authentifiziert hat, Sie richten es also als Post Login Flow auf Ihrer primären Authentifizierung ein.

1. Einen Authentifizierungsflow anlegen

Gehen Sie in der Admin Console zu Authentication > Flows und legen Sie einen neuen Flow an (zum Beispiel XFA Device Verification) vom Typ Basic flow.

Fügen Sie zwei Executions hinzu, beide auf Required, in dieser Reihenfolge:

IdP Redirector (login_hint): Der kommt aus der jar, die Sie installiert haben. Öffnen Sie die Settings (das Zahnrad) und stellen Sie Default Identity Provider auf XFA.
Identity Provider Redirect: Öffnen Sie die Settings und stellen Sie Default Identity Provider auf XFA.

Öffnen Sie die primäre Authentifizierung, die den ersten Anmeldeschritt ausführt (zum Beispiel Ihren Microsoft-Identity-Provider unter Identity providers), gehen Sie zu den erweiterten Einstellungen und stellen Sie Post login flow auf den Flow XFA Device Verification, den Sie gerade angelegt haben.

Nachdem sich ein Benutzer ganz normal angemeldet hat, leitet Keycloak ihn nun zu XFA weiter, damit sein Gerät geprüft wird, bevor die Sitzung zustande kommt.

Erweiterte Einstellungen

Für weitergehende Einstellungen, etwa den Faktor auf bestimmte Benutzer zu begrenzen oder XFA nur in bestimmten Fällen laufen zu lassen, nutzen Sie die Conditional Authenticators von Keycloak innerhalb des Flows XFA Device Verification. Sehen Sie dazu die Dokumentation von Keycloak.