Bring your own IdP

Die kurzlebige Admin-kubeconfig ist ideal für Bootstrap, Automatisierung und Break-Glass-Zugriff. Für den täglichen Team-Zugriff kannst du stattdessen deinen eigenen OpenID-Connect-(OIDC-)Identity-Provider anbinden: Der API-Server deines Clusters vertraut dann Logins von deinem IdP – Entra ID, Okta, Keycloak, Auth0, Google oder jedem anderen OIDC-konformen Provider.

Was du gegenüber geteilten kubeconfigs gewinnst:

• Benannte Nutzer – kubectl-Aktionen sind einer Person zuzuordnen, nicht „wem auch immer, der die kubeconfig hatte“.
• Deine Zugriffsregeln – RBAC gebunden an die Nutzer und Gruppen deines IdP, deine MFA-Policy, deine Session-Laufzeiten.
• Sofortiges Offboarding – deaktiviere das Konto in deinem IdP, und der Cluster-Zugriff stoppt mit.

Deine Identitäten bleiben vollständig in deinem IdP – PaaSbox konfiguriert deinen Cluster nur darauf, ihm zu vertrauen, und sieht deine Nutzer oder deren Zugangsdaten nie.

Verfügbarkeit. Während des Early Access aktiviert der Support BYO-IdP pro Cluster – kontaktiere uns mit den Werten aus Schritt 2, und wir spielen sie ein. Self-Service-Konfiguration in der Konsole ist geplant.

So funktioniert es

PaaSbox konfiguriert den API-Server deines Clusters (über Gardeners Structured Authentication) so, dass er ID-Tokens von deinem Issuer akzeptiert. Tokens werden so auf Kubernetes-Identitäten abgebildet:

Token-Claim	Kubernetes-Identität
email	Username oidc:alice@example.com
Groups-Claim (optional)	Gruppen oidc:<group>, z. B. oidc:platform-team

Das Präfix oidc: hält deine Nutzer sauber von System-Identitäten getrennt. Berechtigungen vergibst du anschließend mit gewöhnlichem RBAC (Schritt 3). Die Admin-kubeconfig funktioniert parallel weiter – sie bleibt dein Break-Glass-Pfad.

1. Registriere einen Client in deinem IdP

Lege in deinem Identity Provider einen nativen / öffentlichen Client (Authorization Code + PKCE) an:

• Redirect URIs: http://localhost:8000 und http://localhost:18000 (die lokalen Callback-Ports, auf denen das kubectl-Login-Plugin lauscht).
• Scopes: openid, email, profile – plus offline_access, falls dein IdP das für Refresh-Tokens verlangt.
• Notiere dir die Issuer URL und die Client ID.

Der Issuer muss über öffentliches HTTPS erreichbar sein. Prüfen:

curl https://<your-issuer>/.well-known/openid-configuration

Manche Provider stellen Clients nur mit Secret aus. Auch das funktioniert – aber das Secret landet dann in der kubeconfig jedes Team-Mitglieds. Bevorzuge also einen öffentlichen PKCE-Client, wenn dein IdP einen anbietet.

2. Aktiviere es auf deinem Cluster

Schick dem Support (oder trage später in der Konsole ein) für den Cluster:

• Issuer URL – exakt so, wie sie im Discovery-Dokument steht, inklusive eines eventuellen abschließenden Slashs.
• Client ID – wird zur akzeptierten Token-Audience.
• Groups-Claim (optional) – z. B. groups, wenn du gruppenbasiertes RBAC möchtest.

Die Änderung wird als Control-Plane-Update eingespielt und greift innerhalb weniger Minuten; deine Workloads sind nicht betroffen. Auf HA-Clustern rollt der API-Server ohne Downtime; auf Nicht-HA-Clustern rechne mit einer kurzen API-Unterbrechung (Sekunden bis eine Minute), während die Änderung angewendet wird – dasselbe gilt für spätere Änderungen oder das Entfernen dieser Konfiguration.

3. Vergib Zugriff per RBAC

OIDC-Nutzer haben keinerlei Berechtigungen, bis du sie vergibst. Binde mit deiner Admin-kubeconfig Rollen an die abgebildeten Identitäten – Read-only für eine Nutzerin:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: oidc-viewer-alice
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: oidc:alice@example.com

