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 Workloads mit Cloud-Clientbibliotheken oder Google API-Clientbibliotheken authentifizieren müssen, lesen Sie den Abschnitt 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 Personen 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 Computern. 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 mehrere Authentifizierungsmethoden in einer einzelnen Umgebung verwenden. Für einen bestimmten gcloud-Befehl wird jedoch nur ein Prinzipal 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. Authentifizierung und Autorisierung sind im Initialisierungsprozess enthalten. Möglicherweise müssen Sie sich noch einmal authentifizieren, wenn Sie mit einem anderen Prinzipal auf verschiedene Ressourcen zugreifen oder Ihren Prinzipal 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 ist autorisiert, auf dieselben Ressourcen wie dieses Dienstkonto zuzugreifen, sofern keine Zugriffsbereiche angewendet wurden.
  • 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-Befehlszeilenbefehl 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:

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.

Mein Gerät hat einen Webbrowser

Führen Sie die folgenden Schritte aus, um sich mit einem Nutzerkonto auf einem Gerät mit einem Webbrowser zu authentifizieren:

  1. Führen Sie den folgenden Befehl aus, um den Vorgang zu starten:

    gcloud auth login

  2. Folgen Sie dem browserbasierten Ablauf, um die gcloud CLI zu authentifizieren und zu autorisieren, damit sie bei zukünftigen Befehlen in Ihrem Namen auf Ressourcen zugreifen kann.

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

Auf meinem Gerät ist kein Webbrowser installiert

Wenn auf dem Gerät, auf dem Sie die gcloud CLI verwenden möchten, kein Webbrowser installiert ist, können Sie sich mit Ihrem Nutzerkonto auf einem anderen vertrauenswürdigen Gerät authentifizieren. Dieser Vorgang hängt von der auf dem anderen vertrauenswürdigen Gerät installierten Software ab.

Mit einem anderen vertrauenswürdigen Gerät authentifizieren

Wählen Sie aus, welche Software auf dem anderen vertrauenswürdigen Gerät verfügbar ist.

Die gcloud CLI und ein Webbrowser

Verwenden Sie das Flag --no-browser, um den Authentifizierungsvorgang auf einem anderen Gerät mit einem Webbrowser und der installierten gcloud CLI abzuschließen:

  1. Führen Sie den folgenden Befehl auf dem ursprünglichen Gerät aus, auf dem Sie die gcloud CLI verwenden möchten:

    Linux und macOS 

    gcloud auth login \
    --no-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-browser

  2. Kopieren Sie den gcloud-Befehl, der mit gcloud auth login --remote-bootstrap=" beginnt, um ihn auf dem anderen Gerät zu verwenden.

  3. Rufen Sie ein anderes vertrauenswürdiges Gerät auf, auf dem sowohl ein Webbrowser als auch die gcloud CLI-Version 372.0.0 oder höher installiert sind.

  4. Führen Sie im Terminal den zuvor kopierten Befehl aus, der mit gcloud auth login --remote-bootstrap=" beginnt, und schließen Sie den browserbasierten Ablauf ab.

  5. Kopieren Sie im Terminal die URL, die mit https://localhost beginnt, um sie auf dem ursprünglichen Gerät zu verwenden.

  6. Kehren Sie zum ursprünglichen Gerät zurück.

  7. Fügen Sie im Terminal an der Eingabeaufforderung die https://localhost-URL ein, die Sie zuvor kopiert haben. Drücken Sie die Eingabetaste oder die Returntaste auf der Tastatur, um den Vorgang abzuschließen.

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

Nur Webbrowser

