Für die gcloud CLI authentifizieren

In diesem Dokument geht es nur um die Authentifizierung für die Google Cloud CLI für den Zugriff aufGoogle Cloud -Ressourcen. Wenn Sie Arbeitslasten mit Cloud-Clientbibliotheken oder Google API-Clientbibliotheken authentifizieren müssen, lesen Sie den Abschnitt Funktionsweise von Standardanmeldedaten für Anwendungen.

Hinweis

Wenn Sie neu bei Google Cloud sind und nur mit der Verwendung von gcloud CLI-Befehlen in Ihrer lokalen Entwicklungsumgebung beginnen möchten, können Sie die gcloud CLI mit dem folgenden Befehl initialisieren:

gcloud init

Bei der Initialisierung werden Sie durch einen Authentifizierungsvorgang geführt, eine gcloud CLI-Konfiguration wird eingerichtet und die gcloud CLI wird autorisiert, in Ihrem Namen zu agieren. Ein separater Authentifizierungsschritt ist nicht erforderlich.

Im Rest dieses Dokuments werden komplexere Szenarien behandelt, z. B. die Verwendung der gcloud CLI mit verschiedenen Prinzipaltypen, geeignete Authentifizierungsmethoden für verschiedene Umgebungen, das Wechseln von Prinzipalen und die Verwaltung gespeicherter Anmeldedaten.

Authentifizierungsmethoden

Für alle gcloud CLI-Befehle muss die Authentifizierung für Google CloudAPIs erfolgen. Sie können sich auf folgende Arten authentifizieren:

• Anmeldedaten autorisieren und speichern: Geeignet für die Verwendung durch Menschen in einer lokalen Entwicklungsumgebung. Sie können die gcloud CLI mit dem Befehl gcloud auth login autorisieren, im Namen eines Principals zu agieren. Nach der ersten Authentifizierung werden mit diesem Befehl Anmeldedaten im Konfigurationsverzeichnis der gcloud CLI gespeichert. Die gcloud CLI verwendet diese gespeicherten Anmeldedaten zur automatischen Authentifizierung für nachfolgende Befehle, bis Ihre Sitzung abläuft oder Sie die Autorisierung widerrufen.

• Mit einer Anmeldedatendatei authentifizieren: Geeignet für Arbeitslasten, die außerhalb von Google Cloudausgeführt werden. Sie können Umgebungsvariablen oder gcloud CLI-Konfigurationseigenschaften verwenden, um eine Datei mit Anmeldedaten für die automatische Authentifizierung anzugeben. Diese Datei kann eine der folgenden sein:

  • Eine Konfigurationsdatei für Anmeldedaten für die Workload Identity-Föderation.

  • Einen Dienstkontoschlüssel.

• Zugriffstoken bereitstellen: Geeignet für hochgradig isolierte automatisierte Workflows oder zustandslose Sitzungen auf gemeinsam genutzten Maschinen. Sie können den Anmeldedatenspeicher umgehen, indem Sie der gcloud CLI direkt ein Zugriffstoken bereitstellen. Dazu können Sie eine bestimmte Umgebungsvariable auf den Rohstring des Zugriffstokens festlegen oder die gcloud CLI auf eine Datei verweisen, die das Zugriffstoken enthält.

Nach der Authentifizierung können Sie die gcloud CLI optional die Identität eines Dienstkontos übernehmen lassen, indem Sie die E-Mail-Adresse des Dienstkontos angeben.

Sie können in einer einzelnen Umgebung mehrere Authentifizierungsmethoden verwenden. Für jeden gcloud-Befehl wird jedoch nur ein Hauptkonto verwendet. Um zu ermitteln, welcher Prinzipal verwendet werden soll, folgt die gcloud CLI einer Prioritätsreihenfolge.

Wann keine Authentifizierung erforderlich ist

In den folgenden Situationen müssen Sie sich nicht für die gcloud CLI authentifizieren:

• Unmittelbar nach der Initialisierung der gcloud CLI. Die Authentifizierung und Autorisierung der gcloud CLI, in Ihrem Namen zu handeln, sind im Initialisierungsprozess enthalten. Möglicherweise müssen Sie sich noch einmal authentifizieren, wenn Sie mit einem anderen Hauptkonto auf verschiedene Ressourcen zugreifen müssen oder Sie Ihr Hauptkonto neu authentifizieren müssen.
• Bei Verwendung der gcloud CLI über eine Ressource, die einen Compute Engine- Metadatenserver bereitstellt. Dazu gehören Ressourcen wie Compute Engine-VM-Instanzen, Cloud Run-Dienste und Cloud Build-Builds. Die gcloud CLI authentifiziert sich mit dem Dienstkonto, das an die VM angehängt ist, und kann innerhalb der Grenzen aller angewendeten Zugriffsbereiche auf dieselben Ressourcen wie dieses Dienstkonto zugreifen.
• Bei Verwendung von Cloud Shell Die gcloud CLI authentifiziert sich automatisch mit dem Konto, mit dem Sie sich in der Google Cloud Console angemeldet haben. Wenn Sie einen gcloud CLI-Befehl zum ersten Mal in einer neuen Cloud Shell-Sitzung ausführen, werden Sie aufgefordert, Cloud Shell mit diesem Prinzipal zu autorisieren.

