Im Bereich des Identity and Access Management (IAM) zeichnet sich Keycloak als eine leistungsstarke Open-Source-Lösung aus. Dennoch kann die Verwaltung der Konfiguration – insbesondere in komplexen, mandantenfähigen Umgebungen – schnell zu einem erheblichen Engpass werden. Manuelle Änderungen über die Benutzeroberfläche, oft auch als „Click-Ops“ bezeichnet, führen zu inkonsistenten Umgebungen, mangelnder Auditierbarkeit und einem hohen betrieblichen Aufwand. Mandantenfähige SaaS-Anwendungen stehen vor einer kritischen Herausforderung: Wie lassen sich hunderte oder tausende von Kunden effizient und sicher anlegen (Onboarding), wenn jeder von ihnen einen eigenen, isolierten Bereich für das Identitätsmanagement benötigt? Manuelle „Click-Ops“ in Keycloak sind schlichtweg nicht skalierbar, da die Verwaltung mehrerer Realms für verschiedene Mandanten die Performance beeinträchtigt und die Komplexität erhöht. Hier kommt der KTA (Keycloak Tenant Accelerator) ins Spiel – eine umfassende Demonstration, wie GitOps-Prinzipien in Kombination mit dem Tool keycloak-config-cli das Mandanten-Onboarding transformieren können. Dieser Ansatz automatisiert einen ehemals manuellen Engpass und verwandelt ihn in einen vollständig automatisierten, auditierbaren und skalierbaren "Configuration as Code“ (CaC)-Prozess. Durch die Nutzung eines GitOps-Workflows ist jede Konfigurationsänderung versionskontrolliert und nachvollziehbar. Dies ermöglicht es Teams, konsistente Keycloak-Setups über verschiedene Umgebungen hinweg mit vollem Vertrauen bereitzustellen.

1. Die traditionelle Herausforderung: „Click-Ops“ in Keycloak und Versionierung

Die manuelle Verwaltung von Keycloak ist ein typischer Ausgangspunkt, bringt jedoch einige Herausforderungen mit sich, die mit zunehmender Größe deiner Anwendung wachsen.

Fehlende Versionierung: Es gibt keine einfache Möglichkeit nachzuvollziehen, wer was wann geändert hat. Das Zurückrollen einer fehlerhaften Änderung ist ein schwieriger und fehleranfälliger Prozess.
Inkonsistenz der Umgebungen: Eine Konfiguration exakt aus einer Entwicklungsumgebung in eine Produktionsumgebung zu replizieren, ist fast unmöglich. Das führt zum gefürchteten "Auf meiner Maschine funktioniert's“-Syndrom.
Skalierungsprobleme: Das manuelle Onboarding neuer Tenants oder Services ist eine zeitaufwendige, repetitive Aufgabe, die nicht skaliert.

Keycloaks Admin-Konsole mit einem mühsamen, mehrstufigen Prozess zur manuellen Erstellung und Konfiguration von Realms.

Diese Probleme verdeutlichen den Bedarf an einem systematischen, automatisierten und auditierbaren Ansatz für die Verwaltung der Keycloak-Konfiguration.

2. Keycloak-config-cli: Dein Schlüssel zu deklarativem Keycloak-Management

Genau hier wird das Open-Source-Tool adorsys/keycloak-config-cli unverzichtbar. Es ist ein Java-basiertes Befehlszeilen-Utility, das entwickelt wurde, um Keycloak-Konfigurationen deklarativ zu verwalten.

Kernphilosophie: Das Tool arbeitet nach einem einfachen, aber mächtigen Prinzip: Der Zustand deines Keycloak-Realms sollte exakt dem in deinen Konfigurationsdateien definierten Zustand entsprechen. Du definierst alles – Realms, Clients, Rollen, Benutzer, Authentifizierungs-Flows – in YAML- oder JSON-Dateien, und das CLI kümmert sich um die notwendigen API-Aufrufe an Keycloak, um diesen Zustand herzustellen.
Hauptmerkmale:
- Idempotente Ausführung: Du kannst das CLI mehrfach mit derselben Konfigurationsdatei ausführen, und es werden nur dann Änderungen angewendet, wenn eine Abweichung (Drift) zwischen deiner Datei und dem aktuellen Keycloak-Zustand vorliegt.
- Configuration as Code (CaC): Indem du deine YAML/JSON-Dateien in Git speicherst, erhältst du eine vollständige Versionierung, Peer-Reviews für Änderungen (Pull Requests) und eine lückenlose Historie aller Audits.
- Mächtige Variablen-Substitution: Das Tool ermöglicht die Verwendung von Variablen in deinen Konfigurationsdateien, was es perfekt für die Erstellung wiederverwendbarer Templates macht. Es kann Werte aus Umgebungsvariablen, Property-Dateien und mehr ersetzen.
- Keine Neustarts erforderlich: Änderungen werden live über die Admin-API von Keycloak angewendet, was bedeutet, dass keine Ausfallzeiten entstehen.