Verwenden Sie das Flag --no-launch-browser, um die Authentifizierung über den Webbrowser eines anderen Geräts abzuschließen:

  1. Führen Sie den folgenden Befehl auf dem ursprünglichen Gerät aus, auf dem Sie die gcloud CLI verwenden möchten:

    Linux und macOS 

    gcloud auth login \
    --no-launch-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-launch-browser

  2. Kopieren Sie die URL, die mit https://accounts.google.com/o/oauth2/auth beginnt, um sie auf dem anderen Gerät zu verwenden.

  3. Rufen Sie ein anderes vertrauenswürdiges Gerät auf, auf dem ein Webbrowser installiert ist.

  4. Öffnen Sie einen Webbrowser, rufen Sie die URL auf, die Sie zuvor kopiert haben, und schließen Sie den browserbasierten Ablauf ab.

  5. Kopieren Sie den Bestätigungscode, um ihn auf dem ursprünglichen Gerät zu verwenden.

  6. Kehren Sie zum ursprünglichen Gerät zurück.

  7. Fügen Sie den zuvor kopierten Bestätigungscode in das Terminal ein. Drücken Sie die Eingabetaste oder die Returntaste auf der Tastatur, um den Vorgang abzuschließen.

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

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 Mitarbeiteridentitätsfö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 Pools für die Mitarbeiteridentitätsföderation.
    • 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. Der authentifizierte Prinzipal wird zum aktiven Prinzipal 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 Workload Identity verwenden. Dazu nutzen 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 Methode für direkten Zugriff zu verwenden, um Dienstkonten mit zu vielen Berechtigungen zu vermeiden und den Ressourcenzugriff mit der Kennung des föderierten Hauptkontos zu protokollieren. Verwenden Sie die Identitätsübernahme des Dienstkontos nur, wenn Google Cloud -APIs die Workload Identity-Föderation nicht unterstützen.

Bei der folgenden Anleitung wird davon ausgegangen, dass Sie bereits einen Workload Identity-Föderationspool und ‑Anbieter für die Zusammenarbeit mit Ihrem IdP eingerichtet haben.

  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. Der authentifizierte Prinzipal wird zum aktiven Prinzipal 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.

Identitätsübernahme des Dienstkontos

Für den Ressourcenzugriff, der Ihrem Hauptkonto normalerweise nicht zur Verfügung steht, empfehlen wir, die Eskalation von Berechtigungen mit Privileged Access Manager zu verwalten, anstatt die Identitätsübernahme des Dienstkontos zu verwenden.

