Cluster für GKE Identity Service mit OIDC einrichten

Dieses Dokument richtet sich an Clusteradministratoren oder Anwendungsoperatoren, die GKE Identity Service auf einzelnen Clustern einrichten möchten, sodass sich Entwickler und andere Nutzer mit ihren vorhandenen Identitätsdetails von einem OIDC-Anbieter (OpenID Connect) bei den Clustern anmelden können.

Vorbereitung

  • Ihr Cluster muss ein GKE Cluster auf lokaler Ebene (VMware oder Bare Metal) in AWS oder in Azure sein. Eine OIDC-Konfiguration pro Cluster wird für angehängte Cluster oder GKE-Cluster nicht unterstützt.
  • Zur Authentifizierung über die Google Cloud Console muss jeder Cluster, den Sie für die OIDC-Authentifizierung konfigurieren möchten, in Ihrer Projektflotte registriert sein.

Hinweise

  • Achten Sie darauf, dass Ihr Plattformadministrator alle erforderlichen Informationen aus der Registrierung von GKE Identity Service bei Ihrem Anbieter erhalten hat, bevor Sie mit der Einrichtung beginnen, einschließlich der Client-ID und des Secrets für GKE Identity Service.

  • Prüfen Sie, ob die folgenden Befehlszeilentools installiert sind:

    • Die neueste Version der Google Cloud CLI, die gcloud, das Befehlszeilentool für die Interaktion mit Google Cloud, enthält. Informationen zur Installation des Google Cloud CLI finden Sie in der Installationsanleitung.
    • kubectl zum Ausführen von Befehlen für Kubernetes-Cluster. Falls Sie kubectl installieren müssen, folgen Sie dieser Anleitung.

    Wenn Sie Cloud Shell als Shell-Umgebung für die Interaktion mit Google Cloud verwenden, sind diese Tools für Sie installiert.

  • Achten Sie darauf, dass die gcloud CLI für die Verwendung mit dem Projekt initialisiert ist, in dem die Cluster registriert sind.

  • Wenn Sie über einen Bastion Host eine Verbindung zur Steuerungsebene eines AWS- oder Azure-GKE-Clusters herstellen müssen, die sich außerhalb Ihrer aktuellen VPC befindet, achten Sie darauf, dass Sie den Bastion Host erstellt und vor der Einrichtung einen SSH-Tunnel an Port 8118 gestartet haben. Stellen Sie dann den kubectl-Befehlen HTTPS_PROXY=http://localhost:8118 voran, wenn Sie dieser Anleitung folgen. Wenn Sie beim Starten des SSH-Tunnels einen anderen Port verwendet haben, ersetzen Sie 8118 durch den ausgewählten Port.

Cluster konfigurieren

Um Ihre Cluster so zu konfigurieren, dass sie den von Ihnen gewählten Anbieter verwenden, müssen Sie bei GKE Identity Service Details über den Identitätsanbieter, die Informationen in den JWT-Tokens, die er zur Identifizierung der Nutzer bereitstellt, und andere Informationen angeben, die bei der Registrierung von GKE Identity Service als Client-Anwendung bereitgestellt werden.

Wenn Ihr Anbieter beispielsweise Identitätstokens mit den folgenden Feldern erstellt, wobei iss der Identitätsanbieter-URI ist, identifiziert sub den Nutzer und groupList listet die Sicherheitsgruppen auf, denen der Nutzer angehört:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

...Ihre Konfiguration enthält die folgenden entsprechenden Felder:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

Ihr Plattformadministrator oder die Person, die die Identitäten in Ihrer Organisation verwaltet, sollte Ihnen die meisten Informationen bereitstellen, die Sie zum Erstellen der Konfiguration benötigen.

GKE Identity Service verwendet für die Clusterkonfiguration den benutzerdefinierten Kubernetes-Ressourcentyp „ClientConfig“ mit Feldern, die alle Informationen enthalten, die GKE Identity Service für die Interaktion mit dem Identitätsanbieter haben muss. Jeder GKE-Cluster hat eine ClientConfig-Ressource namens default im Namespace kube-public, die Sie gemäß der Anleitung unten in Ihren Konfigurationsdetails aktualisieren.

