Keycloak als OIDC-Provider im Kubernetes-Cluster – Zentrales Identity Management in der Praxis

Keycloak als OIDC-Provider – Zentrales Identity Management

Kaum eine moderne Plattform kommt ohne durchdachtes Identity Management aus. Besonders in Kubernetes-Umgebungen ist es wichtig, Authentifizierung und Rechteverwaltung frühzeitig zentral zu organisieren. In diesem Artikel zeigen wir, wie sich Keycloak als OIDC-Provider einsetzen lässt – für einheitliches Login, klare Rollenverteilung und nahtlose Integration über alle Services hinweg.

Vorwort zu Keycloak

Keycloak ist eine Open-Source-Lösung für moderne Anforderungen an Authentifizierung und Autorisierung – mit vollständiger Unterstützung für OpenID Connect (OIDC), OAuth2 und SAML.

Der Fokus liegt auf einfacher Integration, zentralem User-Management und sicherem Zugriff über Rollen, Gruppen und Policies. Ob Single Sign-On, Identity Brokering oder Federation: Keycloak bringt alle notwendigen Features mit – vollständig containerisiert und cloud-native einsetzbar.

Die vollständige Dokumentation findet sich unter: www.keycloak.org/documentation

Falls du Keycloak noch nicht in einem Kubernetes-Cluster installiert hast:
Hier geht’s zur Anleitung: Wie wir mit Keycloak eine User Federation für unseren Cluster aufbauen

Keycloak Admin anlegen

Wenn Keycloak zum ersten Mal verwendet wird, startet man mit einem temporären Admin-User. Das bedeutet: Als Erstes sollten wir einen echten Administrator anlegen.

Disclaimer
Die Konfiguration kann je nach Anforderung variieren – manche Entscheidungen hängen vom persönlichen Geschmack ab, andere sind technisch notwendig. Wenn bestimmte Einstellungen zwingend erforderlich sind, weisen wir explizit darauf hin. Ansonsten können die Werte flexibel gewählt werden.

Wir navigieren zu Users > Add user und legen einen neuen User an, zum Beispiel mit den folgenden Einstellungen:

Nach dem Klick auf Create setzen wir ein Passwort unter Users > Credentials. Wir deaktivieren die Option “ Temporary”, da es sich um einen technischen User handelt – also einen Root-User, den wir später nur noch selten einsetzen. Die eigentliche Administration erfolgt künftig über dedizierte Realms mit eigenen Admins.

Zuletzt müssen wir dem User Admin-Rechte zuweisen. Dafür vergeben wir die Rolle admin des Master-Realms. Damit haben wir effektiv einen Root-User erstellt.

Dazu navigieren wir zu Users > keycloak-admin > Role Mappings > Assign Role:

Dann filtern wir über Filter by Clients > Filter by realm roles, um nur die Rollen des aktuellen Realms (master) anzuzeigen:

Wir wählen die Rolle admin aus und klicken auf Assign:

Jetzt wechseln wir den User. Wir loggen uns aus und melden uns mit dem neu erstellten Keycloak-Admin wieder an. Danach kann der temporäre User gelöscht werden.

⚠️ Wichtig: Es handelt sich hierbei um den Root-User. Er besitzt vollständige Rechte über alle User, Realms und Clients, die künftig eingerichtet werden. Das Passwort dieses Users sollte unbedingt sicher aufbewahrt werden.

Realm anlegen

Realms sind die oberste organisatorische Einheit in Keycloak. Innerhalb eines Realms können beliebig viele User und Clients verwaltet werden. Wir können Realms nutzen, um unsere Organisation logisch zu strukturieren – zum Beispiel durch eigene Realms für Abteilungen oder Projekte. Ob und wie man Realms trennt, ist eher eine strategische als eine technische Entscheidung.

In unserem Fall legen wir einen einzigen Realm für das gesamte Projekt an: k3s-platform.

Da Keycloak auch den Import per JSON-Datei erlaubt, nutzen wir diese Möglichkeit, um uns ein paar Klicks zu sparen:

{
  // Technischer Name des Realms (interne ID)
  "id": "k3s-platform",
  // Anzeigename des Realms
  "realm": "k3s-platform",
  // Aktiviert den Realm
  "enabled": true,
  // Optionaler Titel zur Anzeige im Admin UI
  "displayName": "K3s Platform",
  // SSL-Anforderung (z. B. "external", "all", "none")
  "sslRequired": "external",
  // Deaktiviert die öffentliche Selbstregistrierung
  "registrationAllowed": false,
  // Login via E-Mail erlauben
  "loginWithEmailAllowed": true,
  // User dürfen ihr Passwort zurücksetzen
  "resetPasswordAllowed": true,
  // Aktiviert Lokalisierung im Login-UI
  "internationalizationEnabled": true,
  // Standardsprache für das Realm-UI
  "defaultLocale": "en",
  // Unterstützte Sprachen
  "supportedLocales": [
    "en",
    "de"
  ],
  // Definierte Gruppen mit zugewiesenen Rollen
  "groups": [
    {
      // Gruppe mit Adminrechten
      "name": "platform-admins",
      // Zuweisung der Client-Rolle 'realm-admin' aus dem System-Client 'realm-management'
      "clientRoles": {
        "realm-management": [
          "realm-admin"
        ]
      }
    }
  ],
  // User, die beim Import automatisch erstellt werden
  "users": [
    {
      // Username
      "username": "user-admin",
      // User ist aktiv
      "enabled": true,
      // Vorname (optional)
      "firstName": "Admin",
      // Nachname (optional)
      "lastName": "User",
      // E-Mail-Adresse
      "email": "admin@example.com",
      // E-Mail bereits bestätigt
      "emailVerified": false,
      // Zugewiesene Gruppen
      "groups": [
        "platform-admins"
      ]
    }
  ]
}

Bei den einzelnen Werten muss man sich nicht verrückt machen – alles kann später noch angepasst werden.

Wir haben nun einen neuen Realm mit einem Admin-User und einer Gruppe erstellt. Die Gruppe platform-admins hat durch die zugewiesene Rolle realm-admin Vollzugriff auf den Realm. Alle User, die Mitglied dieser Gruppe sind, erhalten automatisch entsprechende Administratorrechte im Realm:

Einrichtung des E-Mail-Versands

Keycloak kann über ein angebundenes SMTP-Postfach E-Mails versenden. Das ist vor allem praktisch für Aktionen wie „Passwort vergessen“, Account-Aktivierung und andere wichtige Ereignisse. Dazu benötigt man ein eigenes E-Mail-Postfach sowie eine passende Konfiguration. In unserem Fall verwenden wir die Mailserver von IONOS. Je nach Provider müssen die korrekten SMTP-Einstellungen recherchiert und eingetragen werden. Die Konfiguration in der UI ist in der Regel selbsterklärend.

Bei uns sieht das zum Beispiel so aus:

Anschließend gehen wir zu unserem User:
User > Credentials > Credential Reset, wählen dort die Aktionen Update Password und optional Verify Email, und klicken auf Senden.

Der Nutzer erhält nun eine E-Mail mit einem Link zum Setzen seines Passworts. Danach kann er sich als Realm-Administrator unter folgender URL anmelden:

https://your.kecloak.host/auth/realms/k3s-platform/protocol/openid-connect/auth?client_id=security-admin-console

⚠️ Die URL kann je nach Keycloak-Version, Setup und gewähltem Realm-Namen leicht variieren.

Super – wir haben nun einen eigenen Realm mit einem dedizierten Administrator für Keycloak eingerichtet.
Als Nächstes wollen wir OIDC nutzen, um uns auch auf anderen Plattformen authentifizieren zu können.

Gruppen, Rollen und Rechte

Es gibt viele Möglichkeiten, Userrechte in Keycloak zu verwalten. Wir empfehlen, Rollen nicht direkt einzelnen Usern zuzuweisen, sondern über Gruppen zu arbeiten. Direkte Rollenzuweisungen werden mit der Zeit unübersichtlich und sind nur schwer wartbar. Gruppen hingegen stellen abstrakte Berechtigungseinheiten dar – sie bündeln eine oder mehrere Rollen, die einem bestimmten Funktionsbereich oder Verantwortungsniveau zugeordnet sind.

Beispielsweise kann die Gruppe platform-admins die Rolle realm-admin enthalten. Statt jedem User einzeln die Rolle realm-admin zuzuweisen, ordnen wir sie der Gruppe platform-admins zu. Neue User müssen dann nur noch dieser Gruppe zugeordnet werden – das macht die Verwaltung deutlich einfacher und nachvollziehbarer.

Ein weiterer Vorteil: Entfernen wir eine Rolle aus einer Gruppe, verlieren automatisch alle zugewiesenen User dieses Recht – ohne dass wir jeden User einzeln anpassen müssen. Gerade in größeren Teams sorgt das für klare Zuständigkeiten, bessere Skalierbarkeit und ein revisionssicheres Berechtigungsmodell.

