Kerberos-Integration in Keycloak: Schritt-für-Schritt-Anleitung

Die Integration von Kerberos in Keycloak ermöglicht eine nahtlose Authentifizierung, insbesondere in Windows-basierten Unternehmensnetzwerken. Benutzer können sich dadurch automatisch anmelden – ohne erneut Benutzernamen und Passwort eingeben zu müssen. Das ist nicht nur komfortabel, sondern auch sicher und gut integrierbar in bestehende Infrastrukturen mit Active Directory.

Die gute Nachricht:
Die Einrichtung von Kerberos in Keycloak ist grundsätzlich nicht kompliziert – wenn man die Abläufe und Begriffe verstanden hat.

Die ehrliche Nachricht:
Trotzdem klappt es in der Praxis selten beim ersten Versuch. Die Fehlermeldungen sind oft wenig aussagekräftig, die Ursache liegt manchmal ganz woanders als erwartet – sei es im Active Directory, in einer falsch gesetzten Berechtigung, in der Keytab oder in einem Browser-Setting.

Deshalb ist dieser Artikel bewusst sehr ausführlich gehalten.
Er führt Schritt für Schritt durch die Konfiguration – beginnend mit der Vorbereitung im Active Directory, über die Einrichtung auf Server- und Keycloak-Seite, bis hin zur Anpassung des Authentifizierungsflusses. Zusätzlich enthält er gezielte Hinweise zur Fehleranalyse, zu Debugging-Optionen und zu einfachen Tests auf der Kommandozeile, mit denen sich typische Stolpersteine bereits vor der Inbetriebnahme erkennen lassen.

Ziel ist, dass du nicht nur „Copy & Paste“-Anleitungen abarbeitest, sondern die Zusammenhänge verstehst – und im Fehlerfall gezielt nachjustieren kannst.

1. Vorbereitung im Active Directory (AD)

Damit Keycloak Kerberos verwenden kann, muss zunächst im Active Directory (AD) ein passendes Dienstkonto eingerichtet und korrekt konfiguriert werden. Dieser Schritt ist essenziell, da das Dienstkonto über den Service Principal Name (SPN) später mit eingehenden Kerberos-Anfragen verknüpft wird.

Dienstkonto erstellen

Erstelle ein dediziertes Benutzerkonto in der AD-Benutzerverwaltung, z. B. mit dem Namen svc_keycloak. Dieses Konto wird von Keycloak genutzt, um sich gegenüber dem Kerberos Key Distribution Center (KDC) zu authentifizieren. Setze außerdem folgende Optionen:

Benutzer darf Kennwort nicht ändern.
Passwort läuft nicht ab.

Mit der PowerShell erledigst du das wie folgt:

New-ADUser -Name "svc_keycloak" -SamAccountName "svc_keycloak" -AccountPassword (Read-Host -AsSecureString "Passwort eingeben") -Enabled $true -PasswordNeverExpires $true -UserPrincipalName "svc_keycloak@myomain.local"

SPN (Service Principal Name) registrieren

Nun muss dem Dienstkonto ein SPN zugewiesen werden. Der SPN beschreibt den Dienstnamen, unter dem sich Keycloak gegenüber dem Kerberos-System authentifizieren möchte. Für eine Webanwendung ist das in der Regel ein HTTP-SPN:

setspn -A HTTP/keycloak.mydomain.local svc_keycloak

💡 Achte auf: Der Hostname (keycloak.mydomain.local) muss exakt dem entsprechen, unter dem der Keycloak-Server erreichbar ist.

Keytab-Datei erzeugen

Die Keytab-Datei enthält einen (oder mehrere) Kerberos-Schlüssel, die einem bestimmten Dienstkonto im Active Directory zugeordnet sind. Sie dient als Ersatz für eine interaktive Passworteingabe: Statt das Passwort des Dienstkontos bei jeder Authentifizierung manuell einzugeben, kann sich Keycloak mithilfe der Keytab automatisch gegenüber dem Kerberos-Server (KDC) ausweisen.

💡 Kurz gesagt: Die Keytab ist der „Ausweis“ für Keycloak, um als Dienstkonto svc_keycloak mit dem SPN HTTP/keycloak.domain.local im Netzwerk aufzutreten – ohne dass ein Passwort gespeichert oder abgefragt werden muss

Die Datei wird mit dem Tool ktpass auf einem Windows-System erzeugt:

