Sie betrachten die Dokumentation für eine frühere Version von GKE On-Prem. Sehen Sie sich die aktuelle Dokumentation an.

Authentifizierung mit OpenID Connect (OIDC)

Auf dieser Seite wird beschrieben, wie Sie GKE On-Prem konfigurieren, um einen OpenID-Anbieter für die Authentifizierung bei Nutzerclustern zu verwenden. Informationen zur Verwendung von OIDC mit AD FS finden Sie unter Mit OIDC und AD FS authentifizieren.

Eine Übersicht über den GKE On-Prem-Authentifizierungsablauf finden Sie unter Authentifizierung.

Überblick

GKE On-Prem unterstützt OpenID Connect (OIDC) als Authentifizierungsmechanismus für die Interaktion mit dem Kubernetes API-Server eines Nutzerclusters. Mit OIDC können Sie den Zugriff auf Kubernetes-Cluster verwalten und die Standardverfahren in Ihrer Organisation zum Erstellen, Aktivieren und Deaktivieren von Mitarbeiterkonten verwenden.

Für Mitarbeiter gibt es zwei Möglichkeiten zum Verwenden des OIDC-Authentifizierungsablaufs:

  • Ein Mitarbeiter kann mit kubectl verwenden, um einen OIDC-Ablauf zu initiieren. Damit dieser Ablauf automatisch erfolgt, stellt GKE On-Prem das Kubectl-Plug-in für OIDC zur Verfügung: kubectl-Plug-in.

  • Ein Mitarbeiter kann die Google Cloud Console verwenden, um einen OIDC-Authentifizierungsablauf einzuleiten.

In dieser Übung konfigurieren Sie beide Optionen: kubectl und die Cloud Console.

Hinweise

In diesem Thema wird davon ausgegangen, dass Sie mit OAuth 2.0 und OpenID Connect vertraut sind. In diesem Thema wird davon ausgegangen, dass Sie mit OpenID-Bereichen und Anforderungen vertraut sind.

Einen OpenID-Anbieter auswählen

Dieser Abschnitt richtet sich an Administratoren.

Sie können einen beliebigen OpenID-Anbieter Ihrer Wahl verwenden. Eine Liste der zertifizierten Anbieter finden Sie unter OpenID-Zertifizierung.

Eine Möglichkeit ist die Verwendung von Active Directory Federated Services (ADFS) als OpenID-Anbieter und die Verwendung einer lokalen Instanz von Active Directory als Mitarbeiterdatenbank. Weitere Informationen finden Sie unter Mit OIDC und AD FS authentifizieren.

Kubectl-Plug-in für OIDC herunterladen

Dieser Abschnitt richtet sich an Administratoren und Mitarbeiter, die das Kubectl-Plug-in für OIDC verwenden möchten.

Laden Sie das Plug-in herunter und legen Sie Zugriffsberechtigungen fest:

Linux

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/linux_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Windows

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/windows_amd64/kubectl-oidc .

macOS

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/darwin_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Plug-in installieren

Installieren Sie das Plug-in, indem Sie die ausführbare Datei an einen beliebigen Speicherort auf PATH verschieben. Die ausführbare Datei muss den Namen kubectl-oidc haben. Weitere Informationen finden Sie unter kubectl-Plug-ins installieren.

Eine Weiterleitungs-URL für das Kubectl-Plug-in für OIDC erstellen

Dieser Abschnitt richtet sich an Administratoren.

Beim Einrichten einer Beziehung zu Ihrem OpenID-Anbieter müssen Sie eine Weiterleitungs-URL angeben, die der Anbieter verwenden kann, um ID-Tokens an das Kubectl-Plug-in für OIDC zurückzugeben. Das Kubectl-Plug-in für OIDC wird auf dem lokalen Computer jedes Mitarbeiters ausgeführt und überwacht einen Port Ihrer Wahl. Wählen Sie eine Portnummer größer als 1024, die für diesen Zweck geeignet ist. Dann lautet die Weiterleitungs-URL:

http://localhost:[PORT]/callback

Dabei ist [PORT] Ihre Portnummer.

Geben Sie beim Konfigurieren Ihres OpenID-Anbieters http://localhost:[PORT]/callback als eine Ihrer Weiterleitungs-URLs an. Die Vorgehensweise hängt von Ihrem Anbieter ab.