Unter Anbieterspezifische Konfigurationen finden Sie einige Beispielkonfigurationen für beliebte Anbieter.

kubectl

Zum Bearbeiten der Standard-ClientConfig müssen Sie über kubectl eine Verbindung zu Ihrem Cluster herstellen und den folgenden Befehl ausführen:

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Ersetzen Sie KUBECONFIG_PATH durch den Pfad zur kubeconfig-Datei Ihres Clusters, z. B. $HOME/.kube/config.

Die ClientConfig-Ressource des Clusters wird in einem Texteditor geladen. Fügen Sie das Objekt spec.authentication.oidc wie unten gezeigt hinzu. Ändern Sie keine bereits geschriebenen Standarddaten.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

In der folgenden Tabelle sind die Felder des ClientConfig-oidc-Objekts beschrieben. Die meisten Felder sind optional. Welche Felder Sie hinzufügen müssen, hängt von Ihrem Identitätsanbieter und den Einrichtungsoptionen ab, die von Ihrem Plattformadministrator ausgewählt wurden, wenn Sie den Anbieter für GKE Identity Service konfigurieren.

Feld Erforderlich Beschreibung Format
Name Ja Der Name, den Sie dieser Konfiguration zuweisen möchten, normalerweise der Name des Identitätsanbieters. Ein Konfigurationsname muss mit einem Buchstaben beginnen, gefolgt von bis zu 39 Kleinbuchstaben, Zahlen oder Bindestrichen. Das letzte Zeichen darf kein Bindestrich sein. String
certificateAuthorityData Nein Ein eventuell von Ihrem Plattformadministrator bereitgestellter PEM-codierter Zertifikatstring für den Identitätsanbieter. Fügen Sie den resultierenden String in certificateAuthorityData als eine Zeile ein. String
clientID Ja Die Client-ID, die bei der Registrierung von GKE Identity Service bei Ihrem OIDC-Anbieter zurückgegeben wurde. String
clientSecret Nein Gemeinsames Secret vom OIDC-Clientanwendung und OIDC-Anbieter. String
deployCloudConsoleProxy Nein Gibt an, ob ein Proxy bereitgestellt wird, mit dem die Google Cloud Console eine Verbindung zu einem lokalen Identitätsanbieter herstellen kann, der nicht über das Internet öffentlich zugänglich ist. Standardmäßig ist dies auf false eingestellt. Boolesch
extraParams Nein Zusätzliche key=value-Parameter, die als durch Kommas getrennte Liste an den Identitätsanbieter gesendet werden, z. B. `prompt=consent,access_type=offline`. Durch Kommas getrennte Liste
groupsClaim Nein Die JWT-Anforderung (Feldname), die Ihr Anbieter zum Zurückgeben der Sicherheitsgruppen eines Kontos verwendet. String
groupPrefix Nein Das Präfix, das Sie Sicherheitsgruppennamen voranstellen möchten, um Konflikte mit vorhandenen Namen in Ihren Zugriffssteuerungsregeln zu vermeiden, wenn Sie Konfigurationen für mehrere Identitätsanbieter haben (normalerweise der Anbietername). String
issuerURI Ja Der URI, an den Autorisierungsanfragen an Ihren Identitätsanbieter gesendet werden. Der URI muss HTTPS verwenden und darf nicht mit einem nachgestellten Schrägstrich enden. URL String
kubectlRedirectURI JaDie von der gcloud CLI verwendete Weiterleitungs-URL und der Weiterleitungsport, die von Ihrem Plattformadministrator bei der Registrierung angegeben wurden, normalerweise in der Form http://localhost:PORT/callback. URL String
Umfang Ja Zusätzliche Bereiche, die an den OpenID-Anbieter gesendet werden. Microsoft Azure und Okta benötigen beispielsweise den Bereich offline_access. Durch Kommas getrennte Liste
userClaim Nein Die JWT-Anforderung (Feldname), die Ihr Anbieter zur Identifizierung eines Nutzerkontos verwendet. Wenn Sie hier keinen Wert angeben, verwendet GKE Identity Service „sub“. Dies ist die Nutzer-ID-Anforderung, die von vielen Anbietern verwendet wird. Je nach OpenID-Anbieter können Sie andere Anforderungen auswählen, beispielsweise „E-Mail“ oder „Name“. Anderen Anforderungen als der E-Mail-Adresse wird die Aussteller-URL vorangestellt, um Namenskonflikte zu vermeiden. String
userPrefix Nein Das Präfix, das Sie den Nutzeranforderungen voranstellen möchten, um Konflikte mit vorhandenen Namen zu vermeiden. Sie können jedoch auch das Standardpräfix verwenden. String
enableAccessToken Nein Wenn diese Option aktiviert ist, kann GKE Identity Service den userinfo-Endpunkt des Identitätsanbieters verwenden, um Gruppeninformationen abzurufen, wenn sich ein Nutzer über die Befehlszeile anmeldet. Dadurch können Sie Sicherheitsgruppen für die Autorisierung verwenden, wenn Sie einen Anbieter wie Okta haben, der Gruppenanforderungen von diesem Endpunkt bereitstellt. Wenn das Feld nicht festgelegt ist, wird der Wert false verwendet. Boolesch
proxy Nein Proxyserver-Adresse, die gegebenenfalls zum Herstellen einer Verbindung mit dem Identitätsanbieter verwendet werden soll. Diese Angabe ist möglicherweise erforderlich, wenn sich der Cluster beispielsweise in einem privaten Netzwerk befindet und eine Verbindung zu einem öffentlichen Identitätsanbieter hergestellt werden muss. Beispiel: http://user:password@10.10.10.10:8888. String