Wenn Privileged Access Manager nicht zu Ihrem Anwendungsfall passt, führen Sie die folgenden Schritte aus, um die gcloud CLI mit einem Dienstkonto zu verwenden:

  1. Wenn Sie die Identität eines Dienstkontos übernehmen möchten, muss die Service Account Credentials API in Ihrem Projekt aktiviert sein.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

    API aktivieren

  2. Wählen Sie ein Hauptkonto aus, mit dem die Identität eines Dienstkontos übernommen werden soll.

  3. Bitten Sie Ihren Administrator, dem Hauptkonto die IAM-Rolle Dienstkonto-Token-Ersteller (roles/iam.serviceAccountTokenCreator) für das Dienstkonto zuzuweisen, damit das Hauptkonto die erforderliche Berechtigung hat, die Identität eines Dienstkontos zu übernehmen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Diese vordefinierte Rolle enthält die Berechtigung iam.serviceAccounts.getAccessToken, die erforderlich ist, um die Identität eines Dienstkontos zu übernehmen.

    Ihr Administrator kann dem Hauptkonto möglicherweise auch diese Berechtigung mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erteilen.

  4. Authentifizieren Sie sich für die gcloud CLI mit dem zuvor ausgewählten Hauptkonto, unabhängig davon, ob es sich um ein Nutzerkonto, eine föderierte Nutzeridentität, eine föderierte Arbeitslastidentität oder ein anderes Dienstkonto handelt.

  5. Wählen Sie ein Dienstkonto aus, dessen Identität übernommen werden soll. Sie können entweder ein vorhandenes Dienstkonto suchen oder ein neues Dienstkonto erstellen.

  6. Kopieren Sie die E-Mail-Adresse des Dienstkontos.

  7. Wählen Sie aus, ob die Identität des Dienstkontos für alle Befehle oder nur für einen einzelnen Befehl übernommen werden soll:

    Alle Befehle

    Wenn Sie die Identitätsübernahme des Dienstkontos mit der gcloud CLI für zukünftige Befehle verwenden möchten, können Sie eine Umgebungsvariable oder eine Eigenschaft in der aktiven gcloud CLI-Konfiguration festlegen:

    • Umgebungsvariable: Legen Sie die Umgebungsvariable CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT auf die E-Mail-Adresse des Dienstkontos fest.

      Wenn Sie das Dienstkonto nicht mehr verwenden möchten, löschen Sie die Umgebungsvariable CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

    • gcloud CLI-Konfiguration: Legen Sie das Attribut auth/impersonate_service_account der aktiven gcloud CLI-Konfiguration mit dem folgenden Befehl fest:

      gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL

      Ersetzen Sie SERVICE_ACCOUNT_EMAIL durch die E-Mail-Adresse des Dienstkontos.

      Wenn Sie die Identitätsübernahme des Dienstkontos 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/impersonate_service_account

    Einzelner Befehl

    Wenn Sie die Identitätsübernahme des Dienstkontos mit der gcloud CLI für einen einzelnen Befehl verwenden möchten, können Sie einem gcloud CLI-Dienstbefehl das Flag --impersonate-service-account hinzufügen.

    Wenn Sie beispielsweise Compute Engine-VM-Instanzen mithilfe der Identitätsübernahme des Dienstkontos auflisten möchten, führen Sie den folgenden Befehl aus:

    Linux und macOS 

    gcloud compute instances list \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Windows (PowerShell) 

    gcloud compute instances list `
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Ersetzen Sie SERVICE_ACCOUNT_EMAIL durch die E-Mail-Adresse des Dienstkontos.

Dienstkontoschlüssel

Wir empfehlen, für die meisten Arbeitslasten, die außerhalb von Google Cloudausgeführt werden, die Workload Identity-Föderation zu verwenden. Verwenden Sie Dienstkontoschlüssel nur, wenn Ihre Arbeitslast in einer isolierten externen Umgebung ausgeführt wird, die die Workload Identity-Föderation nicht unterstützt.

Die Identitätsföderation von Arbeitslasten bietet die folgenden Vorteile:

  • Der Zugriff auf Ressourcen wird über Identity and Access Management (IAM) gewährt. Dabei werden Arbeitslasten als einzelne Hauptkonten behandelt. Das bedeutet, dass Sie ein Dienstkonto nicht für mehrere Anwendungsfälle überberechtigen müssen.

  • Sie können prüfen, welche Arbeitslast welche Aufgabe ausführt. Aktionen werden nicht hinter der E-Mail-Adresse eines Dienstkontos verborgen.

  • Bei der Workload Identity-Föderation werden kurzlebige Zugriffstokens verwendet, um das Risiko von Datenexfiltration zu verringern. Dienstkontoschlüssel laufen nicht ab, sofern sie nicht manuell widerrufen werden.

So verwenden Sie ein Dienstkonto mit der gcloud CLI für zukünftige Befehle:

  1. Erstellen Sie einen Dienstkontoschlüssel und speichern Sie ihn als Datei an einem sicheren Ort in Ihrer Umgebung.

  2. Definieren Sie den Pfad zur Dienstkontoschlüsseldatei in einer Umgebungsvariable, 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 Dienstkontoschlüsseldatei fest.

      Wenn Sie den Dienstkontoschlüssel nicht mehr verwenden möchten, löschen Sie die Umgebungsvariable CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    • gcloud CLI-Konfiguration: Legen Sie mit dem folgenden Befehl den Pfad des Dienstkontoschlüssels für das Attribut auth/credential_file_override der aktiven gcloud CLI-Konfiguration fest:

      gcloud config set auth/credential_file_override KEY_PATH

      Ersetzen Sie KEY_PATH durch den Pfad zur Dienstkontoschlüsseldatei.

      Wenn Sie den Dienstkontoschlüssel nicht mehr standardmäßig für gcloud-Befehle verwenden möchten, heben Sie die Einstellung des Attributs 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=KEY_PATH

      Windows (PowerShell) 

      gcloud auth login `
    --cred-file=KEY_PATH

      Ersetzen Sie KEY_PATH durch den Pfad zur Dienstkontoschlüsseldatei.

      Mit dem Befehl gcloud auth login werden Anmeldedaten für den Zugriff in Ihrem Basisverzeichnis gespeichert. Der authentifizierte Prinzipal wird zum aktiven Prinzipal 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 einem Zugriffstoken verwenden

