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.
Den XFA-login-hint-Provider auf Keycloak installieren
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>.jarin das Verzeichnisprovidersvon 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
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.
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 zum Post Login Flow hinzufügen
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 Redirector: Öffnen Sie die Settings und stellen Sie Default Identity Provider auf
XFA.
2. Ihn als Post Login Flow einbinden
Ö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.
XFA für weitere Gruppen einführen
Führen Sie den XFA-Post-Login-Flow nur für Gruppen mit xfa-test=true aus. Beginnen Sie mit einer kleinen Testgruppe und markieren Sie nach dem Test weitere Gruppen. Benutzer ohne dieses Attribut an ihrem Benutzerkonto oder ihren Gruppen melden sich ohne diesen XFA-Gerätecheck an.
Verwenden Sie Keycloak 26.x mit dem oben installierten Login-Hint-Provider. Die Bedingung für Gruppenattribute ist in Keycloak 26.0 verfügbar; der aktuelle Provider-Build ist für 26.7.2 ausgelegt. Konfigurieren Sie diesen Geltungsbereich bei einer neuen Integration, bevor Sie den Post-Login-Flow einbinden.
- Erstellen Sie unter Groups eine kleine Gruppe, zum Beispiel
XFA test. - Fügen Sie auf der Registerkarte Attributes dieser Gruppe das Attribut
xfa-testmit dem Werttruehinzu. - Speichern Sie das Gruppenattribut mit Save.
- Fügen Sie über Users > den Benutzer > Groups > Join Group einen Testbenutzer ohne Administratorrechte zur Gruppe hinzu.
- Öffnen Sie Authentication > Flows >
XFA Device Verification. - Erstellen Sie mit Add sub-flow einen Unterablauf vom Typ Generic namens
XFA groups. - Setzen Sie Requirement des Unterablaufs auf Conditional.
- Fügen Sie innerhalb dieses Unterablaufs mit Add condition die Bedingung Condition - user attribute hinzu.
- Setzen Sie Requirement der Bedingung auf Required.
- Öffnen Sie Settings der Bedingung über das Zahnradsymbol.
- Konfigurieren Sie die Bedingung mit Alias
xfa-groups-condition, Attribute namexfa-test, Expected attribute valuetrueund aktiviertem Include group attributes. Lassen Sie Negate output und regex deaktiviert. - Speichern Sie die Bedingung mit Save.
- Verschieben Sie IdP Redirector (login_hint) mit dem Ziehgriff in den Unterablauf, unter die Bedingung.
- Verschieben Sie Identity Provider Redirector in den Unterablauf, unter IdP Redirector (login_hint).
- Prüfen Sie, dass beide Redirectors auf Required stehen, beide Default Identity Provider
XFAbehalten und keiner außerhalb des bedingten Unterablaufs verbleibt. - Testen Sie eine neue Anmeldung mit dem Gruppenmitglied ohne Administratorrechte. Der Benutzer sollte nach der regulären Anmeldung zu XFA gelangen.
- Testen Sie eine neue Anmeldung mit einem Benutzer außerhalb der markierten Gruppen. Dieser Benutzer sollte die Anmeldung ohne diesen XFA-Check abschließen können.
- Fügen Sie
xfa-test=truezu den Attributes der nächsten einzubeziehenden Gruppe hinzu. - Speichern Sie das Gruppenattribut mit Save.
- Wiederholen Sie die Anmeldetests, bevor Sie eine weitere Gruppe hinzufügen.
Verwenden Sie diese Markierung nur an Gruppen. Die Bedingung liest auch Benutzerattribute, sodass dieselbe Markierung direkt an einem Benutzer auch diesen Benutzer einbezieht. Wenn Sie bei der Ersteinrichtung bereits XFA test und den bedingten Unterablauf erstellt haben, behalten Sie diese bei und fahren Sie mit den Testschritten fort.