ktpass -out C:\temp\keycloak.keytab -princ HTTP/keycloak.mydomain.local@MYDOMAIN.LOCAL -mapuser svc_keycloak@mydomain.local -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass DeinSicheresPasswort

Wichtige Parameter:

-princ: SPN im Format HTTP/hostname@REALM
-mapuser: vollständiger Benutzername im AD
-crypto: Verschlüsselungstyp (AES256 empfohlen)

💡 Wichtig: Da das Keytab-File den Zugriff auf das Dienstkonto ermöglicht, sollte sie besonders geschützt werden:
1. Nur lesbar für den Benutzer, unter dem Keycloak läuft.
2. Niemals in Versionskontrolle oder öffentlich zugängliche Speicherorte legen.

Nach Erstellung wird die Datei auf den Keycloak-Server verschoben – z. B. nach /opt/keycloak/conf/keycloak.keytab.

2. Keycloak für Kerberos vorbereiten

Nachdem im Active Directory das Dienstkonto inklusive SPN und Keytab eingerichtet wurde, muss nun die Keycloak-Umgebung für Kerberos vorbereitet werden. Dabei geht es vor allem um zwei Dinge: die Bereitstellung der Keytab-Datei auf dem Server und die Konfiguration der Kerberos-Client-Einstellungen.

Keytab-Datei auf dem Server bereitstellen

Kopiere die zuvor erstellte Keytab-Datei sicher auf den Server, auf dem Keycloak läuft. Ein empfohlener Speicherort ist z. B.:

/opt/keycloak/conf/keycloak.keytab

Passe die Dateiberechtigungen so an, dass nur der Benutzer, unter dem Keycloak läuft, Zugriff hat:

chown keycloak:keycloak /opt/keycloak/conf/keycloak.keytab
chmod 600 /opt/keycloak/conf/keycloak.keytab

Kerberos-Client konfigurieren

Damit Keycloak mit dem Active Directory über Kerberos kommunizieren kann, muss auf dem Server eine gültige Kerberos-Client-Konfiguration vorhanden sein. Diese Dazu legen wir eine Datei krb5.conf an, besipielsweise in /opt/keycloak/conf/.

Die krb5.conf ist sozusagen die Landkarte für den Kerberos-Client. Sie definiert:

Welches Kerberos-Realm (z. B. DOMAIN.LOCAL) verwendet wird
Welche KDCs (Key Distribution Center) zuständig sind
Wie Domainnamen dem Realm zugeordnet werden sollen

Ohne diese Informationen kann Keycloak keine Kerberos-Tickets anfordern – die Datei ist also unverzichtbar.

Beispiel für /opt/keycloak/krb5.conf

[libdefaults]
 default_realm = mydomain.local

[realms]
 mydomain.local = {
  kdc = adserver.domain.local
  admin_server = adserver.domain.local
 }

[domain_realm]
 .mydomain.local = mydomain.local
 mydomain.local = mydomain.local

💡 Hinweis: Achte darauf, dass der Hostname (adserver.domain.local) mit dem tatsächlichen AD-Server übereinstimmt. Falls dein AD mehrere Domänencontroller hat, kannst du hier auch mehrere KDCs eintragen

💡 Nicht wundern: Die krb5.conf sieht vielleicht etwas seltsam aus – man „mappt“ scheinbar ständig dieselbe Domäne auf sich selbst. Aber keine Sorge: Das ist genau so gedacht. Damit weiß der Kerberos-Client, welches Realm zu welcher Domain gehört – auch bei Subdomains oder abweichenden Hostnamen

Java-Optionen für Keycloak

Damit Keycloak die krb5.conf findet und bei Problemen detaillierte Debug-Ausgaben liefert, musst du folgende Java-Optionen setzen – z. B. in der Datei conf/keycloak.conf:

JAVA_OPTS_APPEND="-Dsun.security.krb5.debug=true -Djava.security.krb5.conf=/opt/keycloak/conf/krb5.conf"

krb5.debug=true: Aktiviert detailliertes Logging für Kerberos – sehr hilfreich bei der Fehlersuche
krb5.conf=...: Gibt explizit den Pfad zur Kerberos-Konfigurationsdatei an (falls nicht systemweit verfügbar)

Keytab auf der Konsole testen

Bevor du dich in die Keycloak-Konfiguration stürzt, kannst (und solltest) du testen, ob die Keytab-Datei grundsätzlich funktioniert und ob eine Authentifizierung über Kerberos möglich ist. Zwei Befehle sind dafür besonders hilfreich:

Keytab anzeigen mit klist

