Multi-Tenancy mit Keycloak: Was im Token gehört und was nicht

Mandantenfähigkeit wird meistens als Login-Thema eingekauft und als Architekturthema bezahlt. Der Login ist in zwei Tagen konfiguriert. Die Frage, wer in welchem Kontext was darf, begleitet ein Produkt über Jahre.

Ein Realm oder viele?

Die erste Entscheidung ist auch die teuerste, wenn man sie revidieren muss.

Ein Realm für alle Mandanten ist in den meisten SaaS-Fällen richtig. Mandanten sind dann Gruppen oder Organisationen innerhalb des Realms, die Zugehörigkeit landet als Claim im Token. Vorteile: ein Satz Clients, ein Login-Flow, ein Satz Templates, zentrale Wartung. Nachteil: Isolation ist Modellarbeit, nicht Infrastruktur.

Ein Realm pro Mandant ist dann richtig, wenn Mandanten eigene Identity Provider mitbringen, unterschiedliche Passwort- oder MFA-Richtlinien brauchen oder regulatorisch getrennt sein müssen. Der Preis: Jede Änderung muss über alle Realms ausgerollt werden. Ab etwa zwanzig Mandanten braucht man dafür Automatisierung, sonst wird der Betrieb zur Handarbeit.

Die Zwischenlösung, die in der Praxis gut trägt: ein Realm als Standard, plus einzelne dedizierte Realms für Großkunden mit eigenem IdP.

Was ins Token gehört

Ein Token ist ein Cache mit Ablaufdatum, keine Datenbank. Die Faustregel:

• Ins Token: Identität, Mandantenzugehörigkeit, grobe Rollen, die sich selten ändern. Alles, was jede einzelne Anfrage braucht.
• Nicht ins Token: feingranulare Objektrechte, Freigaben auf Datensatzebene, alles, was sich stündlich ändert. Diese Prüfungen gehören in die Applikation oder eine Policy-Engine.

Der häufigste Fehler ist das Gegenteil: Alle Rechte werden ins Token gepackt, das Token wird groß, Header-Limits werden gerissen, und eine entzogene Berechtigung wirkt erst nach dem nächsten Refresh. Rechte, die sofort greifen müssen, dürfen nicht im Token liegen.

Rollen sauber schneiden

Drei Ebenen reichen fast immer:

1. Plattformrollen — gelten mandantenübergreifend, z. B. Support oder Betrieb. Wenige Personen, streng auditiert.
2. Mandantenrollen — Admin, Mitglied, Gast innerhalb einer Organisation. Das ist die Ebene, die Kunden selbst verwalten sollen.
3. Fachliche Berechtigungen — abgeleitet aus Rollen, geprüft in der Applikation gegen den konkreten Datensatz.

Wenn Rollennamen anfangen, Kundennamen zu enthalten, ist das Modell gekippt. Dann wird nicht mehr modelliert, sondern verwaltet.

Self-Service statt Backoffice

Multi-Tenancy zahlt sich erst aus, wenn das Onboarding eines neuen Kunden kein Ticket mehr ist. Dazu gehören: Organisation anlegen, Admin einladen, Domain verifizieren, Nutzer verwalten, Rollen vergeben — durch den Kunden selbst. Keycloak liefert dafür Bausteine, aber keine fertige Oberfläche. Diese Admin-UI ist Teil des Produkts, nicht ein Nachgedanke.

Migration ohne Big Bang

Bestehende Nutzer werden selten an einem Wochenende umgezogen. Was funktioniert:

• Keycloak als führendes System einführen, das Altsystem übergangsweise als User Storage oder über einen Import-on-first-Login anbinden.
• Passwort-Hashes migrieren, wenn das Format kompatibel ist — sonst einen Reset-Flow mit klarer Kommunikation.
• Applikationen einzeln umstellen, nicht alle gleichzeitig. Jede Umstellung ist eine eigene, rückrollbare Änderung.
• Erst nach der letzten Applikation das Altsystem abschalten.

Was Betrieb bedeutet

Ein Zugriffssystem ist kritische Infrastruktur. Dazu gehören Monitoring auf Login-Fehlerraten und Token-Ausstellung, ein dokumentierter Rotationspfad für Client Secrets und Signing Keys, getestete Backups der Realm-Konfiguration als Code und ein Recovery-Runbook, das jemand im Team schon einmal durchgespielt hat.

Kurzfassung

Realm-Strategie bewusst wählen, Token klein halten, Rollen auf drei Ebenen schneiden, Self-Service als Produktbestandteil bauen und inkrementell migrieren. Wer diese fünf Punkte vor der ersten Zeile Code klärt, spart sich die Sonderfälle, die sonst in jeder Applikation einzeln landen.

Wie wir Mandantenfähigkeit in einem klar abgegrenzten Paket umsetzen, steht unter Keycloak Multi-Tenancy; den technischen Rahmen dazu beschreibt unsere Software-Entwicklung und Delivery.

Mandantentrennung ist der Punkt, an dem Security-Fragebögen und Auditfragen am häufigsten hängen bleiben. Was dabei verlangt wird, steht unter NIS2 und Ihre Software; wo Ihr System heute steht, zeigt der Nachweis-Check.