Fehlerbehebung bei der Drittanbieterauthentifizierung mit einem Diagnosedienstprogramm

Sie können ein Diagnosedienstprogramm verwenden, um Probleme mit der FQDN-basierten Authentifizierung in Flottenmitgliedsclustern zu beheben. Wenn Sie Probleme bei der Authentifizierung in einem Cluster mit einem bestimmten OIDC-Anbieter haben, können Sie das Tool aktivieren und damit schnell Konfigurationsprobleme identifizieren, indem Sie Anmeldeabläufe mit Ihrem OIDC-Anbieter simulieren. Dieses Dokument gilt nur für unterstützte Clustertypen.

Das Diagnosedienstprogramm ist nur für einzelne Cluster mit Version 1.32 oder höher verfügbar und unterstützt nur OIDC.

Diagnosedienstprogramm aktivieren

Das Diagnosedienstprogramm ist standardmäßig deaktiviert und muss aktiviert werden, bevor Sie es zur Fehlerbehebung verwenden können. So aktivieren Sie es:

  1. Öffnen Sie die benutzerdefinierte Ressource „ClientConfig“ zur Bearbeitung:

    kubectl edit clientconfig default \
    --kubeconfig CLUSTER_KUBECONFIG -n kube-public

    Das Manifest sollte in etwa so aussehen:

    apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: oidc
    oidc:
      clientID: example-client-id
      clientSecret: example-client-secret
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://example.com
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

  2. Fügen Sie dem ClientConfig-Manifest einen Abschnitt identityServiceOptions hinzu, um die Konfiguration des Diagnosedienstprogramms anzugeben, wie im folgenden Beispiel gezeigt:

    apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
  metadata:
    name: default
    namespace: kube-public
  spec:
    identityServiceOptions:
      diagnosticInterface:
        enabled: true
        expirationTime: TIMESTAMP
    authentication:
    - name: oidc
      oidc:
        clientID: example-client-id
        clientSecret: example-client-secret
        cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
        extraParams: prompt=consent, access_type=offline
        issuerURI: https://example.com
        kubectlRedirectURI: http://localhost:PORT/callback
        scopes: openid,email,offline_access
        userClaim: email

    Ersetzen Sie TIMESTAMP durch eine Ablaufzeit im RFC 3339 Format. Beispiel: 2025-05-01T17:05:00Z. Die Ablaufzeit bestimmt, wann die Funktion des Diagnosedienstprogramms automatisch deaktiviert wird. Da das Diagnosedienstprogramm für alle Nutzer mit Clusterzugriff verfügbar ist, können Sie mit der entsprechenden Ablaufzeit dafür sorgen, dass das Dienstprogramm nicht länger als nötig aktiviert bleibt. Beim Festlegen der Ablaufzeit wird empfohlen, sie auf 12 Stunden in der Zukunft zu setzen. Jede andere Zeit in der Zukunft ist jedoch gültig.

  3. Speichern Sie die Änderungen und beenden Sie den Texteditor, um das Manifest auf den Cluster anzuwenden.

Diagnosedienstprogramm zum Simulieren einer Anmeldung verwenden

Nachdem das Diagnosedienstprogramm aktiviert wurde, können Sie ein Anmeldeereignis simulieren und die entsprechenden Diagnoseinformationen abrufen, mit denen Sie Probleme mit einem bestimmten Anbieter beheben können.

  1. Öffnen Sie die Diagnoseseite in einem Browser, indem Sie die folgende URL aufrufen:

    APISERVER-URL/diagnose

    Ersetzen Sie APISERVER_URL durch den vollqualifizierten Domainnamen (FQDN) für Ihren Cluster. Beispiel: https://apiserver.example.com.

    Wenn ein Fehler vom Typ „Verboten“ auftritt, wie im folgenden Beispiel:

    forbidden: user \"system:anonymous\" cannot get path \"/diagnose\"

    Hängen Sie den Portnummernwert :11001 an die APISERVER_URL an. Beispiel: https://apiserver.example.com:11001/diagnose.

    Auf der Diagnoseseite wird eine Liste der für Ihren Cluster konfigurierten OIDC-Anbieter angezeigt.

  2. Wählen Sie den Anbieter aus, für den Sie eine Fehlerbehebung ausführen möchten.

  3. Melden Sie sich wie gewohnt an.

    Am Ende des Anmeldevorgangs zeigt das Dienstprogramm eine Seite mit Diagnoseinformationen an, die Ihnen bei der Fehlerbehebung helfen können.

