MFA-Enrollment in Keycloak: Nutzer zwischen OTP und WebAuthn wählen lassen
Keycloak unterstützt standardmäßig keine Auswahl zwischen mehreren MFA-Verfahren, wenn Nutzer noch keinen zweiten Faktor eingerichtet haben. Mit dem Plugin Enforce MFA lässt sich diese Lücke schließen. In diesem Beitrag zeigen wir, wie das Plugin kompiliert, installiert und in einen Authentication Flow integriert wird, damit Anwender selbst entscheiden können, ob sie künftig OTP oder WebAuthn als zweiten Faktor nutzen möchten.
Stellen Sie sich folgendes Szenario vor: Ein Nutzer meldet sich zum ersten Mal an und hat noch keine Zwei-Faktor-Methode eingerichtet. Eigentlich möchten Sie ihm die Wahl lassen – soll er sich künftig per OTP (Einmalpasswort) oder per WebAuthn/FIDO2 (z. B. Sicherheitsschlüssel oder Passkey) anmelden? Keycloak bietet dafür standardmäßig keine Lösung. Sobald noch kein zweiter Faktor konfiguriert ist, gibt es out of the box keine Möglichkeit, den Nutzer zwischen mehreren MFA-Methoden wählen zu lassen.
Genau hier setzt das Plugin Enforce MFA aus der Keycloak-MFA-Plugin-Sammlung von netzbegrünung an. Die Dokumentation im Repository ist bewusst knapp gehalten, deshalb zeigen wir Ihnen in diesem Beitrag den kompletten Weg – vom Kompilieren des Plugins bis zum fertigen, funktionierenden Authentication Flow.
Was macht das Plugin?
Enforce MFA erkennt, wenn ein Nutzer noch keine Zweitfaktor-Methode eingerichtet hat, und bietet ihm anschließend die im Flow konfigurierten Verfahren zur Auswahl an. Dabei kann der Benutzer selbst entscheiden, welche Methode eingerichtet werden soll, beispielsweise OTP oder WebAuthn. Ohne dieses Plugin führt der Versuch, dieses Verhalten über einen Standard-Keycloak-Flow abzubilden, zu einer Authentication-Flow-Exception. Keycloak kann diese Konstellation von Haus aus nicht verarbeiten. Das Plugin schließt die Funktionslücke in Keycloak effektiv. Bevor Anwender jedoch zwischen OTP und WebAuthn wählen können, muss die Erweiterung zunächst erstellt und in die Keycloak-Umgebung eingebunden werden. Schauen wir uns darum auf die Installation an, beginnend mit dem Build-Prozess.
Schritt 1: Das Plugin kompilieren
Im Repository wird ausschließlich der Quellcode bereitgestellt. Eine fertige JAR-Datei zum Download gibt es nicht. Daher muss das Plugin zunächst selbst gebaut werden. Am einfachsten erfolgt dies in einer Linux-Umgebung mit Maven.
Maven ist ein Build-Tool für Java-Projekte. Es lädt die benötigten Abhängigkeiten herunter, kompiliert den Code und erstellt daraus eine JAR-Datei. Genau diese wird für die spätere Installation benötigt.
Falls Maven noch nicht installiert ist, kann die Installation auf Debian- oder Ubuntu-Systemen beispielsweise wie folgt erfolgen:
Dies ist nur ein Beispiel – je nach Distribution und Umgebung kann der Weg zur Maven-Installation anders aussehen.
Jetzt geht's ans Bauen. Anschließend klonen Sie das Repository:
Nun wechseln Sie in das Verzeichnis des Enforce-MFA-Plugins:
Nach erfolgreichem Build liegt nun das fertige Plugin im target-Ordner:
Schritt 2: Die Installation des Plugins
Kopieren Sie die JAR-Datei in den providers-Ordner Ihrer Keycloak-Installation und starten Sie anschließend Keycloak neu.
Wenn Sie das Plugin dauerhaft fest einbinden wollen, sollten sie vorher kc.sh build ausführen. Das optimiert den Startvorgang, indem Keycloak die Provider-Konfiguration bereits beim Build statt erst beim Serverstart auflöst. Lässt man diesen Schritt weg, dauert der nächste Start etwas länger, weil Keycloak den neuen Provider zur Laufzeit erkennen und einbinden muss.
Nach dem Neustart können Sie in der Admin-Oberfläche prüfen, ob Keycloak die Erweiterung erkannt hat:
Schritt 3: Das Plugin in einen Authentication Flow einbinden
Kommen wir zum spannenden Teil: Wie binden Sie das Plugin so ein, dass es tut, was es soll? Dafür benötigen Sie einen Authentication Flow, der wie folgt aufgebaut ist:
Der gesamte Flow erscheint auf dem ersten Blick ziemlich unübersichtlich. Die relevanten Abschnitte wurden zur besseren Nachvollziehbarkeit mit nummerierten Markierungen versehen. So ist klar erkennbar, was an welcher Stelle dargestellt werden soll.
Der Anfang: Login, wie gewohnt
Der Beginn des Flows ist weitgehend selbsterklärend. Ist der Nutzer bereits per Cookie oder Kerberos authentifiziert, ist er direkt angemeldet. Andernfalls muss er sich zunächst per Benutzername und Passwort authentifizieren (Username Password Form).
(1) Die Weiche: MFA vorhanden oder nicht?
Ab hier muss Keycloak unterscheiden: Hat der Nutzer bereits eine MFA-Methode eingerichtet, oder muss er das erst noch tun? Dafür braucht es einen Subflow mit zwei Alternativen – im Screenshot als (1) mfa-auth-or-enroll markiert.
(2) Alternative 1: MFA-Authentifizierung
Der erste Subflow, (2) mfa-authentication, prüft über die Bedingung „Condition – user configured“, ob der Nutzer bereits über eine MFA-Methode verfügt (Subflow check-mfa-enrolled). Ist das der Fall, kann er sich per OTP oder WebAuthn anmelden (Subflow select-mfa-method mit den Alternativen „OTP Form“ und „WebAuthn Authenticator“). Das ist reine Standard-Keycloak-Funktionalität und hat mit dem Plugin noch nichts zu tun.
(3) Alternative 2: MFA-Enrollment
Hat der Nutzer noch kein MFA-Verfahren eingerichtet, greift die zweite Alternative – der Subflow (3) mfa-enrollment, der für das Enrollment zuständig ist. Genau hier kommt das Plugin ins Spiel, und genau hier musst du dich exakt an die Vorgabe des Plugin-Entwicklers halten: Es werden zwei weitere Subflows benötigt.
(3a) list-mfa-enrollment-methods
legt fest, für welche MFA-Verfahren sich der Nutzer überhaupt einschreiben kann – hier stehen als Alternativen „OTP Form“ und „WebAuthn Authenticator“, abgesichert durch die Bedingung „Condition – user configured“. Man könnte annehmen, dass Keycloak eine solche Auswahl bereits von Haus aus unterstützt. Probiert man es ohne das Plugin, bekommt man jedoch eine Fehlermeldung – genau das Problem, das eingangs beschrieben wurde.
(3b) enforce-mfa-enrollment
bindet das eigentliche Plugin ein (Schritt „Enforce MFA“, als REQUIRED markiert). Es sorgt dafür, dass dem Nutzer die im ersten Subflow (3a) definierten MFA-Verfahren zur Auswahl angeboten werden, und dass er sich für eines davon entscheiden und es einrichten muss.
Wichtig dabei: Der Subflow mit den Alternativen (3a) muss der erste Subflow innerhalb des Wrapper-Flows sein – diese Reihenfolge verlangt das Plugin ausdrücklich, sonst funktioniert es nicht.
Wie sich das für den Nutzer in der Praxis anfühlt, zeigt die folgende Grafik: die Login-Maske, die ihm dank des Plugins die Wahl zwischen den konfigurierten MFA-Methoden anbietet.
Wichtige Hinweise zum Flow-Aufbau
Beim Einrichten dieses Flows sollten Sie sorgfältig vorgehen, da die Struktur durch verschachtelte Subflows, Alternativen und Bedingungen fehleranfällig ist. Aktuell gibt es keine Möglichkeit, den Flow einfach als Konfiguration zu exportieren und weiterzugeben. Da ein Export in der aktuellen Keycloak-Version nicht möglich ist, muss der Flow einmalig manuell in der Admin-Oberfläche nachgebildet werden
Fazit
Mit dem Enforce-MFA-Plugin lässt sich eine funktionale Lücke in Keycloak schließen: Anwender können selbst entscheiden, ob sie die Multi-Faktor-Authentifizierung per OTP oder WebAuthn einrichten möchten. Zwar erfordert die Implementierung zusätzliche Schritte wie die Kompilierung des Plugins, die Installation sowie die Konfiguration des Authentifizierungsflusses, dafür entsteht jedoch eine flexible und benutzerfreundliche MFA-Registrierung. Mit dem beschriebenen Flow als Vorlage lässt sich die Konfiguration strukturiert nachbilden und erfolgreich in bestehenden Keycloak-Umgebungen einsetzen.
Fragen zum Flow?
Authentication Flows wie dieser bieten viel Flexibilität, werden aber schnell komplex. Der hier gezeigte Aufbau kann als Vorlage für die eigene Implementierung dienen. Sollten bei der Einrichtung oder Anpassung Fragen entstehen, kontaktieren Sie uns!
Ihr Ansprechpartner für Keycloak: Tom Schiekel