Keycloak für Kommunen einrichten: in fünf Schritten zum eigenen Identity-Provider

Eine zentrale Anmeldung für alle Fachanwendungen ist kein Großprojekt – mit Keycloak steht das Fundament an einem Nachmittag. Während um digitale Souveränität und Cloud-Abhängigkeiten große Debatten geführt werden, liegt einer der greifbarsten Quick Wins für die kommunale IT seit Jahren bereit: ein quelloffener Identity-Provider, der auf eigener Infrastruktur läuft, das vorhandene Active Directory anzapft und jede moderne Anwendung über Standardprotokolle absichert. Keine Lizenzkosten, kein Vendor-Lock-in, keine Nutzerdaten bei einem Hyperscaler. Dieser Beitrag erklärt, was Keycloak mitbringt, warum es sich gerade für Kommunen lohnt – und führt dann Schritt für Schritt durch die Einrichtung bis zum Produktivbetrieb.

Warum Keycloak – und warum gerade für Kommunen

Keycloak ist ein Open-Source-System für Identity and Access Management, entwickelt mit dem Anspruch, Anwendungen „mit minimalem Aufwand” um Authentifizierung und Absicherung zu ergänzen [1]. Es steht unter der Apache-Lizenz 2.0 [2] und ist als Incubation-Projekt der Cloud Native Computing Foundation organisiert [1] – also kein Hobby-Projekt, sondern Infrastruktur-Software mit breiter Trägerschaft, regelmäßigen Releases und aktiver Sicherheitspflege; die aktuelle Versionslinie ist Keycloak 26 [3].

Was es mitbringt, deckt genau die Liste ab, die eine Verwaltung braucht:

Der eigentliche Gewinn ist dabei strukturell: Jede Fachanwendung mit eigenem Login ist eine zweite, schlechter gepflegte Kopie Ihrer Identitätsverwaltung. Verwaiste Konten nach Personalwechseln, doppelte Passwortpflege, Berechtigungen, die niemand zentral sieht – all das verschwindet, wenn Identitäten an einer Stelle geführt und von dort konsumiert werden. Und weil Keycloak auf eigener Hardware läuft – ob Linux oder nativ auf dem Windows Server im Rathaus-Keller –, bleibt die kommunale Datenhoheit unangetastet.

Voraussetzungen

Für den ersten Aufschlag brauchen Sie erstaunlich wenig:

• Eine Java-Laufzeitumgebung: Die offizielle Anleitung setzt OpenJDK voraus (aktuell OpenJDK 25) [5].
• Die Keycloak-ZIP-Distribution von keycloak.org – sie enthält Start-Skripte für Linux (kc.sh) und Windows (kc.bat) [5].
• Für den Produktivbetrieb später: eine richtige Datenbank, idealerweise PostgreSQL [6] – die in vielen Kommunen ohnehin schon für GIS und Fachverfahren läuft.

Einen Container braucht es ausdrücklich nicht. Die ZIP-Distribution läuft nativ – ein Punkt, der in Umgebungen ohne Container-Plattform den Unterschied zwischen „machen wir” und „vertagen wir” ausmacht.

Schritt 1: Installation und erster Start

ZIP herunterladen, entpacken, in das Verzeichnis wechseln und den Entwicklungsmodus starten [5]:

# Linux/macOS
bin/kc.sh start-dev

# Windows
bin\kc.bat start-dev

Danach öffnen Sie http://localhost:8080/ und legen über das angezeigte Formular den ersten Administrator an; die Admin-Konsole erreichen Sie anschließend unter http://localhost:8080/admin [5].

Zwei Dinge sollten Sie an dieser Stelle wissen: start-dev ist ein reiner Test- und Evaluationsmodus. Er verwendet die eingebaute dev-file-Datenbank, die laut Doku „nur für Entwicklungs-Anwendungsfälle existiert” [6]. Für die Teststellung im Amt ist das perfekt – für den Produktivbetrieb kommen wir in Schritt 5 zur richtigen Konfiguration.

Schritt 2: Einen Realm anlegen