Wenn Sie sich bereits auf einem anderen Gerät für die gcloud CLI authentifiziert haben, können Sie mit dem folgenden Befehl ein Zugriffstoken für den aktiven Prinzipal dieses Geräts abrufen:

gcloud auth print-access-token

Sie können dieses Zugriffstoken dann auf einem anderen Gerät verwenden, um auf Google Cloud-Ressourcen zuzugreifen. Durch die Verwendung eines Zugriffstokens ist es nicht erforderlich, einen aktiven Prinzipal festzulegen. Außerdem wird jeder aktive Prinzipal überschrieben, der in der aktiven gcloud CLI-Konfiguration festgelegt ist.

Zugriffstokens für Nutzerkonten haben eine Standardgültigkeitsdauer von einer Stunde.

Sie können ein Zugriffstoken mit der gcloud CLI für zukünftige Befehle oder nur für einen einzelnen Befehl verwenden.

Alle Befehle

Wenn Sie ein Zugriffstoken mit der gcloud CLI für zukünftige Befehle verwenden möchten, können Sie eine Umgebungsvariable oder ein Attribut in der aktiven gcloud CLI-Konfiguration festlegen:

  • Umgebungsvariable: Legen Sie die Umgebungsvariable CLOUDSDK_AUTH_ACCESS_TOKEN auf den Zugriffstokenstring fest.

    Wenn Sie das Zugriffstoken nicht mehr verwenden möchten, entfernen Sie die Umgebungsvariable CLOUDSDK_AUTH_ACCESS_TOKEN.

  • gcloud CLI-Konfiguration: Speichern Sie das Zugriffstoken in einer Datei und legen Sie dann mit dem folgenden Befehl den Pfad der Datei für das Attribut auth/access_token_file der aktiven gcloud CLI-Konfiguration fest:

    gcloud config set auth/access_token_file ACCESS_TOKEN_PATH

    Ersetzen Sie ACCESS_TOKEN_PATH durch den Pfad zur Datei mit dem Zugriffstoken.

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

    gcloud config unset auth/access_token_file

Einzelner Befehl