Weiterleitungs-URL für die Cloud Console konfigurieren

Dieser Abschnitt richtet sich an Administratoren.

Zusätzlich zur Weiterleitungs-URL für kubectl benötigen Sie eine Weiterleitungs-URL für die Cloud Console. Die Weiterleitungs-URL für die Cloud Console lautet:

https://console.cloud.google.com/kubernetes/oidc

Geben Sie beim Konfigurieren Ihres OIDC-Anbieters https://console.cloud.google.com/kubernetes/oidc als eine Ihrer Weiterleitungs-URLs an. Wie Sie dabei vorgehen, hängt von Ihrem Anbieter ab.

Ihre Client-Anwendungen beim OpenID-Anbieter registrieren

Dieser Abschnitt richtet sich an Administratoren.

Bevor Ihre Mitarbeiter das Kubectl-Plug-in für OIDC oder Cloud Console mit Ihrem OpenID-Anbieter verwenden können, müssen Sie diese beiden Clients beim OpenID-Anbieter registrieren. Die Registrierung umfasst folgende Schritte:

  • Informieren Sie sich über den URI des Dienstleisters. Hier sendet das Kubectl-Plug-in für OIDC oder Cloud Console Authentifizierungsanfragen.

  • Stellen Sie dem Anbieter die Weiterleitungs-URL für das Kubectl-Plug-in für OIDC bereit.

  • Stellen Sie dem Anbieter die Weiterleitungs-URL für die Cloud Console bereit. Diese lautet https://console.cloud.google.com/kubernetes/oidc.

  • Richten Sie eine einzelne Client-ID ein. Dies ist die ID, die der Anbieter zum Identifizieren des Kubectl-Plug-ins für OIDC und Cloud Console verwendet.

  • Richten Sie einen einzelnen Clientschlüssel ein. Das Kubectl-Plug-in für OIDC und die Cloud Console verwenden diesen Schlüssek zur Authentifizierung beim OpenID-Anbieter.

  • Legen Sie einen benutzerdefinierten Bereich fest, mit dem das Kubectl-Plug-in für OIDC oder die Cloud Console die Sicherheitsgruppen des Nutzers anfragen kann.

  • Legen Sie einen benutzerdefinierten Anforderungsnamen fest, mit dem der Anbieter die Sicherheitsgruppen des Nutzers zurückgibt.

Wie Sie diese Schritte ausführen, hängt von Ihrem OpenID-Anbieter ab. Informationen zum Ausführen der Registrierungsschritte mit ADFS finden Sie unter Mit OIDC und ADFS authentifizieren.

Die oidc-Spezifikation in die GKE On-Prem-Konfigurationsdatei einsetzen

Dieser Abschnitt richtet sich an Mitarbeiter, die einen Cluster erstellen möchten, der für die Verwendung von OIDC konfiguriert ist.