Ein Realm ist die oberste Organisationseinheit in Keycloak: Er „verwaltet eine Menge von Benutzern, Credentials, Rollen und Gruppen”, und Realms sind voneinander isoliert [4]. Der mitgelieferte master-Realm bleibt der Verwaltung von Keycloak selbst vorbehalten – für Ihre Anwendungen legen Sie einen eigenen an, etwa verwaltung.

Das ist in der Admin-Konsole ein Dreizeiler: Realm-Auswahl oben links → „Create realm” → Name vergeben. Alles Weitere – Benutzer, Clients, Rollen – spielt sich ab jetzt in diesem Realm ab.

Schritt 3: Active Directory anbinden

Hier entsteht der eigentliche Mehrwert. Keycloak bringt einen LDAP/Active-Directory-Provider von Haus aus mit: Sie können einen oder mehrere Verzeichnisdienste in einem Realm föderieren und die LDAP-Attribute auf das Keycloak-Benutzermodell mappen; importierte Benutzer werden on-demand oder per periodischem Hintergrund-Task synchronisiert [4].

In der Praxis heißt das: Unter „User federation” einen LDAP-Provider anlegen, Verbindungsdaten zum Domain Controller eintragen (Vendor „Active Directory”, Bind-Konto mit Lesezugriff, Basis-DN der Benutzer), Verbindung testen, Synchronisation starten. Danach tauchen Ihre AD-Benutzer im Realm auf – das AD bleibt führendes System, Keycloak ist nur die Vermittlungsschicht.

Zwei Praxis-Hinweise, die später Ärger ersparen:

• Lese-Modus genügt. Für den Standardfall „AD-Konten im Portal nutzen” braucht Keycloak keinen Schreibzugriff auf das Verzeichnis.
• Synchronisation explizit testen. Klären Sie, ob Benutzer importiert und periodisch synchronisiert werden [4], und spielen Sie den Fall „Mitarbeiterin wechselt die Abteilung” einmal durch, bevor es jemand im Echtbetrieb tut.

Schritt 4: Die erste Anwendung als OIDC-Client anbinden

Clients sind in Keycloak die Anwendungen, die um Authentifizierung bitten [4]. Für eine Web-Anwendung legen Sie einen OpenID-Connect-Client an – und konfigurieren ihn nach aktuellem Stand der Technik:

1. Authorization-Code-Flow mit PKCE. Die OAuth-Security-Best-Practice RFC 9700 (Januar 2025) verlangt PKCE für Public Clients – also für alles, was im Browser läuft – verbindlich [7]. Der früher übliche Implicit Flow ist abgewählt [7].
2. Exakte Redirect-URIs. Keine Wildcards – je spezifischer die erlaubten Rücksprungadressen, desto schwerer die Client-Imitation [8].
3. Rollen je Anwendung. Keycloak unterscheidet Realm-Rollen und Client-Rollen – einen der Anwendung gewidmeten Rollen-Namespace [4]. Legen Sie die Berechtigungen der Anwendung als Client-Rollen an und weisen Sie sie Gruppen statt Einzelpersonen zu [4]: AD-Gruppe → Rolle → Recht. Diese Berechtigungsmatrix gehört schriftlich dokumentiert – sie ist Ihr Audit-Nachweis.

Damit steht die Kette komplett: Eine Sachbearbeiterin meldet sich mit ihrem ganz normalen Windows-Passwort an, Keycloak prüft gegen das AD, die Anwendung bekommt ein Token mit genau den Rollen, die ihre AD-Gruppen hergeben.

Schritt 5: Produktivbetrieb – die Härtungs-Checkliste

Vom Testaufbau zum Echtbetrieb sind es fünf Punkte:

1. Richtige Datenbank. PostgreSQL gehört zu den offiziell unterstützten Datenbanken; die Umstellung ist eine Konfigurationszeile (db=postgres plus Verbindungsdaten) [6]. Datenbank-Passwörter gehören dabei in die Konfigurationsdatei oder einen Keystore, nicht auf die Kommandozeile [6].
2. HTTPS überall. Keycloak tauscht permanent sensible Daten aus – die gesamte Kommunikation von und zu Keycloak braucht einen gesicherten Kanal [9]. In der Praxis heißt das: TLS-Zertifikat und meist ein Reverse Proxy davor, wie ihn Produktionsumgebungen üblicherweise ohnehin vorsehen [9].
3. Admin-Zugang trennen. Die offizielle Produktions-Anleitung empfiehlt, Administrations-Oberfläche und -API unter einem anderen Hostnamen oder Pfad zu betreiben als die öffentlichen Anmelde-Endpunkte – das verkleinert die Angriffsfläche [9].
4. Token-Lebensdauern begrenzen. Der über die BSI-Website veröffentlichte benutzerdefinierte Grundschutz-Baustein „IAM Dienst Keycloak” empfiehlt als SOLLTE-Anforderungen, Access- und Refresh-Token-Lebensdauern zu begrenzen, Authorization Codes nur wenige Sekunden gültig zu halten und Access Tokens nur die Rollen des jeweils anfragenden Clients mitzugeben [8].
5. Abmeldung zu Ende denken. Login bauen alle, Logout vergessen viele. OIDC definiert dafür RP-Initiated Logout (die Anwendung meldet den Nutzer am Provider ab) und Back-Channel Logout (der Provider informiert alle angebundenen Anwendungen direkt) [10] [11] – beides gehört in den Testplan, ebenso der Fall „AD-Konto deaktiviert → Zugriff endet sofort”.

Wer diese fünf Punkte abhakt, betreibt keinen Bastelaufbau mehr, sondern einen Identity-Provider, der ein IT-Sicherheits-Audit übersteht.

Und das Geoportal?

Für GISRede ist Keycloak ein möglicher Baustein unter dem kommunalen Geoportal: Das Masterportal bringt die OIDC-Anbindung von Haus aus mit – in der config.js ist ein login-Modul mit den Keycloak-Endpunkten dokumentiert, und weil das Modul optional ist, bleibt der freie Bürgerzugang erhalten [12]. Sobald Keycloak steht, ist die Anbindung von Auskunftsportal, geschützten Layern und Eigentümerdaten der logische nächste Schritt – warum genau diese Architektur auch ein Sicherheits- und Compliance-Thema ist und wie die Berechtigungsmatrix dahinter aussieht, zeigt der Beitrag Keycloak und SSO im kommunalen Geoportal.

Fazit

Keycloak ist einer der seltenen Fälle, in denen der strategisch richtige Weg auch der pragmatisch einfache ist: ein etabliertes Open-Source-Projekt unter Apache-Lizenz [2], das auf eigener Infrastruktur läuft, das vorhandene Active Directory weiterverwendet statt es zu ersetzen [1], und das sich an einem Nachmittag so weit aufsetzen lässt, dass die erste Anwendung dagegen authentifiziert. Der Quick Win liegt nicht in einem Beschaffungsverfahren, sondern in einer Teststellung: ZIP entpacken, Realm anlegen, AD anbinden – und dann mit einer echten Anwendung erleben, wie sich „ein Login für alles” anfühlt.

GISRede setzt diese Kette – Keycloak, AD-Federation, OIDC-Clients, rollenbasierte Geoportal-Auskunft – in kommunalen Kontexten um — auf Windows Server, Linux oder Kubernetes. Wenn Sie eine Teststellung oder eine zweite Meinung zur Architektur wollen: Sprechen Sie Chris Redekop an.

Quellen

• [1] Keycloak – Open Source Identity and Access Management (Projektseite)
• [2] Keycloak auf GitHub – Apache License 2.0
• [3] Keycloak 26.6.3 released (Keycloak-Projekt, 04.06.2026)
• [4] Keycloak Server Administration Guide (Keycloak-Projekt)
• [5] Keycloak Getting Started: OpenJDK / ZIP-Distribution (Keycloak-Projekt)
• [6] Keycloak Server Guide: Configuring the database (Keycloak-Projekt)
• [7] RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, BCP 240)
• [8] Benutzerdefinierter IT-Grundschutz-Baustein APP.bd.3 „IAM Dienst Keycloak” (PDF, via BSI)
• [9] Keycloak Server Guide: Configuring Keycloak for production (Keycloak-Projekt)
• [10] OpenID Connect RP-Initiated Logout 1.0 (OpenID Foundation)
• [11] OpenID Connect Back-Channel Logout 1.0 (OpenID Foundation)
• [12] Masterportal-Dokumentation: config.js, Modul „login” (masterportal.org)