Mit OpenID Connect (OIDC) authentifizieren

Auf dieser Seite wird gezeigt, wie Sie GKE On-Prem konfigurieren, um einen OpenID-Anbieter zur 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 Authentifizierungsvorgang in GKE On-Prem finden Sie unter Authentifizierung.

Übersicht

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 nutzen.

Für Mitarbeiter gibt es zwei Möglichkeiten zur Verwendung der OIDC-Authentifizierung:

  • Ein Mitarbeiter kann mit kubectl einen OIDC-Ablauf 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 mithilfe der Google Cloud Console einen OIDC-Authentifizierungsvorgang initiieren.

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

Hinweis

In diesem Thema wird davon ausgegangen, dass Sie mit OAuth 2.0 und OpenID Connect vertraut sind. Außerdem wird angenommen, dass Sie sich mit OpenID-Bereichen und -Anforderungen auskennen.

OpenID-Anbieter auswählen

Dieser Abschnitt richtet sich an Administratoren.

Sie können einen beliebigen OpenID-Anbieter 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 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 durch Verschieben der ausführbaren Datei an einen beliebigen Speicherort unter Ihrem PATH. Die ausführbare Datei muss den Namen kubectl-oidc haben. Weitere Informationen finden Sie unter kubectl-Plug-ins installieren.

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, mit der der Anbieter ID-Tokens an das Kubectl-Plug-in für OIDC zurückgeben kann. 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. Die Weiterleitungs-URL lautet unter diesen Bedingungen so:

http://localhost:[PORT]/callback

Dabei ist [PORT] Ihre Portnummer.

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

Weiterleitungs-URL für die Google 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 Google Cloud Console. Die Weiterleitungs-URL für die Google 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.

Clientanwendungen beim OpenID-Anbieter registrieren

Dieser Abschnitt richtet sich an Administratoren.

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

  • Ermitteln Sie den Aussteller-URI des Anbieters. Damit sendet das Kubectl-Plug-in für OIDC oder für die Google Cloud Console Authentifizierungsanfragen.

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

  • Geben Sie dem Anbieter die Weiterleitungs-URL für die Google Cloud Console. Sie 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 für die Google Cloud Console verwendet.

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

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

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

Die jeweilige Vorgehensweise hängt von Ihrem OpenID-Anbieter ab. Informationen zum Ausführen der Registrierungsschritte mit ADFS finden Sie unter Mit OIDC und ADFS authentifizieren.

oidc-Spezifikation in der GKE On-Prem-Konfigurationsdatei festlegen

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

Generieren Sie, bevor Sie einen Nutzercluster erstellen, mit gkectl create-config eine GKE On-Prem-Konfigurationsdatei. Die Konfiguration enthält die folgende oidc-Spezifikation. Für oidc geben Sie die für Ihren Anbieter spezifischen Werte an:

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: erforderlich. Die URL Ihres OpenID-Anbieters, beispielsweise https://example.com/adfs. Clientanwendungen wie das Kubectl-Plug-in für OIDC und für die Google Cloud Console senden Autorisierungsanfragen an diese URL. Der Kubernetes API-Server nutzt diese URL, um öffentliche Schlüssel zum Verifizieren von Tokens zu ermitteln. Es muss HTTPS verwendet werden.
  • clientid: erforderlich. Die ID für die Clientanwendung, die Authentifizierungsanfragen an den OpenID-Anbieter sendet. Sowohl das Kubectl-Plug-in für OIDC als auch für die Google Cloud Console verwenden diesen Schlüssel.
  • clientsecret: optional. Das Secret für die Clientanwendung. Sowohl das Kubectl-Plug-in für OIDC als auch für die Google Cloud Console verwenden dieses Secret.
  • username: optional. Die JWT-Anforderung, die 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. Das 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 mit dem Wert - alle Präfixe deaktivieren.
  • group: optional. Die JWT-Anforderung, mit der der Anbieter Ihre Sicherheitsgruppen zurückgibt.
  • groupprefix: optional. Das Präfix, das Gruppenanforderungen vorangestellt wird, um Konflikte mit vorhandenen Namen zu vermeiden. Ein Beispiel ist gid-foobar für die Gruppe foobar und das Präfix gid-.
  • scopes: optional. Zusätzliche Bereiche, die als durch Kommas getrennte Liste an den OpenID-Anbieter gesendet werden.
  • extraparams: Optional. Zusätzliche Schlüssel/Wert-Paar-Parameter, die als durch Kommas getrennte Liste an den OpenID-Anbieter gesendet werden.
  • usehttpproxy: optional. Damit wird angegeben, ob ein Reverse-Proxy im Cluster bereitgestellt werden soll, um 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 der 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 nutzeridentifizierende Attribute wie E-Mail-Adressen und Nutzer-IDs in einem Token. Diese Attribute bringen jedoch implizite Risiken für Authentifizierungsrichtlinien mit sich:

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

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