Nachdem Sie Ihre ClientConfig abgeschlossen haben, speichern Sie die Datei, wodurch die ClientConfig in Ihrem Cluster aktualisiert wird. Bei Syntaxfehlern werden Sie aufgefordert, die Konfiguration noch einmal zu bearbeiten, um sie zu beheben.

Anbieterspezifische Konfigurationen

Dieser Abschnitt enthält Konfigurationsanleitungen für einige beliebte OIDC-Anbieter, einschließlich Beispielkonfigurationen, die Sie kopieren und mit Ihren eigenen Details bearbeiten können.

Azure AD

Dies ist die Standardkonfiguration für die Einrichtung von GKE Identity Service mit Azure AD. Mit dieser Konfiguration kann GKE Identity Service Informationen zur Nutzer- und Gruppenmitgliedschaft von Azure AD abrufen und die rollenbasierte Zugriffssteuerung (RBAC) von Kubernetes basierend auf Gruppen einrichten. Bei dieser Konfiguration können jedoch nur etwa 200 Gruppen pro Nutzer abgerufen werden.

Wenn Sie mehr als 200 Gruppen pro Nutzer abrufen müssen, lesen Sie die Anleitung für Azure AD (Erweitert).

...
spec:
  authentication:
  - name: oidc-azuread
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Ersetzen Sie Folgendes:

  • CLIENT_ID: Die Client-ID, die bei der Registrierung von GKE Identity Service bei Ihrem Anbieter zurückgegeben wurde.
  • CLIENT_SECRET: Gemeinsames Secret der OIDC-Clientanwendung und des OIDC-Anbieters.
  • TENANT: Die Art des zu authentifizierenden Azure AD-Kontos. Unterstützte Werte sind die Mandanten-ID oder der Mandantenname für Konten, die zu einem bestimmten Mandanten gehören. Der Name des Mandanten wird auch als primäre Domain bezeichnet. Weitere Informationen zum Ermitteln dieser Werte finden Sie unter Microsoft Azure AD-Mandanten-ID und Namen der primären Domain finden.
  • PORT: Die Portnummer, die für die von der gcloud CLI verwendete Weiterleitungs-URL ausgewählt und von Ihrem Plattformadministrator bei der Registrierung angegeben wurde.

Azure AD (Erweitert)

Mit dieser optionalen Konfiguration für Azure AD kann GKE Identity Service Nutzer- und Gruppeninformationen mit unbegrenzter Anzahl von Gruppen pro Nutzer über die Microsoft Graph API abrufen.