oder Admin für eine ganze IdP-Gruppe:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: oidc-admin-platform-team
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: oidc:platform-team

4. Richte kubectl auf jeder Maschine ein

Team-Mitglieder installieren einmalig das kubelogin-Plugin:

kubectl krew install oidc-login   # or: brew install kubelogin

Dann nutzt du eine kubeconfig, deren cluster-Abschnitt aus einer beliebigen heruntergeladenen PaaSbox-kubeconfig kopiert ist (er enthält die API-Server-URL und die CA), mit einem OIDC-Nutzer anstelle des Zertifikats:

apiVersion: v1
kind: Config
clusters:
  - name: my-cluster        # copy this block from your downloaded kubeconfig
    cluster:
      server: https://api.<your-cluster-domain>
      certificate-authority-data: <copied>
contexts:
  - name: my-cluster-oidc
    context: { cluster: my-cluster, user: oidc }
current-context: my-cluster-oidc
users:
  - name: oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubectl
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=https://<your-issuer>
          - --oidc-client-id=<client-id>
          - --oidc-extra-scope=email,profile

Diese Datei enthält kein Secret (bei einem öffentlichen Client) – du kannst sie gefahrlos in die Dotfiles oder das Onboarding-Repo deines Teams committen.

5. Verifizieren

Der erste kubectl-Aufruf öffnet einen Browser zum Login und cacht danach das Token:

kubectl auth whoami            # attributes: oidc:alice@example.com
kubectl auth can-i list pods   # yes (per your RBAC)
kubectl get pods -A

Troubleshooting

• invalid issuer / Audience-Fehler – die Issuer URL muss Zeichen für Zeichen mit dem Discovery-Dokument übereinstimmen (inklusive abschließendem Slash), und die von dir registrierte Client ID muss die Audience des Tokens sein.
• Veralteter Login – leere den Token-Cache mit rm -rf ~/.kube/cache/oidc-login und melde dich neu an.
• Unauthorized trotz erfolgreichem Login – meist fehlt RBAC (Schritt 3), oder der Username-Claim passt nicht zum Binding – prüfe mit kubectl auth whoami (zum Vergleich mit der Admin-kubeconfig) oder kontrolliere den Subject-Namen noch einmal, inklusive oidc:-Präfix.
• Gruppen funktionieren nicht – stelle sicher, dass dein IdP den Groups-Claim tatsächlich in das ID-Token schreibt (manche Provider müssen das pro Client aktiviert bekommen) und dass du uns den Claim-Namen in Schritt 2 genannt hast.
• Login abgelehnt, obwohl RBAC korrekt ist – weil deine E-Mail-Adresse der Username ist, lehnt der API-Server Tokens ab, bei denen der IdP email_verified: false meldet. Stelle sicher, dass die E-Mail-Adresse des Kontos in deinem IdP verifiziert ist.
• Login erfolgreich, aber Cluster-Zugriff verweigert – das ID-Token muss den email-Claim tatsächlich enthalten, und manche Provider liefern ihn nur mit einer expliziten Einstellung pro Anwendung mit (Zitadel: „User Info inside ID Token“; prüfe das Äquivalent deines Providers). Nur den email-Scope anzufordern reicht nicht immer.
• Der Login gelingt beim IdP, kehrt aber nie ins Terminal zurück (kubelogin scheitert schließlich mit context deadline exceeded) – die meisten IdPs können verlangen, dass Nutzer einer Anwendung explizit zugewiesen sind, bevor sie Tokens für sie ausstellen (Entra ID „user assignment required“, Okta-App-Assignments, Zitadels Prüfung der Projektberechtigung). Weise den Nutzer dem Client zu, den du in Schritt 1 registriert hast. Prüfe außerdem, dass nichts anderes auf deiner Maschine den Callback-Port belegt – kubelogin lauscht auf localhost:8000/18000.

Sicherheitshinweise

• Offboarding: Deaktiviere den Nutzer in deinem IdP – neue Logins und Token-Refreshes stoppen sofort. Denk daran: Die Person hat womöglich auch ein Portal-Konto, das Admin-kubeconfigs ausstellen kann; entferne das ebenfalls.
• Break-Glass: Behalte den Weg über die Admin-kubeconfig für Notfälle – ist dein IdP down, sind es OIDC-Logins auch.