Keycloak erlaubt auch hierarchische Gruppenstrukturen, was zusätzliche Flexibilität bietet. So könnte es z. B. eine übergeordnete Gruppe engineering geben, die devs, ops und qa als Untergruppen enthält – jeweils mit eigenen Rollen und Zugriffsrechten.

Das entspricht auch dem Berechtigungskonzept, das Rancher verwendet.

Wenn wir OpenID Connect (alternativ wäre auch SAML möglich – das behandeln wir hier jedoch nicht) einsetzen, hängt es immer vom konsumierenden System ab, welche Einstellungen wir in Keycloak vornehmen müssen. In der Regel müssen sogenannte Mapper konfiguriert werden, die das Token mit zusätzlichen Informationen wie Gruppen oder bestimmten Userattributen anreichern. Alternativ können diese Informationen auch über den UserInfo-Endpoint bereitgestellt werden.

Wir müssen also immer die Dokumentation des jeweiligen Consumers lesen, um genau zu verstehen, welche Konfiguration in Keycloak notwendig ist.

In den folgenden Abschnitten zeigen wir exemplarisch, wie wir die Integration für MinIO und Rancher umsetzen.

Rancher per OIDC anbinden

Wir beginnen damit, einen neuen Client Scope in Keycloak anzulegen. Ein Client Scope ist eine Sammlung von Mappings ( Mappern), die einem Client zugewiesen werden können. Diese Mapper bestimmen, welche Informationen (z. B. Gruppen oder Attribute) im Token enthalten sind.

Man kann entweder pro Client einen eigenen Scope anlegen oder Scopes nach Use Cases gruppieren und mehreren Clients zuweisen. In unserem Fall entscheiden wir uns für einen Use-Case-zentrierten Ansatz und erstellen je Anwendungsfall einen eigenen Scope. Das ist vor allem eine organisatorische Entscheidung – technisch ist nur relevant, dass die richtigen Mapper enthalten und dem Client zugewiesen sind.

Rancher verwendet Gruppen aus Keycloak zur Integration in sein eigenes Rollen- und Rechtesystem. Daher benötigen wir einen Scope, der die Gruppenmitgliedschaften im Token abbildet.

Wir gehen in Keycloak auf Client Scopes > Create client scope und legen unseren Scope an:

Die Einstellungen Protocol und Include in token scope müssen exakt wie gezeigt gesetzt werden – der Name ist frei wählbar.

Nach dem Klick auf Create wechseln wir in den Tab Mappers > Create new Mapper und wählen als Mapper Type den Eintrag Group Membership.

Wir füllen das Formular wie folgt aus:

Wichtig: Nur der Name des Mappers ist flexibel – alle anderen Einstellungen müssen exakt so gesetzt werden, damit Rancher die Gruppen korrekt verarbeiten kann.

---

Anschließend legen wir den eigentlichen Client an. Dazu gehen wir auf Clients > Create client.

Die Konfiguration sieht wie folgt aus:

General settings

• Client Type: OpenID Connect
• Client ID: rancher

Capability Config

• Client Authentication: ON
• Authentication Flow: Standard Flow

Login Settings

• Valid Redirect URIs: https://your.rancher.host/verify-auth

⚠️ Die Rancher-URL muss natürlich durch die tatsächliche Adresse ersetzt werden.

---

Jetzt wechseln wir zu Rancher und melden uns mit einem lokalen Admin-Account an (z. B. admin). Unter Users & Authentication > Auth Provider legen wir einen neuen OIDC-Provider an.

Die Konfiguration sieht so aus:

Configure a Keycloak OIDC account

• Client ID: rancher
• Client Secret: (findet man in Keycloak unter Clients > rancher > Credentials)

Endpoints

• Generate URL: https://keycloakx.osaia.cloud/auth
• Realm: k3s-platform

Wir klicken auf Save – der neue Identity Provider sollte nun aktiv sein.

Ab sofort kann man sich über Keycloak bei Rancher anmelden. Bevor wir jedoch den User wechseln, gehen wir in Rancher zu Users & Authentication > Groups > Refresh Group Memberships > Assign Global Roles.

Dort ordnen wir nun die Gruppe platform-admins aus Keycloak der globalen Rolle Administrator in Rancher zu.

Jetzt loggen wir uns aus Rancher aus. Beim nächsten Login sehen wir nun die Option, uns per OIDC über Keycloak anzumelden:

Perfekt – die Anmeldung über Keycloak funktioniert nun auch für Rancher.

Rancher Rechteverwaltung

Jetzt, da Rancher über Keycloak authentifiziert, können wir die Keycloak-Gruppen direkt zur Rechteverwaltung in Rancher nutzen. Damit lassen sich Zugriffe auf Projekte komfortabel und nachvollziehbar steuern.