Wenn Sie ein Zugriffstoken mit der gcloud CLI für einen einzelnen Befehl verwenden möchten, können Sie das Flag --access-token-file einem gcloud CLI-Dienstbefehl hinzufügen:

  1. Speichern Sie das Zugriffstoken in einer Datei.

  2. Verwenden Sie das Flag --access-token-file mit einem beliebigen gcloud-Dienstbefehl.

    Wenn Sie beispielsweise Compute Engine-VM-Instanzen mit einem Zugriffstoken auflisten möchten, führen Sie den folgenden Befehl aus:

    Linux und macOS 

    gcloud compute instances list \
    --access-token-file ACCESS_TOKEN_PATH

    Windows (PowerShell) 

    gcloud compute instances list `
    --access-token-file ACCESS_TOKEN_PATH

    Ersetzen Sie ACCESS_TOKEN_PATH durch den Pfad zur Zugriffstoken-Datei.

Priorität der Anmeldedaten

Da in einer Umgebung möglicherweise mehrere Authentifizierungsmethoden verwendet werden, wertet die gcloud CLI die Methoden in einer bestimmten Reihenfolge aus, um zu ermitteln, welcher Prinzipal verwendet werden soll. Die gcloud CLI beginnt mit den bereitgestellten Anmeldedaten und prüft dann, ob die Identitätsübernahme des Dienstkontos angefordert wurde.

Die Reihenfolge der Auswertung der angegebenen Anmeldedaten ist wie folgt:

  1. Die Umgebungsvariable CLOUDSDK_AUTH_ACCESS_TOKEN, die auf den Zugriffstokenstring festgelegt ist.

  2. Zugriffstokendateien: Die Methoden zum Definieren der Zugriffstokendateipfade werden in der folgenden Reihenfolge ausgewertet:

    1. Das Befehlszeilenflag --access-token-file, das mit einem beliebigen gcloud CLI-Befehl verwendet wird.

    2. Die Umgebungsvariable CLOUDSDK_AUTH_ACCESS_TOKEN_FILE.

    3. Das Attribut auth/access_token_file in der aktiven gcloud CLI-Konfiguration.

  3. Dateien mit Anmeldedaten Die Methoden zum Definieren der Anmeldedateipfade werden in der folgenden Reihenfolge ausgewertet:

    1. Die Umgebungsvariable CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    2. Das Attribut auth/credential_file_override in der aktiven gcloud CLI-Konfiguration.

  4. Das aktive Prinzipal, das mit dem Befehl gcloud auth login oder durch Festlegen des Attributs core/account festgelegt wird.

Priorität der Identitätsübernahme des Dienstkontos

Wenn die Identitätsübernahme des Dienstkontos angefordert wurde, prüft die gcloud CLI, welches Dienstkonto übernommen werden soll, nachdem Anmeldedaten für das Hauptkonto bereitgestellt wurden, das die Identitätsübernahme durchführt. Die Methoden, mit denen Dienstkonten für die Identitätsübernahme definiert werden, werden in der folgenden Reihenfolge ausgewertet:

  1. Das Befehlszeilen-Flag --impersonate-service-account.

  2. Die Umgebungsvariable CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

  3. Das Dienstkonto, das durch das Attribut auth/impersonate_service_account in der aktiven Konfiguration definiert wird.

Google Drive in den Umfang aufnehmen

Der gcloud CLI-Bereich kann zusätzlich zu Google Cloudauf Google Drive-Zugriff erweitert werden. Das bedeutet, dass Sie Google Cloud -Zugriffstokens mit Google Drive verwenden können.

Wenn Sie den Bereich auf Google Drive ausweiten möchten, fügen Sie beim Autorisieren der gcloud CLI das Flag --enable-gdrive-access hinzu:

Linux und macOS 

gcloud auth login \
    --enable-gdrive-access

Windows (PowerShell) 

gcloud auth login `
    --enable-gdrive-access

Anschließend können Sie mit der gcloud CLI Aufrufe an Google Drive APIs senden, um ein Zugriffstoken bereitzustellen. Wenn Sie beispielsweise alle Dateien in Ihrem Google Drive auflisten möchten, können Sie die folgende Anfrage stellen:

Linux und macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

Sie können dann beispielsweise eine Datei-ID aus der Antwort des vorherigen Befehls verwenden, um Text aus einer Google Docs-Datei zu extrahieren:

Linux und macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Ein häufiger Anwendungsfall für den Google Drive-Zugriff ist die Verwendung von BigQuery mit in Google Sheets gespeicherten Daten.

Weitere Informationen zur Google Drive API finden Sie in der Übersicht zur Google Drive API.

gcloud CLI als Credential Helper zu Docker hinzufügen

Wenn Sie Containerregistries aus Artifact Registry abrufen möchten, können Sie die gcloud CLI als Credential Helper zu Ihrer Docker-Konfiguration hinzufügen.

Führen Sie dazu den Befehl gcloud auth configure-docker aus:

gcloud auth configure-docker REGION-docker.pkg.dev

Principals und Anmeldedaten verwalten

Mit dem Befehl gcloud auth login können Sie mehrere Principals in derselben Umgebung authentifizieren und die gcloud CLI autorisieren, in ihrem Namen auf Ressourcen zuzugreifen. Es kann jedoch jeweils nur ein Principal aktiv sein. In den folgenden Abschnitten wird beschrieben, wie Sie die Principals in Ihrer gcloud CLI-Konfiguration verwalten, einschließlich des Auflistens, des Wechsels zwischen ihnen und des Widerrufs ihrer Anmeldedaten.

Hauptkonten auflisten

Mit dem Befehl gcloud auth list können Sie die Principals auflisten, deren Anmeldedaten im lokalen System gespeichert sind (d. h. die mit gcloud auth login authentifiziert wurden):