sudo klist -K -e -t -k keycloak.keytab

Keytab name: FILE:keycloak.keytab
KVNO Timestamp           Principal
---- ------------------- ------------------------------------------------------
  11 01/01/1970 01:00:00 HTTP/keycloak.mydomain.local@MYDOMAIN.LOCAL (aes256-cts-hmac-sha1-96)

Was zeigt der Befehl?

Ob die Datei korrekt gelesen werden kann
Welche Principals enthalten sind
Welche Verschlüsselung verwendet wird

Kerberos-Ticket anfordern mit kinit

kinit -k -t keycloak.keytab HTTP/keycloak.mydomain.local@MYDOMAIN.LOCAL

Wenn alles korrekt ist, wird kein Fehler ausgegeben, und du kannst anschließend mit klist das erhaltene Ticket anzeigen. Wenn beide Tests erfolgreich sind, steht der Kerberos-Kommunikation nichts mehr im Weg – und wir können sicher sein, dass das Zusammenspiel zwischen Keytab, AD und KDC funktioniert

3. Kerberos-Realms in Keycloak einrichten

Nach der Vorbereitung im Active Directory und auf dem Server ist Keycloak nun bereit, mit dem Kerberos-Protokoll zu arbeiten. Dazu wird in Keycloak ein sogenannter Benutzerföderations-Provider vom Typ „Kerberos“ eingerichtet. Dieser sorgt dafür, dass sich Benutzer:innen aus dem AD mit ihren gewohnten Windows-Anmeldedaten authentifizieren können – ohne dass sie in Keycloak manuell angelegt werden müssen.

Kerberos-Provider hinzufügen

In der Keycloak-Admin-Konsole gehst du zu:

Benutzer → Benutzer-Föderation → „Kerberos“ → „Hinzufügen“

Die Einstellungen sind in der Benutzeroberfläche größtenteils selbsterklärend. In den Screenshots unten findest du eine vollständige Beispielkonfiguration, an der du dich orientieren kannst.

Ein paar Hinweise zu wichtigen Feldern:

„Benutzername LDAP Attribut“ sollte in den meisten Fällen auf sAMAccountName gesetzt sein – das entspricht dem üblichen Windows-Anmeldenamen.
„Benutzer importieren“ bestimmt, ob beim ersten Login automatisch ein Benutzer in Keycloak angelegt wird.
→ Auf diesen Punkt gehen wir im letzten Kapitel noch einmal genauer ein.

Wenn du alle Felder ausgefüllt hast, speichere die Konfiguration. Die Verbindung wird nun aktiv und kann getestet werden.

4. Authentifizierungsfluss anpassen

Nachdem der Kerberos-Provider eingerichtet ist, funktioniert die Authentifizierung technisch bereits – allerdings nur, wenn man den passenden Login-Flow nutzt. Wenn du willst, dass sich Benutzer automatisch anmelden können (z. B. ohne Eingabe von Benutzername und Passwort im Intranet), musst du den Authentifizierungsfluss in Keycloak entsprechend anpassen.

Browser-Authentifizierungsfluss anpassen

Damit SPNEGO in Keycloak greift, musst du den Browser-Flow im jeweiligen Realm anpassen:

Gehe zu Authentication → Flows
Erstelle eine Kopie des bestehenden Flows „Browser“ (z. B. „Browser mit SPNEGO“)
Bearbeite diesen Flow und setze den Step „Kerberos“ auf „Alternative“
Setze diesen Flow als neuen Standard indem du ihn als browser-flow bindest

Browser vorbereiten

Damit SPNEGO im Browser funktioniert, müssen die meisten Clients vertrauenswürdige Sites definieren, bei denen SPNEGO verwendet werden darf.

Beispiel: Firefox

In about:config:

network.negotiate-auth.trusted-uris = keycloak.mydomain.local

Beispiel: Chrome (und Edge Chromium)

Verwendet die Systemkonfiguration (Internetoptionen → Intranetzone), oder über Gruppenrichtlinien:

AuthServerWhitelist = keycloak.mydomain.local

Test & Verhalten prüfen

Wenn alles korrekt eingerichtet ist:

AD-Benutzer meldet sich an seinem Windows-PC an
Ruft Keycloak im Browser auf
Wird ohne Passwortabfrage automatisch angemeldet

Falls nicht, hilft ein Blick in:

Den Keycloak-Log
Das Browser-Log / DevTools
klist am Client – ist ein gültiges Ticket vorhanden?