Ein Projekt in Rancher ist eine logische Gruppierung von Namespaces. In unserem Fall gibt es z. B. ein Projekt **MLOps **, das die Namespaces knative-serving und kubeflow enthält. Wenn wir möchten, dass nur eine bestimmte Gruppe – etwa platform-admins – Zugriff auf dieses Projekt hat, können wir das einfach im Rancher UI konfigurieren:

In diesem Beispiel haben ausschließlich Mitglieder der Gruppe platform-admins Zugriff auf das Projekt MLOps – inklusive aller enthaltenen Namespaces.

---

Ein weiterer Vorteil: User können sich ihre persönliche kubectl-Konfiguration direkt aus Rancher generieren lassen.

Diese Datei lässt sich dann z. B. unter ~/.kube/config ablegen und mit dem gewohnten kubectl-Befehl verwenden. So arbeitet jeder User mit seinen individuellen Rechten – auch auf der Kommandozeile.

MinIO per OIDC anbinden

Die Anbindung von MinIO erfolgt ähnlich wie bei Rancher: Wir erstellen einen Client Scope sowie einen Client in Keycloak. Die grundlegenden Schritte sind identisch – die Konfiguration unterscheidet sich allerdings, da MinIO einen * *Policy-basierten Ansatz** verfolgt, während Rancher gruppenbasiert arbeitet.

Client Scope erstellen

Zuerst legen wir einen neuen Client Scope an, z. B. mit dem Namen minio-policy. Dieser muss wie folgt konfiguriert werden:

Unter Mappers erstellen wir anschließend einen neuen Mapper vom Typ User Attribute:

Dieser Mapper sorgt dafür, dass ein Userdefiniertes Attribut namens policy im OIDC-Token landet. MinIO wertet dieses Attribut aus und ordnet es einer entsprechenden internen Policy zu.

Beispiel: Wird policy=consoleAdmin gesetzt, erhält der User vollen Admin-Zugriff auf die MinIO-Konsole.

In unserem Setup regeln wir das über Gruppen: Mitglieder der Gruppe minio-admins erhalten das Attribut policy=consoleAdmin. Damit können wir zentral steuern, wer in MinIO welche Berechtigungen erhält:

Client anlegen

Als Nächstes erstellen wir den MinIO-Client in Keycloak:

General Settings:

• Client type: OpenID Connect
• Client ID: minio

Capability Config:

• Client Authentication: On
• Authentication Flow: Standard Flow

Login Settings:

• Valid Redirect URIs: *

Nach dem Speichern fügen wir unter Client Scopes unseren zuvor erstellten Scope (z. B. minio-policy) hinzu.

Damit ist MinIO an Keycloak angebunden – User können sich nun via OIDC anmelden, und ihre Berechtigungen werden anhand des policy-Attributs aus Keycloak vergeben.

MinIO OIDC einrichten

In MinIO gehen wir auf Identity > OpenID Connect > Create OpenID Connect Provider und konfigurieren unseren Provider wie folgt:

Die URL zur OpenID-Konfiguration von Keycloak folgt immer dem gleichen Schema:

https://<KEYCLOAK_HOST>/realms/<REALM_NAME>/.well-known/openid-configuration

Nach dem Speichern können wir uns ausloggen und anschließend über Keycloak wieder anmelden.

MinIO Rechteverwaltung

In MinIO lassen sich beliebig viele Policies definieren. Diese können anhand von Attributen aus dem OIDC-Token gezielt zugewiesen werden – in unserem Fall über das policy-Attribut, das wir zuvor in Keycloak per Mapper definiert haben:

So lässt sich der Zugriff auf Buckets, APIs oder bestimmte Aktionen fein granular steuern – zentral verwaltet über die Userattribute in Keycloak.

Fazit

Keycloak liefert damit genau das, was moderne Plattformen brauchen: eine zentrale, sichere und flexible Authentifizierung – cloud-native, erweiterbar und vollständig unter eigener Kontrolle. Ob für Kubernetes, Rancher oder externe Tools: Einmal eingerichtet, spart das zentrale Usermanagement enorm viel Aufwand – und wächst problemlos mit.

Bildnachweis

📸 Image by Mohamed Hassan from Pixabay

---

Dieser Beitrag wurde erstellt von OSAIA Consulting – Experten für Platform Engineering, Automatisierung und Softwarearchitektur.

💬 Fragen oder Feedback?
Wir freuen uns über den Austausch – schreibt uns jederzeit über unsere Website.