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, beispielsweisehttps://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 istsub
. Dies ist eine eindeutige ID des Endnutzers. Je nach OpenID-Anbieter können Sie andere Anforderungen auswählen, wie beispielsweiseemail
odername
. Allerdings wird anderen Anforderungen alsemail
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 undusername
ein anderer Wert alsemail
ist, wird standardmäßig das Präfixissuerurl#
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 istgid-foobar
für die Gruppefoobar
und das Präfixgid-
.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.- Eine Liste der Authentifizierungsparameter finden Sie unter Authentifizierungs-URI-Parameter.
- Eine Liste der Authentifizierungsparameter von Microsoft Azure erhalten Sie unter Senden der Anmeldeanforderung.
- Wenn Sie eine Gruppe autorisieren, geben Sie
resource=token-groups-claim
ein. - Wenn Ihr Autorisierungsserver zur Zustimmung auffordert, geben Sie
prompt=consent
ein.
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.- Eine Liste der Authentifizierungsparameter finden Sie unter Authentifizierungs-URI-Parameter.
- Wenn Sie eine Gruppe autorisieren, geben Sie
resource=token-groups-claim
ein. - Wenn Ihr Autorisierungsserver zur Zustimmung auffordert, geben Sie
prompt=consent
ein.
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.- Eine Liste der Authentifizierungsparameter von Google finden Sie unter Authentifizierungs-URI-Parameter.
- Eine Liste der Authentifizierungsparameter von Microsoft Azure erhalten Sie unter Senden der Anmeldeanforderung.
- Wenn Sie eine Gruppe autorisieren, geben Sie
resource=token-groups-claim
ein. - Wenn Ihr Autorisierungsserver zur Zustimmung auffordert, geben Sie
prompt=consent
ein.
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.
-
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 vonkubectl oidc login
ausführen. -
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.
-
Prüfen Sie, ob Ihr Cluster für OIDC konfiguriert ist.
-
Prüfen Sie, ob Ihr Cluster für Google Cloud registriert wurde, entweder automatisch während der Erstellung des Clusters oder manuell.
-
Rufen Sie in der Google Cloud Console die Seite Kubernetes-Cluster auf.
-
Ermitteln Sie in der Liste der Cluster Ihren GKE On-Prem-Cluster und klicken Sie auf Anmelden.
-
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.