Stell dir folgendes Szenario vor: Ein Nutzer meldet sich zum ersten Mal an und hat noch keine Zwei-Faktor-Methode eingerichtet. Eigentlich möchtest du 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 zeige ich dir 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 dann an, eine der im Flow konfigurierten Methoden (z. B. OTP oder WebAuthn) selbst auszuwählen und einzurichten. Ohne das Plugin führt der Versuch, das über einen normalen Keycloak-Flow abzubilden, zu einer Authentication-Flow-Exception – Keycloak kommt mit dieser Konstellation von Haus aus nicht klar
Schritt 1: Das Plugin kompilieren
Im Repository wird nur der Quellcode bereitgestellt, es gibt kein fertiges Jar zum Download. Wir müssen das Plugin also selbst bauen. Am einfachsten geht das in einer Linux-Umgebung mit Maven (kurz „mvn“).
Kurz zur Einordnung: Maven ist ein Build-Tool für Java-Projekte. Es lädt die benötigten Abhängigkeiten herunter, kompiliert den Code und packt das Ergebnis in eine JAR-Datei – genau das brauchen wir hier. Falls Maven noch nicht installiert ist, geht das auf einem Debian/Ubuntu-System beispielsweise so
#bash
sudo apt-get update
sudo apt-get install -y mavenDas ist nur ein Beispiel – je nach Distribution und Umgebung kann der Weg zur Maven-Installation anders aussehen.
Jetzt geht’s ans Bauen. Zuerst klonst du das Repository:
#bash
git clone https://github.com/netzbegruenung/keycloak-mfa-plugins.gitDann wechselst du in das Verzeichnis des Enforce-MFA-Plugins:
#bash
cd keycloak-mfa-plugins/enforce-mfa/
mvn clean installNach erfolgreichem Build liegt das fertige Plugin im target-Ordner:
bash
ls target
netzbegruenung.enforce-mfa-v<version>.jarSchritt 2: Plugin installieren
Die JAR-Datei kopierst du in den providers-Ordner deiner Keycloak-Installation und startest Keycloak anschließend neu.
Wer das Plugin dauerhaft fest einbinden möchte, sollte vorher einmal 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 – für die meisten Installationen ist das aber unkritisch.
Nach dem Neustart kannst du in der Admin-Oberfläche prüfen, ob Keycloak die Erweiterung erkannt hat:
Schritt 3: Das Plugin in einen Authentication Flow einbinden
Jetzt zum eigentlich spannenden Teil: Wie bindest du das Plugin so ein, dass es tut, was es soll? Dafür wird ein Authentication Flow benötigt, der wie im folgenden Screenshot aufgebaut ist:
Der gesamte Flow ist auf den ersten Blick ziemlich unübersichtlich. Ich habe deshalb die wichtigen Abschnitte mit Rechtecken markiert und nummeriert, damit klarer wird, was an welcher Stelle passiert.
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 der folgende Screenshot: die Login-Maske, die ihm dank des Plugins die Wahl zwischen den konfigurierten MFA-Methoden anbietet.
Ein Wort zur Sorgfalt
Beim Einrichten dieses Flows solltest du sehr sorgfältig vorgehen – die Struktur mit ihren verschachtelten Subflows, Alternativen und Bedingungen ist fehleranfällig. Leider gibt es aktuell keine Möglichkeit, den Flow einfach als Konfiguration zu exportieren und weiterzugeben: Ein Export ist mit der aktuellen Keycloak-Version nicht möglich. Du wirst also nicht darum herumkommen, ihn einmal manuell in der Admin-Oberfläche nachzubauen.
Fazit
Mit dem Enforce-MFA-Plugin lässt sich eine Lücke schließen, die Keycloak bislang selbst nicht abdeckt: Nutzer ohne bestehende MFA-Methode selbst entscheiden zu lassen, ob sie OTP oder WebAuthn einrichten möchten. Der Weg dahin – kompilieren, installieren, Flow konfigurieren – ist etwas aufwendiger als ein einfacher Toggle in der Admin-Oberfläche, aber mit dem hier gezeigten vollständigen Flow als Vorlage sollte der Nachbau gut machbar sein.
Wartung und Support
Ein Punkt bleibt bei solchen Plugins immer im Hinterkopf: Weiterentwicklung und Unterstützung für künftige Keycloak-Versionen sind nicht garantiert. Wer hier kein Risiko eingehen möchte, kann das Plugin bei uns unter Support stellen – wir testen es bei jedem neuen Keycloak-Release und stellen die Funktionstüchtigkeit sicher. Sollte es mit einer neuen Version nicht mehr kompatibel sein, kümmern wir uns um die Anpassung.