Bevor Sie einen Nutzercluster erstellen, generieren Sie eine GKE On-Prem-Konfigurationsdatei mit gkectl create-config. Die Konfiguration enthält die folgende oidc-Spezifikation. Sie füllen oidc mit Werten, die für Ihren Anbieter spezifisch sind:

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: Erforderlich. URL Ihres OpenID-Anbieters, beispielsweise https://example.com/adfs. Clientanwendungen wie das Kubectl-Plug-in für OIDC und die Cloud Console senden Autorisierungsanfragen an diese URL. Der Kubernetes API-Server verwendet diese URL, um öffentliche Schlüssel zum Verifizieren von Tokens zu finden. HTTPS muss verwendet werden.
  • clientid: Erforderlich. ID für die Clientanwendung, die Authentifizierungsanfragen an den OpenID-Anbieter sendet. Sowohl das Kubectl-Plug-in für OIDC als auch die Cloud Console verwenden diesen Schlüssel.
  • clientsecret: Optional Das Secret für die Clientanwendung. Sowohl das Kubectl-Plug-in für OIDC als auch die Cloud Console verwenden dieses Secret.
  • username: Optional JWT-Anspruch, der als Nutzername verwendet wird. Der Standardwert ist sub. Dies ist eine eindeutige ID des Endnutzers. Je nach OpenID-Anbieter können Sie andere Anforderungen auswählen, wie beispielsweise email oder name. Allerdings wird anderen Anforderungen als email die Aussteller-URL vorangestellt, um Namenskonflikte mit anderen Plug-ins zu vermeiden.
  • usernameprefix: Optional Präfix, das Nutzernamensanforderungen vorangestellt wird, um Konflikte mit vorhandenen Namen zu vermeiden. Wenn Sie dieses Feld nicht angeben und username ein anderer Wert als email ist, wird standardmäßig das Präfix issuerurl# verwendet. Sie können den Wert - verwenden, um alle Präfixe zu deaktivieren.
  • group: Optional JWT-Anspruch, mit dem der Anbieter Ihre Sicherheitsgruppen zurückgibt.
  • groupprefix: Optional Präfix, das Gruppenansprüchen vorangestellt wird, um Konflikte mit vorhandenen Namen zu vermeiden. Es sind beispielsweise die Gruppe foobar und das Präfix gid- gid-foobar gegeben.
  • scopes: Optional Zusätzliche Bereiche, die als durch Kommas getrennte Liste an den OpenID-Anbieter gesendet werden.
  • extraparams: Optional Zusätzliche Schlüsselwertparameter, die als durch Kommas getrennte Liste an den OpenID-Anbieter gesendet werden.
  • usehttpproxy: Optional Gibt an, ob ein Reverse-Proxy im Cluster bereitgestellt werden soll, um dem Connect-Agent Zugriff auf den lokalen OIDC-Anbieter zur Authentifizierung von Nutzern zu gewähren. Der Wert muss ein String sein: "true" oder "false".
  • capath: Optional Pfad zum Zertifikat für die Zertifizierungsstelle, die das Webzertifikat Ihres Identitätsanbieters ausgestellt hat. Dieser Wert ist möglicherweise nicht erforderlich. Wenn das Zertifikat Ihres Identitätsanbieters beispielsweise von einer bekannten öffentlichen Zertifizierungsstelle ausgestellt wurde, müssen Sie hier keinen Wert angeben.

Beispiel: Nutzer und Gruppen autorisieren

Viele Anbieter codieren Eigenschaften zur Identifizierung von Nutzern wie E-Mail-Adressen und Nutzer-IDs in einem Token. Diese Eigenschaften haben jedoch implizite Risiken für Authentifizierungsrichtlinien:

  • Nutzer-IDs können das Lesen und Prüfen von Richtlinien erschweren.
  • E-Mail-Adressen können sowohl ein Verfügbarkeitsrisiko (wenn ein Nutzer seine primäre E-Mail-Adresse ändert) als auch ein Sicherheitsrisiko (wenn eine E-Mail neu zugewiesen werden kann) bewirken.

Daher empfiehlt es sich, Gruppenrichtlinien zu verwenden, da eine Gruppen-ID sowohl persistent als auch einfacher zu prüfen ist.

Angenommen, Ihr Anbieter erstellt Identitäts-Token, die die folgenden Felder enthalten:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList: ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}
Bei diesem Tokenformat würden Sie die oidc-Spezifikation Ihrer Konfigurationsdatei so ausfüllen:
issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

Nachdem Sie den Nutzercluster erstellt haben, können Sie den authentifizierten Nutzern mithilfe der rollenbasierten Zugriffssteuerung (Role-based Access Control, RBAC) einen autorisierten Zugriff gewähren. Sie können beispielsweise eine ClusterRole erstellen, die ihren Nutzern Lesezugriff auf die Secrets des Clusters gewährt, und eine ClusterRoleBinding-Ressource erstellen, um die Rolle an die authentifizierte Gruppe zu binden:

ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-reader
rules:
- apiGroups: [""]
  # The resource type for which access is granted
  resources: ["secrets"]
  # The permissions granted by the ClusterRole
  verbs: ["get", "watch", "list"]

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Zertifikat der Zertifizierungsstelle des Kubernetes API-Servers speichern

Dieser Abschnitt richtet sich an Mitarbeiter, die einen Nutzercluster erstellt haben und nun das Kubectl-Plug-in für OIDC verwenden möchten.

Ihr Nutzercluster verfügt über einen Kubernetes API-Server. Die kubeconfig-Datei Ihres Nutzerclusters speichert das Zertifikat der Zertifizierungsstelle, die ein Zertifikat an den Kubernetes API-Server ausgestellt hat. Das Zertifikat der Zertifizierungsstelle ist der Basis-64-codierte Wert des Felds certificate-authority-data. Sie müssen diesen Wert entschlüsseln und in einer lokalen Datei wie server-ca-cert speichern:

cat [USER_CLUSTER_KUBECONFIG]  | grep certificate-authority-data | awk '{ print $2}' | base64 --decode > server-ca-cert

Die Konfigurationsdatei für die Clientauthentifizierung generieren

Dieser Abschnitt richtet sich an Mitarbeiter, die einen Nutzercluster erstellt haben und nun das Kubectl-Plug-in für OIDC verwenden möchten.

Geben Sie den folgenden Befehl ein, um eine Konfigurationsdatei für die Clientauthentifizierung zu generieren:

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URL] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "[CUSTOM_SCOPES]" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file [SERVER_CA_CERT] \
--issuer-ca-file [PROVIDER_CA_CERT] \
--extra-params [KEY]=[VALUE], ... # e.g. --extra-params "resource=token-groups-claim"
> client-config.yaml

wobei

  • [ISSUER_URI] ist der URI des Ausstellers.
  • [REDIRECT_URL] ist die Weiterleitungs-URL für das Kubectl-Plug-in für OIDC.
  • [CLIENT_ID] ist die Client-ID für das Kubectl-Plug-in für OIDC.
  • [CLIENT_SECRET] ist der Clientschlüssel für das Kubectl-Plug-in für OIDC.
  • [USER_CLUSTER_NAME] ist der Name Ihres Nutzerclusters.
  • [CLUSTER_URL] ist die URL des Kubernetes API-Servers des Nutzerclusters.
  • [SERVER_CA_FILE] ist der Pfad zum Zertifikat der Zertifizierungsstelle, die ein Zertifikat für den Kubernetes API-Server ausgestellt hat. Dies ist die Zertifikatsdatei, die Sie im vorherigen Abschnitt erstellt haben.
  • [PROVIDER_CA_CERT] ist der Pfad zum Zertifikat der Zertifizierungsstelle, die das Zertifikat des OpenID-Anbieters signiert hat. Dies entspricht dem Wert von oidc:cacert in der Cluster-Konfigurationsdatei.
  • [CUSTOM_SCOPES] ist die durch Kommas getrennte Liste Ihrer benutzerdefinierten Bereiche für Sicherheitsgruppen. Dies entspricht dem Wert von oidc:scopes in der Cluster-Konfigurationsdatei.
  • --extra-params [KEY]=[VALUE], ... ist eine Liste von durch Kommas getrennten Schlüssel/Wert-Paaren, die in Autorisierungsanfragen an den OpenID-Anbieter eingeschlossen werden sollen.

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URL] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "[CUSTOM_SCOPES]" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file [SERVER_CA_CERT] `
--issuer-ca-file [PROVIDER_CA_CERT] `
--extra-params [KEY]=[VALUE]
> client-config.yaml

wobei

  • [ISSUER_URI] ist der URI des Ausstellers.
  • [REDIRECT_URL] ist die Weiterleitungs-URL für das Kubectl-Plug-in für OIDC.
  • [CLIENT_ID] ist die Client-ID für das Kubectl-Plug-in für OIDC.
  • [CLIENT_SECRET] ist der Clientschlüssel für das Kubectl-Plug-in für OIDC.
  • [USER_CLUSTER_NAME] ist der Name Ihres Nutzerclusters.
  • [CLUSTER_URL] ist die URL des Kubernetes API-Servers des Nutzerclusters.
  • [SERVER_CA_FILE] ist der Pfad zum Zertifikat der Zertifizierungsstelle, die ein Zertifikat für den Kubernetes API-Server ausgestellt hat. Dies ist die Zertifikatsdatei, die Sie im vorherigen Abschnitt erstellt haben.
  • [PROVIDER_CA_CERT] ist der Pfad zum Zertifikat der Zertifizierungsstelle, die das Zertifikat des OpenID-Anbieters signiert hat. Dies entspricht dem Wert von oidc:cacert in der Cluster-Konfigurationsdatei.
  • [CUSTOM_SCOPES] ist die durch Kommas getrennte Liste Ihrer benutzerdefinierten Bereiche für Sicherheitsgruppen. Dies entspricht dem Wert von oidc:scopes in der Cluster-Konfigurationsdatei.
  • --extra-params [KEY]=[VALUE], ... ist eine Liste von durch Kommas getrennten Schlüssel/Wert-Paaren, die in Autorisierungsanfragen an den OpenID-Anbieter eingeschlossen werden sollen.