Das richtige Hauptkonto für die Aufgabe auswählen

Es gibt verschiedene Arten von Identitäten für die Nutzung durch Menschen und für automatisierte Arbeitslasten. Der Hauptkontotyp, den Sie verwenden müssen, wirkt sich darauf aus, wie Sie sich authentifizieren.

• Nutzerkonten: Dies sind Google-Konten, die für interaktive Aufgaben von Menschen vorgesehen sind, z. B. gelegentliche administrative Aufgaben, nicht programmatische Konfiguration von Google Cloud -Diensten, Tests, Experimente und Beobachtbarkeit.

  Sie authentifizieren sich als Nutzerkonto mit Nutzeranmeldedaten wie einem Passwort und einem Einmalcode.

• Dienstkonten: Dies sind Konten, die speziell für Google Cloud sind und von Arbeitslasten verwendet werden können, um auf Dienste oder Ressourcen zuzugreifen. Normalerweise authentifizieren Sie sich nicht direkt als Dienstkonto. Stattdessen hängen Sie ein Dienstkonto an eine Ressource wie eine Compute Engine-VM an oder verwenden die Identitätsübernahme des Dienstkontos.

• Föderierte Hauptkonten: Das sind Identitäten, die auf Nutzer- oder Dienstkonten bei einem externen Identitätsanbieter verweisen. Es gibt zwei Arten von föderierten Hauptkonten, die von Google Cloudunterstützt werden und ähnliche Namen haben:

  • Mitarbeiteridentitätsföderation: Ermöglicht es menschlichen Nutzern, sich mit Identitäten, die von einem externen Identitätsanbieter verwaltet werden, bei Google Cloud anzumelden. Wenn in Ihrer Organisation bereits die Einmalanmeldung (SSO) eingerichtet ist, können Sie diesen Identitätstyp möglicherweise zur Authentifizierung bei Google Cloudverwenden.

    Ihr Identitätsanbieter muss OpenID Connect (OIDC) oder SAML 2.0 unterstützen, damit Sie die Mitarbeiteridentitätsföderation verwenden können.

  • Identitätsföderation von Arbeitslasten: Ermöglicht es Arbeitslasten, die außerhalb von Google Cloud ausgeführt werden, auf Google Cloud Ressourcen zuzugreifen.

    Sie können die Workload Identity-Föderation mit Arbeitslasten verwenden, die sich mit X.509-Clientzertifikaten authentifizieren, die auf Amazon Web Services (AWS) oder Azure, Active Directory vor Ort, Bereitstellungsdiensten wie GitHub und GitLab und mit einem beliebigen Identitätsanbieter ausgeführt werden, der OpenID Connect (OIDC) oder Security Assertion Markup Language (SAML) V2.0 unterstützt.

gcloud CLI als Mensch verwenden

Bei interaktiven Aufgaben authentifizieren Sie sich in der Regel mit einer der folgenden Methoden:

• Ein Nutzerkonto

• Eine föderierte Nutzeridentität mit der Mitarbeiteridentitätsföderation

Nutzerkonten

Wie Sie sich mit einem Nutzerkonto für die gcloud CLI authentifizieren, hängt davon ab, ob auf Ihrem Gerät ein Webbrowser installiert ist.

Identitäten föderierter Nutzer

Sie können die gcloud CLI mit einer föderierten Nutzeridentität verwenden, die in einem externen Identitätsanbieter (IdP) verwaltet wird. Dazu verwenden Sie die Workforce Identity-Föderation.

Bei der folgenden Anleitung wird davon ausgegangen, dass Sie bereits einen Pool und einen Anbieter für die Mitarbeiteridentitätsföderation eingerichtet haben, die mit Ihrem IdP funktionieren.

Wenn Sie die gcloud CLI mit einer föderierten Nutzeridentität verwenden möchten, erstellen Sie eine Anmeldekonfigurationsdatei und melden sich dann über einen browserbasierten Ablauf an:

1. Führen Sie den folgenden Befehl aus, um eine Konfigurationsdatei für die Anmeldung zu erstellen:

   Linux und macOS

   gcloud iam workforce-pools create-login-config \
       locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
       --output-file=LOGIN_CONFIG_PATH

   Windows (PowerShell)

   gcloud iam workforce-pools create-login-config `
       locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
       --output-file=LOGIN_CONFIG_PATH

   Ersetzen Sie Folgendes:

   • WORKFORCE_POOL_ID: Die ID des Workforce Identity Federation-Pools.
   • WORKFORCE_PROVIDER_ID: Die ID des Anbieters der Mitarbeiteridentitätsföderation.
   • LOGIN_CONFIG_PATH: Der Pfad, in den die Anmeldekonfigurationsdatei geschrieben werden soll. Beispiel: login-config.json.

   Die Konfigurationsdatei für die Anmeldung enthält die Endpunkte, die von der gcloud CLI verwendet werden, um den browserbasierten Authentifizierungsvorgang zu aktivieren und die Zielgruppe auf den IdP festzulegen, der im Workforce Identity-Poolanbieter konfiguriert wurde. Die Datei enthält keine vertraulichen Informationen.

   Der Inhalt der Anmeldekonfigurationsdatei sieht in etwa so aus:

   {
     "universe_domain": "googleapis.com",
     "universe_cloud_web_domain": "cloud.google",
     "type": "external_account_authorized_user_login_config",
     "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
     "auth_url": "https://auth.cloud.google/authorize",
     "token_url": "https://sts.googleapis.com/v1/oauthtoken",
     "token_info_url": "https://sts.googleapis.com/v1/introspect"
   }

2. Verweisen Sie mit einer Umgebungsvariable oder einem Attribut in der aktiven gcloud CLI-Konfiguration auf die Konfigurationsdatei für die Anmeldung oder verwenden Sie sie direkt mit dem Befehl gcloud auth login:

   Umgebungsvariable

   So verwenden Sie die Konfigurationsdatei für die Anmeldung mit einer Umgebungsvariable:

   1. Legen Sie die Umgebungsvariable CLOUDSDK_AUTH_LOGIN_CONFIG_FILE auf den Pfad der Anmeldekonfigurationsdatei fest.

   2. Führen Sie dazu diesen Befehl aus:

      gcloud auth login

   3. Die gcloud CLI verweist auf die Umgebungsvariable, um die Anmeldekonfigurationsdatei zu finden, und startet dann den Authentifizierungsprozess. Folgen Sie dem browserbasierten Ablauf, um die gcloud CLI zu authentifizieren und zu autorisieren, damit sie in Ihrem Namen auf Ressourcen für zukünftige Befehle zugreifen kann.

   Wenn Sie die Konfigurationsdatei für die Anmeldung für gcloud auth login-Befehle nicht mehr verwenden möchten, löschen Sie die Umgebungsvariable CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

   gcloud CLI-Konfiguration

   So verwenden Sie die Konfigurationsdatei für die Anmeldung mit einer Konfigurationseigenschaft der gcloud CLI:

   1. Legen Sie das Attribut auth/login_config_file der aktiven gcloud CLI-Konfiguration mit dem folgenden Befehl auf den Pfad der Anmeldekonfigurationsdatei fest:

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

   2. Führen Sie dazu diesen Befehl aus:

      gcloud auth login

   3. Die gcloud CLI verweist auf das Konfigurationsattribut, um die Anmeldekonfigurationsdatei zu finden, und startet dann den Authentifizierungsprozess. Folgen Sie dem browserbasierten Ablauf, um die gcloud CLI zu authentifizieren und zu autorisieren, damit sie in Ihrem Namen auf Ressourcen für zukünftige Befehle zugreifen kann.

   Wenn Sie die Konfigurationsdatei für die Anmeldung nicht mehr für gcloud auth login-Befehle verwenden möchten, heben Sie die Einstellung der Property mit dem folgenden Befehl auf:

   gcloud config unset auth/login_config_file

   gcloud auth login

   Wenn Sie die Konfigurationsdatei für die Anmeldung direkt mit dem Befehl gcloud auth login verwenden möchten, folgen Sie dieser Anleitung:

   • Wenn Sie das Flag --activate beim Erstellen der Konfigurationsdatei für die Anmeldung verwendet haben, führen Sie den folgenden Befehl aus:

     gcloud auth login

   • Wenn Sie das Flag --activate beim Erstellen der Konfigurationsdatei für die Anmeldung nicht verwendet haben, führen Sie den folgenden Befehl aus:

     Linux und macOS

     gcloud auth login \
         --login-config=LOGIN_CONFIG_PATH

     Windows (PowerShell)

     gcloud auth login `
         --login-config=LOGIN_CONFIG_PATH

     Ersetzen Sie LOGIN_CONFIG_PATH durch den Pfad Ihrer Anmeldekonfigurationsdatei.

   Mit dem Befehl gcloud auth login werden Anmeldedaten für den Zugriff in Ihrem Basisverzeichnis gespeichert. Das authentifizierte Hauptkonto wird zum aktiven Hauptkonto in Ihrer aktiven gcloud CLI-Konfiguration. Sofern nicht anders angegeben, verwendet die gcloud CLI diese gespeicherten Anmeldedaten für den Zugriff auf Google Cloud.