Keycloak-config-cli: your Key to Declarative Keycloak Management de

3. Das KTA-Projekt: Automatisiertes Tenant-Onboarding im großen Stil

Das Projekt Keycloak Tenant Accelerator (KTA) zeigt exakt, wie ein echtes SaaS-Unternehmen den kompletten Lebenszyklus des Tenant-Onboardings automatisieren kann. Stellen wir uns ein Projektmanagement-SaaS namens „ConnectFlow“ vor, das Unternehmen wie „x-company“ als isolierte Tenants onboarden muss.

Die geschäftliche Herausforderung: Wenn sich ein neuer Tenant für die Dienste von ConnectFlow registriert, benötigt er: Einen eigenen isolierten Identity-Realm ({{TENANT_ID}}) Sichere Web- und API-Clients ({{TENANT_ID}}-webapp, {{TENANT_ID}}-api) Rollenbasierte Zugriffskontrolle (RBAC: tenant_admin, tenant_user) Benutzerdefinierte Sicherheitsrichtlinien und Branding Ein erstes Administrator-Konto für den Einstieg
Dies für jeden neuen Kunden manuell zu erledigen, ist nicht tragbar. Das KTA-Modell automatisiert diesen gesamten Prozess.
Architektur-Deep-Dive: Von der Registrierung zum laufenden Realm Der im KTA-Projekt demonstrierte Workflow umfasst folgende Schritte:
- Tenant Signup API: Ein neuer Tenant füllt ein Registrierungsformular aus, das das Flask-Backend unter /api/tenants/signup aufruft.
- Konfigurationsgenerierung: Das Backend liest das Master-Template tenant-template.yaml ein, ersetzt die Tenant-spezifischen Werte und generiert {{TENANT_ID}}.yaml.
- GitOps-Trigger: Die neue Konfigurationsdatei wird automatisch committet und in das Git-Repository gepusht.
- CI/CD-Aktivierung: GitHub Actions erkennt die neue Datei und löst die Deployment-Pipeline aus.
- Sofortiges Ergebnis: Der dedizierte Realm des Tenants wird erstellt und steht dem Team sofort zur Verfügung.

Dieser gesamte Prozess dauert Minuten, nicht Stunden oder Tage manueller Konfiguration.

The KTA Project: Automated Tenant Onboarding at Scale de

4. Der template-gesteuerte Ansatz: Configuration as Code im großen Stil

Die Stärke des KTA-Systems liegt in seinem template-gesteuerten Ansatz zur Generierung von Tenant-Konfigurationen. Anstatt das Setup für jeden Tenant manuell zu erstellen, beginnt alles mit einer Master-Vorlage. Das Master-Template (_templates/tenant-template.yaml) definiert die vollständige Struktur eines Keycloak-Realms mithilfe von Platzhaltervariablen.

Wie das Template-System funktioniert: Wenn sich ein Tenant mit der ID acme_corp und dem Namen „ACME Corporation“ registriert, sieht das generierte Template wie folgt aus:

Achte darauf, wie jedes Element auf den spezifischen Tenant zugeschnitten ist:
- Realm-Isolierung: Jeder {{TENANT_ID}}-Realm ist komplett von anderen Tenants getrennt.
- Eigene Anwendungen: {{TENANT_ID}}-webapp und {{TENANT_ID}}-api gehören ausschließlich diesem Tenant.
- Tenant-bezogene Tokens: JWT-Tokens enthalten tenant_id: "{{TENANT_ID}}"-Claims für die Autorisierung auf Anwendungsebene.
- Sicherheitsrichtlinien: Jeder Tenant kann eigene Kennwortanforderungen und Session-Timeouts haben.
Dieses Maß an Isolierung stellt sicher, dass Benutzer, Anwendungen und Daten der einzelnen Tenants auf demselben Keycloak-Server strikt voneinander getrennt bleiben.