Dieser Befehl erzeugt eine Konfigurationsdatei für die Clientauthentifizierung mit dem Namen client-config.yaml. Bearbeiten Sie diese Datei nicht manuell.

Mit dem Kubectl-Plug-in für OIDC einen Nutzercluster authentifizieren

Dieser Abschnitt richtet sich an Mitarbeiter, die einen Nutzercluster erstellt haben und nun das Kubectl-Plug-in für OIDC verwenden möchten.

  1. Initialisieren Sie das Plug-in mit der Datei client-config.yaml:

    kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \
        --kubeconfig [KUBECONFIG_OUTPUT_PATH]

    wobei

    • [NAME] ist Ihr Nutzername.
    • [KUBECONFIG_OUTPUT_PATH] ist der Pfad zur kubeconfig-Datei, in der das Kubectl-Plug-in für OIDC Anmeldedaten speichert.

    kubectl oidc login startet einen Browser, in dem Sie Ihre Anmeldedaten eingeben können.

    Die bereitgestellte kubeconfig-Datei enthält jetzt ein ID-Token, das von kubectl zur Authentifizierung beim Kubernetes API-Server auf dem Nutzercluster verwendet werden kann.

    Hinweis: Windows-Nutzer müssen den Befehl möglicherweise als kubectl-oidc.exe-login statt als kubectl oidc login ausführen.

  2. Prüfen Sie, ob die Authentifizierung erfolgreich war, indem Sie einen beliebigen kubectl-Befehl ausführen. Beispiel:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

OIDC mit Google Cloud Console verwenden

Dieser Abschnitt richtet sich an Mitarbeiter, die einen Nutzercluster erstellt haben und jetzt die Google Cloud Console zur Authentifizierung beim Cluster verwenden möchten.

  1. Prüfen Sie, ob Ihr Cluster für OIDC konfiguriert ist.

  2. Prüfen Sie, ob Ihr Cluster in Google Cloud registriert wurde, entweder automatisch während der Erstellung des Clusters oder manuell.

  3. Rufen Sie in der Cloud Console die Seite Kubernetes-Cluster auf.

    Zur Seite Kubernetes-Cluster

  4. Suchen Sie in der Liste der Cluster nach Ihrem GKE On-Prem-Cluster und klicken Sie auf Anmelden.

  5. Wählen Sie Mit dem für den Cluster konfigurierten Identitätsanbieter authentifizieren aus und klicken Sie auf ANMELDEN.

    Sie werden zu Ihrem Identitätsanbieter weitergeleitet. Dort müssen Sie sich möglicherweise anmelden oder dem Zugriff der Cloud Console auf Ihr Konto zustimmen. Anschließend werden Sie zurück zur Seite Kubernetes-Cluster in der Cloud Console weitergeleitet.

Fehlerbehebung für OIDC in GKE On-Prem

Ungültige Konfiguration

Wenn die Cloud Console die OIDC-Konfiguration nicht aus Ihrem Cluster lesen kann, wird die Schaltfläche ANMELDEN deaktiviert.

Ungültige Anbieterkonfiguration

Wenn die Konfiguration Ihres Identitätsanbieters ungültig ist, wird nach dem Klicken auf ANMELDEN eine Fehlermeldung Ihres Identitätsanbieters angezeigt. Befolgen Sie die anbieterspezifischen Anweisungen, um den Anbieter oder Ihren Cluster richtig zu konfigurieren.

Ungültige Berechtigungen

Wenn Sie den Authentifizierungsvorgang abschließen, aber die Details des Clusters immer noch nicht sehen, bestätigen Sie, dass Sie dem mit OIDC verwendeten Konto die richtigen RBAC-Berechtigungen erteilt haben. Beachten Sie, dass sich dieses Konto möglicherweise von dem Konto unterscheidet, mit dem Sie auf die Cloud Console zugreifen.

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

Möglicherweise tritt dieser Fehler auf, wenn der Autorisierungsserver zur Einwilligung auffordert, der erforderliche Authentifizierungsparameter jedoch nicht angegeben wurde. Geben Sie den Parameter prompt=consent im Feld oidc: extraparams der GKE On-Prem-Konfigurationsdatei an und generieren Sie die Clientauthentifizierungsdatei mit dem Flag --extra-params prompt=consent neu.