gcloud CLI mit Arbeitslasten verwenden

Bei automatisierten Arbeitslasten authentifizieren Sie sich in der Regel mit einer der folgenden Methoden:

• Eine föderierte Arbeitslastidentität mit der Workload Identity-Föderation

• Ein Dienstkonto mit Identitätsübernahme

Föderierte Arbeitslastidentitäten

Sie können die gcloud CLI mit einer föderierten Arbeitslastidentität verwenden. Dazu verwenden Sie die Workload Identity-Föderation.

Eine Arbeitslast kann entweder direkt auf Google Cloud Ressourcen zugreifen, indem sie als Hauptkonto fungiert, das durch einen Workload Identity-Pool definiert wird, oder die Identität eines Dienstkontos übernehmen, das an einen Workload Identity-Pool angehängt ist.

Wir empfehlen die Verwendung der Methode für direkten Zugriff, um Dienstkonten mit zu vielen Berechtigungen zu vermeiden und den Ressourcenzugriff mit der Kennung des föderierten Principals zu protokollieren. Verwenden Sie die Identitätsübernahme des Dienstkontos nur, wenn Google Cloud APIs die Workload Identity-Föderation nicht unterstützen.

In der folgenden Anleitung wird davon ausgegangen, dass Sie bereits einen Pool und einen Anbieter für die Identitätsföderation von Arbeitslasten eingerichtet haben, die mit Ihrem IdP funktionieren.

1. Erstellen Sie eine Konfigurationsdatei für Anmeldedaten für die Workload Identity-Föderation, indem Sie der Anleitung für Ihren unterstützten Identitätsanbieter folgen.

2. Definieren Sie den Pfad zur Konfigurationsdatei für Anmeldedaten in einer Umgebungsvariablen, als Attribut in der aktiven gcloud CLI-Konfiguration oder mit dem Befehl gcloud auth login:

   Umgebungsvariable

   Legen Sie die Umgebungsvariable CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE auf den Pfad der Konfigurationsdatei für Anmeldedaten fest. Die gcloud CLI verweist bei jedem Ausführen eines Befehls auf die Datei und ruft Anmeldedaten von Ihrem Identitätsanbieter ab. Diese Anmeldedaten werden gegen ein Zugriffstoken für Google Cloudeingetauscht.

   Wenn Sie die Anmeldedaten-Konfigurationsdatei nicht mehr verwenden möchten, löschen Sie die Umgebungsvariable CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

   gcloud CLI-Konfiguration

   Legen Sie das Attribut auth/credential_file_override der aktiven gcloud CLI-Konfiguration mit dem folgenden Befehl auf den Pfad der Anmeldedatenkonfigurationsdatei fest:

   gcloud config set auth/credential_file_override CONFIGURATION_PATH
   

   Ersetzen Sie CONFIGURATION_PATH durch den Pfad zur Konfigurationsdatei für Anmeldedaten.

   Wenn Sie die Konfigurationsdatei für Anmeldedaten nicht mehr standardmäßig für gcloud-Befehle verwenden möchten, heben Sie die Einstellung der Property mit dem folgenden Befehl auf:

   gcloud config unset auth/credential_file_override
   

   gcloud auth login

   Führen Sie den folgenden Befehl mit dem Flag --cred-file aus:

   Linux und macOS

   gcloud auth login \
       --cred-file=CONFIGURATION_PATH
   

   Windows (PowerShell)

   gcloud auth login `
       --cred-file=CONFIGURATION_PATH
   

   Ersetzen Sie CONFIGURATION_PATH durch den Pfad zu einer Konfigurationsdatei für Anmeldedaten.

   Mit dem Befehl gcloud auth login werden Anmeldedaten für den Zugriff in Ihrem Basisverzeichnis gespeichert. Das authentifizierte Hauptkonto wird zum aktiven Hauptkonto in Ihrer aktiven gcloud CLI-Konfiguration. Sofern nicht anders angegeben, verwendet die gcloud CLI diese gespeicherten Anmeldedaten für den Zugriff auf Google Cloud.

Dienstkonten

Sie können die gcloud CLI mit einem Dienstkonto auf folgende Weise verwenden:

• Auf einer Ressource, die einen Compute Engine-Metadatenserver bereitstellt, z. B. eine Compute Engine-VM-Instanz oder ein Cloud Run-Dienst. Die gcloud CLI verwendet standardmäßig das Dienstkonto, das der Ressource zugeordnet ist, für die Authentifizierung.

• Ein anderes Hauptkonto verwenden, um die Identität eines Dienstkontos zu übernehmen.

• Mit einem Dienstkontoschlüssel.