5. CI/CD-Pipeline: Von der Konfiguration bis zum Deployment

Unser GitHub Actions-Workflow automatisiert den gesamten Prozess von der Änderung der Tenant-Konfiguration bis zur Bereitstellung in Keycloak. Dies gewährleistet Konsistenz und Zuverlässigkeit über alle Tenant-Deployments hinweg.

Die Pipeline im Detail:

Konfigurationserkennung: Überwacht Änderungen in den Dateien unter keycloak-configs/tenants/*.yaml, um den Deployment-Prozess zu starten.
Validierungsprozess: Prüft die YAML-Syntax und die Struktur der Tenant-Konfiguration, bevor fortgefahren wird.
Deployment-Orchestrierung: Übernimmt die Anwendung der Konfiguration über das Keycloak Config CLI inklusive ordnungsgemäßer Fehlerbehandlung.

Diese Automatisierung liefert starke Ergebnisse und ermöglicht ein nahtloses Tenant-Management:

Tool-Logs, die die erfolgreiche Erstellung und Aktualisierung von Realms zeigen.

Beispiel-CI-Setup für die Produktion:

Dieses Setup bietet ein robustes Fundament für die Verwaltung mehrerer Tenants über die Versionskontrolle. Die Pipeline stellt sicher, dass Konfigurationsänderungen ordnungsgemäß validiert und angewendet werden – inklusive automatischem Rollback im Fehlerfall.

6. Evolution: Keycloak Organizations – Die Zukunft der Multi-Tenancy

Die Organisations-Revolution

Während der oben gezeigte Ansatz („Ein Realm pro Tenant“) eine hervorragende Isolierung bietet, führt Keycloak ab Version 26+ ein bahnbrechendes Feature ein: Organizations. Diese native Multi-Tenancy-Lösung bietet einen skalierbareren und effizienteren Ansatz zur Verwaltung mehrerer Mandanten innerhalb eines einzigen Realms.

Realm-per-Tenant vs. Organizations: Ein umfassender Vergleich

Das KTA-System verwaltet Keycloak-Organisationen über einen vollständig deklarativen, GitOps-gesteuerten Workflow. Dieser Ansatz verzichtet auf direkte API-Aufrufe zur Erstellung von Organisationen und setzt stattdessen auf dieselbe leistungsstarke keycloak-config-cli-Methodik, die auch für das Realm-pro-Mandant-Management verwendet wird. Das Ergebnis ist ein einziger, konsistenter und auditierbarer Prozess für alle Multi-Tenancy-Modelle.

Diese neue Architektur ist einfacher und robuster. Die einzige Aufgabe des Backends besteht darin, eine vollständige Konfigurationsdatei aus einer Vorlage zu generieren (zu rendern) und diese in Git zu committen. Die CI/CD-Pipeline übernimmt anschließend die deklarative Bereitstellung.

KTA Organization: Deklarativer GitOps-Flow

Der Kern dieses neuen Ansatzes ist eine Reihe von in sich geschlossenen Konfigurationsdateien, die deinen gewünschten Zustand abbilden – das ist einfach genial.

1. Das Organizations-Realm-Template (`_templates/organizations-realm-template.yaml`)

Zuerst wird ein Basis-Realm definiert, der alle Organisationen beherbergt. Dies ist eine einmalige Einrichtung.

2. Das Jinja2-Organisations-Template (`_templates/organization-template.yaml.j2`)

Dies ist die Master-Vorlage für eine einzelne Organisation. Es handelt sich um eine .j2-Datei (Jinja2-Template), was Konflikte mit YAML-Lintern verhindert. Das Backend rendert dieses Template, um eine fertige YAML-Datei zu erzeugen.

3. Die generierte Konfiguration (`organizations/acme-corp.yaml`)

Wenn sich ein Benutzer registriert, generiert das Backend eine vollständige, eigenständige YAML-Datei wie diese. Beachte, dass sie den Ziel-Realm (kta-organizations) angibt und alle notwendigen Details der Organisation enthält.

4. CI/CD-Pipeline (`.github/workflows/apply-organizations-config.yaml`)

Der GitHub Actions-Workflow ist jetzt extrem schlank. Er triggert bei einem Push in das organizations-Verzeichnis und führt ein einziges Skript aus.

5. Zusammenfassung des neuen Ansatzes

Dieser rein deklarative GitOps-Workflow bietet immense Vorteile:
- Single Source of Truth: Das Git-Repository ist die unbestrittene Quelle der Wahrheit für alle Organisationskonfigurationen.
- Prüfbarkeit (Auditability): Jede Änderung ist ein Git-Commit. Das liefert eine lückenlose Historie darüber, wer was wann geändert hat.
- Konsistenz: Überall werden dieselben Skripte und Container für das Deployment verwendet, was Abweichungen zwischen den Umgebungen ausschließt.
- Einfachheit: Die Logik ist geradlinig und leicht verständlich. Es gibt kein komplexes Merging oder direkte API-Aufrufe in Shell-Skripten.

6. Wann man Organizations vs. Realm-per-Tenant nutzt

7. Migrationsstrategie: KTA-Methodik + Organizations

Das KTA-Projekt zeigt, wie Organisationen schrittweise von einem "Realm-pro-Tenant"-Modell auf das neue Organizations-Feature migrieren können:

Von Realms zu Organizations.

8. Ressourcen zur Demonstration

Um diese Lösung in deiner eigenen Umgebung zu implementieren, wirf einen Blick auf diese Schlüsselressourcen:

Setup und Installation

Konfigurationsbeispiele

9. Zukünftige Erweiterungen, Performance- und Skalierungsüberlegungen

Multi-Environment-Support, erweiterte Validierung, Monitoring und Reporting

Umgebungsspezifische Konfigurationstemplates
Automatisierte Umgebungserkennung und dynamischer Konfigurationswechsel
Integration mit Secrets-Management-Systemen von Cloud-Anbietern
Benutzerdefinierte Validierungsregeln für Tenant-Konfigurationen
Benachrichtigungen über den Deployment-Status
Erfassung von Performance-Metriken
Caching-Strategien für wiederkehrende Konfigurationen
Inkrementelle Updates im Vergleich zu vollständigen Deployments

10. Best Practices und praktische Tipps

Versionskontrolle
- Nutze Semantic Versioning (SemVer) für deine Konfigurationen.
- Führe ein Changelog.
- Etabliere Review-Prozesse (Pull Requests) für Konfigurationsänderungen.
Sicherheit
- Regelmäßige Sicherheitsaudits durchführen.
- Das Prinzip der geringsten Rechte (Principle of Least Privilege) anwenden.
- Sichere Speicherung von sensiblen Konfigurationsdaten.

Beispiel für eine sichere Konfiguration:

Wartung
- Regelmäßige Backup-Verfahren einrichten.
- Monitoring und Alerting aufsetzen.
- Dokumentation kontinuierlich aktualisieren.

11. Zusätzliche Ressourcen und weiterführende Links

Für alle, die noch tiefer einsteigen möchten, sind hier einige wertvolle Ressourcen:

What is ClickOps, and How Can You Prevent It?: https://blog.equinix.com/blog/2022/12/01/what-is-clickops-and-how-can-you-prevent-it/
Fairness in multi-tenant systems: https://aws.amazon.com/builders-library/fairness-in-multi-tenant-systems/
Keycloak configuration change management discussion: https://github.com/keycloak/keycloak/discussions/19782
All Keycloak Configuration: https://www.keycloak.org/server/all-config
Keycloak 26.x documentation: https://www.keycloak.org/docs/latest/release_notes/index.html#keycloak-26-1-0
What is GitOps: https://about.gitlab.com/topics/gitops/

12. Fazit

Die Implementierung einer automatisierten Keycloak-Tenant-Konfiguration mittels GitHub Actions stellt einen bedeutenden Fortschritt bei der Verwaltung von Multi-Tenant-Umgebungen dar. Diese Lösung rationalisiert nicht nur den Bereitstellungsprozess, sondern sorgt auch für Konsistenz, Sicherheit und Skalierbarkeit. Durch die Beachtung von Best Practices und zukünftigen Erweiterungen können Unternehmen ein robustes und effizientes Tenant-Managementsystem aufbauen.

Vielen Dank, dass du bis zum Ende durchgehalten hast! Ich hoffe, dieser Deep Dive inspiriert dich dazu, neue Wege zur Modernisierung deiner eigenen Projekte zu gehen. Du bist herzlich eingeladen, zum Projekt beizutragen, deine Erfahrungen zu teilen oder dich bei Fragen zu melden. Gemeinsam können wir die Art und Weise, wie wir Identitäten und Zugriffe in unseren Anwendungen verwalten, weiter verbessern und weiterentwickeln.