Beispiel: Ihr Anbieter erstellt Identitätstokens, 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ürde dann die oidc-Spezifikation Ihrer Konfigurationsdatei so aussehen: 
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) autorisierten Zugriff gewähren. Sie haben beispielsweise die Möglichkeit, eine ClusterRole zu erstellen, die ihren Nutzern Lesezugriff auf die Secrets des Clusters gewährt, sowie eine ClusterRoleBinding-Ressource, 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 hat einen Kubernetes API-Server. Die kubeconfig-Datei Ihres Nutzerclusters speichert das Zertifikat der Zertifizierungsstelle, die ein Zertifikat für den Kubernetes API-Server ausgestellt hat. Das Zertifikat der Zertifizierungsstelle ist der base-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

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

Dabei gilt:

  • [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 Clusterkonfigurationsdatei.
  • [CUSTOM_SCOPES] ist die durch Kommas getrennte Liste Ihrer benutzerdefinierten Bereiche für Sicherheitsgruppen. Dies entspricht dem Wert von oidc:scopes in der Clusterkonfigurationsdatei.
  • --extra-params [KEY]=[VALUE], ... ist eine Liste von durch Kommas getrennten Schlüssel/Wert-Paaren, die in Autorisierungsanfragen an den OpenID-Anbieter enthalten sein 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

Dabei gilt:

  • [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 Clusterkonfigurationsdatei.
  • [CUSTOM_SCOPES] ist die durch Kommas getrennte Liste Ihrer benutzerdefinierten Bereiche für Sicherheitsgruppen. Dies entspricht dem Wert von oidc:scopes in der Clusterkonfigurationsdatei.
  • --extra-params [KEY]=[VALUE], ... ist eine Liste von durch Kommas getrennten Schlüssel/Wert-Paaren, die in Autorisierungsanfragen an den OpenID-Anbieter enthalten sein sollen.

Dieser Befehl generiert 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 für 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]

    Dabei gilt:

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

    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 im Nutzercluster verwendet werden kann.

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

  2. Prüfen Sie, ob die Authentifizierung erfolgreich war. Führen Sie dazu einen kubectl-Befehl aus. Beispiel:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

OIDC mit der Google Cloud Console verwenden

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

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

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

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

    Zur Seite „Kubernetes-Cluster“

  4. Ermitteln Sie in der Liste der Cluster Ihren 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 dann zu Ihrem Identitätsanbieter weitergeleitet. Dort müssen Sie sich möglicherweise anmelden oder dem Zugriff der Google Cloud Console auf Ihr Konto zustimmen. Anschließend werden Sie zurück zur Seite Kubernetes-Cluster in der Google Cloud Console geleitet.

Fehlerbehebung für OIDC in GKE On-Prem

Ungültige Konfiguration

Wenn in der Google Cloud Console die OIDC-Konfiguration aus Ihrem Cluster nicht gelesen werden 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. Folgen Sie dann der anbieterspezifischen Anleitung, um den Anbieter oder Ihren Cluster ordnungsgemäß zu konfigurieren.

Ungültige Berechtigungen

Wenn Sie den Authentifizierungsvorgang abgeschlossen haben, die Details des Clusters aber noch nicht sichtbar sind, prüfen Sie, ob Sie dem mit OIDC verwendeten Konto die erforderlichen RBAC-Berechtigungen erteilt haben. Dieses Konto unterscheidet sich möglicherweise von dem Konto, mit dem Sie auf die Google Cloud Console zugreifen.

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

Dieser Fehler tritt eventuell auf, wenn der Autorisierungsserver zur Zustimmung auffordert, der erforderliche Authentifizierungsparameter aber 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.