Diagnoseseite zur Fehlerbehebung bei Anmeldeproblemen verwenden

Auf der Diagnoseseite finden Sie eine Zusammenfassung der Authentifizierung, die in drei Abschnitte unterteilt ist:

  • Status: Enthält je nachdem, ob die Authentifizierung erfolgreich war oder nicht, entweder Success oder Failed.

  • Identitätsanbieter: Enthält Details wie Name, Client ID und UserClaim zum Anbieter, der für die Anmeldung verwendet wurde.

  • ID-Token: Enthält Informationen zum ID-Token, das von dem Cluster mit dem angegebenen Bereitsteller abgerufen wurde. Das ID-Token ist ein JSON-Objekt, das eine Reihe von Schlüssel/Wert-Paaren enthält. Schlüssel können beispielsweise iss, aud, sub und email sein.

Fehlerbehebung bei erfolgreicher Authentifizierung

Wenn der Inhalt des Abschnitts Status angibt, dass die Authentifizierung erfolgreich war, aber weiterhin Probleme auftreten, können fehlende rollenbasierte Zugriffssteuerungen (Role-Based Access Controls, RBACs) die Ursache sein. Weitere Informationen zur Fehlerbehebung finden Sie unter RBACs für Gruppen funktionieren nicht für OIDC Anbieter.

Fehlerbehebung bei fehlgeschlagener Authentifizierung

Wenn der Inhalt des Abschnitts Status angibt, dass die Authentifizierung fehlgeschlagen ist, suchen Sie zuerst nach Inkonsistenzen zwischen den Abschnitten Identitätsanbieter und ID-Token.

Hier sind einige Authentifizierungsanforderungen, die Sie prüfen sollten:

  • Wenn das Feld UserClaim unter Identitätsanbieter leer ist, muss der Abschnitt ID-Token ein Feld mit dem Namen sub enthalten. Ein fehlendes Feld sub deutet auf ein Problem mit dem ID-Token hin.

  • Der Wert des Felds UserClaim unter Identitätsanbieter muss ein Schlüssel im Abschnitt ID-Token sein. Wenn das Feld UserClaim beispielsweise auf email gesetzt ist, muss im Abschnitt ID-Token ein Feld mit dem Namen email vorhanden sein.

  • Der Wert des Felds GroupsClaim unter Identitätsanbieter muss ein Schlüssel im Abschnitt ID-Token sein. Wenn das Feld GroupsClaim beispielsweise auf groupsList gesetzt ist (für einen Anbieter, der Gruppen unterstützt), muss im Abschnitt ID-Token ein Feld mit dem Namen groupsList vorhanden sein.

  • Der Wert des Felds Client ID unter Identitätsanbieter muss im Wert des Felds aud im Abschnitt ID-Token enthalten sein.

Wenn eine der oben genannten Bedingungen nicht erfüllt ist, finden Sie in einem der folgenden Leitfäden weitere Informationen zum korrekten Konfigurieren Ihrer Cluster für die Authentifizierung:

Logs für weitere Fehlerbehebung verwenden

Die Logs des Identitätsdienst-Pods enthalten zusätzliche Debugging-Informationen. So verwenden Sie diese Logs:

  1. Aktivieren Sie das Debugging-Log.
  2. Prüfen Sie das Containerlog.