gcloud auth list

Die gcloud CLI listet die Identitäten auf und zeigt an, welche Identität aktiv ist:

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

Überschreibungen für den aktiven Prinzipal sind nicht in dieser Liste enthalten. Dazu gehören die folgenden Umgebungsvariablen:

  • CLOUDSDK_AUTH_ACCESS_TOKEN
  • CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
  • CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

Führen Sie den folgenden Befehl für Ihr Betriebssystem aus, um zu prüfen, ob diese Umgebungsvariablen festgelegt sind:

Linux und macOS 

echo "$ENVIRONMENT_VARIABLE"

Windows (PowerShell) 

echo $env:ENVIRONMENT_VARIABLE

Ersetzen Sie ENVIRONMENT_VARIABLE durch die Umgebungsvariable, die Sie prüfen möchten.

Überschreibungen für den aktiven Prinzipal umfassen auch die folgenden Konfigurationseigenschaften:

  • auth/access_token_file
  • auth/credential_file_override
  • auth/impersonate_service_account

Führen Sie den folgenden Befehl aus, um zu prüfen, ob diese Konfigurationseigenschaften festgelegt sind:

gcloud config list

Aktive Principals wechseln

Wenn Sie zu einem aktiven Prinzipal mit gespeicherten Anmeldedaten wechseln möchten (d. h. der gcloud auth login-Ablauf wurde bereits abgeschlossen), führen Sie gcloud config set aus:

gcloud config set account PRINCIPAL_IDENTIFIER

Ersetzen Sie PRINCIPAL_IDENTIFIER durch die vollständige Kennung des Hauptkontos.

Sie können auch auf folgende Weise zwischen Hauptkonten wechseln:

Länge der Nutzersitzung einstellen

Administratoren können steuern, wie lange verschiedene Nutzer auf die gcloud CLI zugreifen können, ohne sich neu authentifizieren zu müssen. Sie können beispielsweise Nutzer mit erweiterten Berechtigungen dazu zwingen, sich häufiger als reguläre Nutzer neu zu authentifizieren.

Weitere Informationen finden Sie unter Sitzungsdauer für Google Cloud -Dienste festlegen.

Anmeldedaten für ein Hauptkonto widerrufen

Sie können Anmeldedaten für Identitäten widerrufen, die sich mit gcloud auth login authentifiziert haben, damit die gcloud CLI nicht in ihrem Namen agieren kann. Durch den Widerruf werden die Anmeldedaten auf den Autorisierungsservern von Google ungültig und das Prinzipal wird aus der aktiven gcloud CLI-Konfiguration entfernt.

Führen Sie zum Widerrufen von Anmeldedaten den Befehl gcloud auth revoke aus:

gcloud auth revoke PRINCIPAL_IDENTIFIER

Ersetzen Sie PRINCIPAL_IDENTIFIER durch die vollständige Kennung des Hauptkontos.

Wenn Sie den Zugriff für die gcloud CLI auf allen Geräten widerrufen möchten, die mit Ihrem Google-Konto verknüpft sind, rufen Sie in den Einstellungen Ihres Google-Kontos Drittanbieter-Apps und ‑Dienste auf und löschen Sie alle Verbindungen zum Google Cloud SDK.

Gespeicherte Anmeldedaten verwalten

Die gcloud CLI speichert die verwendeten Dateien mit Anmeldedaten im Konfigurationsverzeichnis der gcloud CLI. Mit gcloud info können Sie den Speicherort der Dateien mit Anmeldedaten aufrufen:

gcloud info

Die gcloud CLI gibt Informationen zu Ihrer Installation aus. Dateien mit Anmeldedaten werden im User Config Directory (Nutzerkonfigurationsverzeichnis) gespeichert, das in der Ausgabe definiert ist:

User Config Directory: [/home/USERNAME/.config/gcloud]

Unter Linux und macOS ist das Konfigurationsverzeichnis der gcloud CLI normalerweise /home/USERNAME/.config/gcloud. Unter Windows ist es %APPDATA%\gcloud.

Nächste Schritte