OIDC / Structured Authentication

Ab Kubernetes 1.32 ist die bisherige oidcConfig-Konfiguration im Shoot-Manifest nicht mehr zulässig. Die Authentifizierung über externe Identity Provider erfolgt ausschließlich über die Structured Authentication Configuration — ein Kubernetes-natives Format, das direkt am kube-apiserver des Shoots konfiguriert wird.

Funktionsweise

Die Konfiguration wird in einer ConfigMap im jeweiligen Gardener-Projekt-Namespace hinterlegt und über das Shoot-Manifest referenziert. Änderungen an der ConfigMap werden beim nächsten Reconcile des Shoots übernommen — ein manueller Trigger ist möglich.

Konfiguration

Schritt 1: ConfigMap anlegen

Die ConfigMap muss im Projekt-Namespace (z.B. garden-my-project) angelegt werden und enthält die AuthenticationConfiguration im Feld config.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: structured-authentication-config
  namespace: garden-my-project
data:
  config.yaml: |
    apiVersion: apiserver.config.k8s.io/v1beta1
    kind: AuthenticationConfiguration
    jwt:
    - issuer:
        url: https://issuer.example.com
        audiences:
        - <client-id>
        audienceMatchPolicy: MatchAny
      claimMappings:
        username:
          claim: email
          prefix: ""
        groups:
          claim: groups
          prefix: ""

Mehrere JWT-Authenticators können in der Liste jwt definiert werden, z.B. für verschiedene Identity Provider.

Schritt 2: Shoot-Manifest referenzieren

Im Shoot-Manifest wird die ConfigMap unter spec.kubernetes.kubeAPIServer.structuredAuthentication referenziert:

apiVersion: core.gardener.cloud/v1beta1
kind: Shoot
metadata:
  name: mycluster
  namespace: garden-my-project
spec:
  kubernetes:
    kubeAPIServer:
      structuredAuthentication:
        configMapName: structured-authentication-config

Diese Änderung löst einen Reconcile aus. Andere Authentifizierungsmethoden (z.B. zertifikatsbasiert) bleiben davon unberührt.

Claim Mappings

Das Feld claimMappings steuert, wie JWT-Claims auf Kubernetes-Identitäten abgebildet werden:

Alternativ zu claim können CEL-Anweisungen (expression) verwendet werden, z.B.:

claimMappings:
  username:
    expression: 'claims.email'
  groups:
    expression: 'claims.groups'

Claim Validation Rules

Optional können Validierungsregeln definiert werden, die eingehende Tokens prüfen:

claimValidationRules:
- expression: 'claims.hd == "example.com"'
  message: "Nur Tokens der Domain example.com sind zugelassen"

Migration von oidcConfig

Falls im Shoot-Manifest noch spec.kubernetes.kubeAPIServer.oidcConfig konfiguriert ist, muss diese auf Structured Authentication migriert werden — spätestens bei einem Upgrade auf Kubernetes 1.32.

Beispiel — bisherige oidcConfig:

spec:
  kubernetes:
    kubeAPIServer:
      oidcConfig:
        clientID: <client-id>
        issuerURL: https://issuer.example.com
        usernameClaim: email
        groupsClaim: groups
        groupsPrefix: "oidc:"

Äquivalente Structured Authentication ConfigMap:

data:
  config.yaml: |
    apiVersion: apiserver.config.k8s.io/v1beta1
    kind: AuthenticationConfiguration
    jwt:
    - issuer:
        url: https://issuer.example.com
        audiences:
        - <client-id>
      claimMappings:
        username:
          claim: email
          prefix: ""
        groups:
          claim: groups
          prefix: "oidc:"

Anschließend oidcConfig aus dem Shoot-Manifest entfernen und durch den structuredAuthentication-Block ersetzen.

Anonyme Authentifizierung

Standardmäßig ist anonyme Authentifizierung in PSKE-Clustern deaktiviert. Für spezifische Pfade kann sie über Structured Authentication aktiviert werden (ab Kubernetes 1.35):

data:
  config.yaml: |
    apiVersion: apiserver.config.k8s.io/v1beta1
    kind: AuthenticationConfiguration
    anonymous:
      enabled: true
      conditions:
      - path: /livez

kubectl-Konfiguration (kubelogin)

Für die Nutzung von OIDC mit kubectl wird das Plugin oidc-login (auch bekannt als kubelogin) empfohlen. Die Installation und Konfiguration ist im Tutorial Einrichten von OIDC/2FA beschrieben.