Informationen zu Plattformen, die diese Konfiguration unterstützen, finden Sie unter Erweiterte Einrichtung für Azure AD.

Wenn Sie weniger als 200 Gruppen pro Nutzer abrufen müssen, empfehlen wir die Verwendung der Standardkonfiguration mit einem oidc-Anchor in Ihrer ClientConfig. Weitere Informationen finden Sie in der Anleitung für Azure AD.

Alle Felder in der folgenden Beispielkonfiguration sind erforderlich.

...
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Ersetzen Sie Folgendes:

  • NAME: Der Name, den Sie dieser Konfiguration zuweisen möchten, normalerweise der Name des Identitätsanbieters. Ein Konfigurationsname muss mit einem Buchstaben beginnen, gefolgt von bis zu 39 Kleinbuchstaben, Zahlen oder Bindestrichen. Das letzte Zeichen darf kein Bindestrich sein.
  • PROXY_URL: Proxyserver-Adresse, die gegebenenfalls zum Herstellen einer Verbindung mit dem Identitätsanbieter verwendet werden soll. Diese Angabe ist möglicherweise erforderlich, wenn sich der Cluster beispielsweise in einem privaten Netzwerk befindet und eine Verbindung zu einem öffentlichen Identitätsanbieter hergestellt werden muss. Beispiel: http://user:password@10.10.10.10:8888
  • CLIENT_ID: Die Client-ID, die bei der Registrierung von GKE Identity Service bei Ihrem Anbieter zurückgegeben wurde.
  • CLIENT_SECRET: Gemeinsames Secret der OIDC-Clientanwendung und des OIDC-Anbieters.
  • TENANT: Die Art des zu authentifizierenden Azure AD-Kontos. Unterstützte Werte sind die Mandanten-ID oder der Mandantenname für Konten, die zu einem bestimmten Mandanten gehören. Der Name des Mandanten wird auch als primäre Domain bezeichnet. Weitere Informationen zum Ermitteln dieser Werte finden Sie unter Microsoft Azure AD-Mandanten-ID und Namen der primären Domain finden.
  • PORT: Die Portnummer, die für die von der gcloud CLI verwendete Weiterleitungs-URL ausgewählt und von Ihrem Plattformadministrator bei der Registrierung angegeben wurde.
  • GROUP_FORMAT: das Format, in dem Sie Gruppeninformationen abrufen möchten. Dieses Feld kann Werte haben, die der ID oder dem NAME der Nutzergruppen entsprechen. Beachten Sie, dass diese Einstellung derzeit nur für Cluster in Bare-Metal-Bereitstellungen von Google Distributed Cloud verfügbar ist.
  • USER_CLAIM (Optional): Die JWT-Anforderung (Feldname), die Ihr Anbieter zur Identifizierung eines Kontos verwendet. Wenn Sie hier keinen Wert angeben, verwendet GKE Identity Service einen Wert in der Reihenfolge „email“, „preferred_username“ oder „sub“, um die Nutzerdetails abzurufen. Dieses Attribut kann ab GKE Enterprise Version 1.28 verwendet werden.

Okta

Im Folgenden wird gezeigt, wie Sie die Authentifizierung mithilfe von Nutzern und Gruppen mit Okta als Identitätsanbieter einrichten. Mit dieser Konfiguration kann Anthos Identity Service Nutzer- und Gruppenanforderungen mithilfe eines Zugriffstokens und des userinfo-Endpunkts von Okta abrufen.

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Einschränkungen für den Gruppenzugriff

Bei Okta-Nutzern kann Anthos Identity Service Gruppeninformationen für Nutzer abrufen, deren Gruppennamen zusammengenommen (verkettet) eine Länge von weniger als 170.000 Zeichen haben. In Anbetracht der maximalen Gruppenlänge in Okta entspricht dies einer Mitgliedschaft in etwa 650 Gruppen. Wenn der Nutzer Mitglied in zu vielen Gruppen ist, schlägt der Authentifizierungsaufruf fehl.

Nächste Schritte

Nachdem die Konfiguration angewendet wurde, richten Sie den Nutzerzugriff auf Cluster ein.