Kurzlebige Tokens für die Workforce Identity-Föderation abrufen

In diesem Leitfaden erfahren Sie, wie Sie einen Workforce Identity-Pool und einen Workforce Identity-Poolanbieter verwenden, um kurzlebige Token vom Security Token Service zu erhalten. Sie können die Token verwenden, um auf Google Cloud-Ressourcen zuzugreifen, die Workforce Identity-Föderation unterstützen und auf die Sie Zugriff erhalten haben.

Die in diesem Leitfaden beschriebenen Methoden können auf headless-Maschinen verwendet werden.

So erhalten Sie kurzlebige Tokens:

  1. Rufen Sie Anmeldedaten vom vertrauenswürdigen Identitätsanbieter ab.
  2. Tauschen Sie die Anmeldedaten gegen ein Token des Security Token Service aus.

Hinweise

  1. Konfigurieren der Workforce Identity-Föderation oder lesen Sie für IdP-spezifische Anweisungen die folgenden Anleitungen:

    Notieren Sie sich die ID Ihres Mitarbeiteridentitätspools und die ID des Anbieters des Mitarbeiteridentitätspools.

  2. Prüfen Sie, ob Sie die IAM-Berechtigung (Identity and Access Management) serviceusage.services.use haben. Die Rolle mit den geringsten Berechtigungen, die diese Berechtigung enthält, ist Service Usage-Nutzer (roles/serviceusage.serviceUsageConsumer).

  3. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  4. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

Externe Anmeldedaten gegen ein Google Cloud-Zugriffstoken austauschen

In diesem Abschnitt erfahren Sie, wie Sie mit dem Security Token Service Ihre externen Anmeldedaten gegen ein Zugriffstoken austauschen, das Zugriff auf Google Cloud gewährt. Verwenden Sie dazu die gcloud CLI, die REST API und die Cloud-Clientbibliotheken, wie später in dieser Anleitung beschrieben.

Wenn Sie einen langlebigen Zugriff benötigen, können Sie einen lang andauernden Prozess konfigurieren, um Anmeldedaten auf diesem Computer kontinuierlich zu aktualisieren. Alternativ können Sie einen lokalen Server im Hintergrund mit einem Endpunkt ausführen, der die Anmeldedaten zurückgibt.

Browserbasierte Anmeldung mit der gcloud CLI

In diesem Abschnitt wird beschrieben, wie Sie die gcloud CLI für die Verwendung eines browserbasierten Anmeldeablaufs konfigurieren. Dazu erstellen Sie eine Konfigurationsdatei für die Anmeldung und verweisen dann entweder in Aufrufen an gcloud auth login auf die Datei oder aktivieren sie für eine standardmäßige Verwendung.

Konfigurationsdatei für die Anmeldung erstellen

Mit dem folgenden Befehl erstellen Sie die Konfigurationsdatei für die Anmeldung. Optional können Sie die Datei mit dem Flag --activate als Standarddatei für die gcloud CLI aktivieren. 

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

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Workforce Identity-Pools
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools
  • LOGIN_CONFIG_FILE: ein Pfad zur von Ihnen angegebenen Anmeldekonfigurationsdatei, z. B. login.json

Die Datei enthält die Endpunkte, die von der gcloud CLI verwendet werden, um den browserbasierten Authentifizierungsvorgang zu aktivieren und die Zielgruppe auf den Identitätsanbieter festzulegen, der im Anbieter des Mitarbeiteridentitätspools konfiguriert wurde. Die Datei enthält keine vertraulichen Daten.

Die Ausgabe sieht dann ungefähr so aus:

{
  "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",
}

Mit der browserbasierten Authentifizierung anmelden

Sie haben folgende Möglichkeiten, sich mit einer browserbasierten Anmeldung zu authentifizieren:

  • Wenn Sie das Flag --activate beim Erstellen der Konfigurationsdatei verwendet oder die Konfigurationsdatei mit gcloud config set auth/login_config_file aktiviert haben, wird sie automatisch von der gcloud CLI verwendet: 

    gcloud auth login

  • Mit dem folgenden Befehl melden Sie sich durch Angabe des Speicherorts der Konfigurationsdatei an: 

    gcloud auth login --login-config=LOGIN_CONFIG_FILE
  • Wenn Sie den Speicherort der Konfigurationsdatei mit einer Umgebungsvariable angeben möchten, legen Sie für CLOUDSDK_AUTH_LOGIN_CONFIG_FILE den Konfigurationspfad fest.

Browserbasierte Anmeldung deaktivieren

So beenden Sie die Verwendung der Konfigurationsdatei für die Anwendung:

  • Wenn Sie das Flag --activate beim Erstellen der Konfigurationsdatei verwendet oder die Konfigurationsdatei mit gcloud config set auth/login_config_file aktiviert haben, müssen Sie den folgenden Befehl ausführen, um die Festlegung aufzuheben: 

    gcloud config unset auth/login_config_file
  • Löschen Sie die Umgebungsvariable CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, falls sie festgelegt ist.

Konfigurationsdateien für die Anmeldung verwenden

Als Alternative zur browserbasierten Anmeldung finden Sie in diesem Abschnitt verschiedene Möglichkeiten, wie Sie Konfigurationsdateien für Anmeldedaten verwenden können, um Zugriff auf authentifizierte Google Cloud-Aktionen zu gewähren. Sie müssen nicht in der gcloud CLI angemeldet sein, um die Konfigurationsdateien einzurichten.

Wie Sie Ihre Konfigurationsdatei einrichten, hängt davon ab, ob Ihr IdP OIDC oder SAML verwendet.

OIDC

Sie können die Anmeldedaten, mit denen Sie Ihre Konfigurationsdatei einrichten, aus den folgenden Quellen beziehen:

Dateibasierte Anmeldedaten

Bei der Verwendung von dateibasierten Anmeldedaten werden Tokens aus einer Datei geladen. Ein anderer Prozess muss diese Datei mit einem neuen OIDC-Token aktualisieren, bevor das alte Token abläuft. Wenn das Token beispielsweise eine Lebensdauer von einer Stunde hat, müssen Sie die Datei innerhalb einer Stunde aktualisieren.

Führen Sie den folgenden Befehl aus, um die Konfigurationsdatei mit dateibasierten Anmeldedaten zu generieren:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Workforce Identity-Pools
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools
  • PATH_TO_OIDC_TOKEN: der Pfad zur OIDC-IdP-Anmeldedatendatei
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer oder ID, die dem Nutzerprojekt für Workforce-Pools zugeordnet sind.

Das Hauptkonto muss die Berechtigung serviceusage.services.use für dieses Projekt haben.

Durch Ausführen des Befehls wird eine OIDC-IdP-Konfigurationsdatei erstellt, die in etwa so aussieht:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

URL-basierte Anmeldedaten

Bei der Verwendung von URL-basierten Anmeldedaten werden Tokens von einem lokalen Server mit einem Endpunkt geladen, der auf HTTP GET-Anfragen antwortet. Die Antwort muss ein OIDC-ID-Token sein, entweder im Nur-Text- oder JSON-Format.

Führen Sie den folgenden Befehl aus, um eine Konfigurationsdatei mit URL-basierten Anmeldedaten zu generieren:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Mitarbeiteridentitätspools.
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools.
  • URL_TO_RETURN_OIDC_ID_TOKEN: die URL, die zum Abrufen der OIDC-Anmeldedaten aufgerufen werden soll, z. B. ein OIDC-ID-Token wie http://localhost:5000/token.
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer, die für Kontingente und die Abrechnung verwendet wird. Das Hauptkonto muss serviceusage.services.use permission für dieses Projekt haben.

Durch Ausführen des Befehls wird eine OIDC-IdP-Konfigurationsdatei erstellt, die in etwa so aussieht:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Nicht interaktive ausführbare Datei-basierte Anmeldedaten

Wenn Sie nicht interaktive ausführbare Datei-basierte Anmeldedaten verwenden, werden Tokens aus einer lokalen ausführbaren Datei geladen. Die ausführbare Datei muss ein gültiges, nicht abgelaufenes OIDC-ID-Token im JSON-Format für stdout bereitstellen:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Diese Felder sind mit Ausnahme von expiration_time für eine erfolgreiche Antwort erforderlich. Das Feld expiration_time ist nur erforderlich, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben wurde.

Die ausführbare Datei muss alle Fehler in stdout im folgenden JSON-Format anzeigen:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Alle diese Felder sind für eine Fehlerantwort erforderlich. Die Felder „code“ und „message“ werden von den Clientbibliotheken verwendet, wenn der entsprechende Fehler ausgegeben wird.

Der Befehl kann die folgenden Felder zurückgeben:

  • version: Die Version der JSON-Ausgabe. Nur Version 1 wird unterstützt.

  • success: Der Status der Antwort. Wenn der Status true lautet, muss die ausführbare Datei mit dem Exit-Code 0 beendet werden und die Antwort muss die folgenden Felder enthalten:

    • token_type: id_token
    • Feld expiration_time, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben ist

    Wenn der Status false lautet, muss die ausführbare Datei mit einem Wert ungleich null beendet werden und die Antwort muss die folgenden Felder enthalten:

    • code
    • message

  • token_type: der Drittanbieter-Tokentyp des Subjekts, der urn:ietf:params:oauth:token-type:id_token lauten muss

  • id_token: das OIDC-Token des Drittanbieters

  • expiration_time: die Ablaufzeit des OIDC-Tokens des Drittanbieters in Sekunden (Unixzeit)

  • code: der Fehlercodestring

  • message: die Fehlermeldung

Die Clientbibliotheken legen die folgenden Umgebungsvariablen fest, wenn die ausführbare Datei ausgeführt wird:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: Das Feld für die Zielgruppe aus der Konfiguration der Anmeldedaten. Diese Variable ist immer festgelegt.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Der erwartete Tokentyp des Subjekts. Diese Variable ist immer festgelegt.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Der Speicherort der Ausgabedatei aus der Konfiguration von Anmeldedaten. Diese Variable ist nur vorhanden, wenn sie in der Konfiguration der Anmeldedaten angegeben ist.

Diese Umgebungsvariablen können von der ausführbaren Datei verwendet werden, um eine Hartcodierung dieser Werte zu vermeiden.

Um diese Methode der Anmeldedatenbereitstellung für die Clientbibliotheken zu aktivieren, muss die Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES auf 1 festgelegt sein.

Führen Sie den folgenden Befehl aus, um die Konfigurationsdatei mit ausführbaren Anmeldedaten zu generieren:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Mitarbeiteridentitätspools.
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools.
  • EXECUTABLE_COMMAND: der vollständige Befehl, einschließlich Argumenten, um das Subjekt-Token abzurufen, z. B. ein OIDC-ID-Token, im folgenden Format: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: Optional. Die Dauer in Millisekunden, die gewartet wird, bis die ausführbare Datei ausgeführt wird (standardmäßig 30 Sekunden).
  • EXECUTABLE_OUTPUT_FILE: Optional. Ein Pfad zu den Anmeldedaten des Drittanbieters, die von der ausführbaren Datei generiert werden. Dies ist nützlich, um die Anmeldedaten im Cache zu speichern. Die Auth-Bibliotheken prüfen zuerst diesen Pfad, bevor die ausführbare Datei ausgeführt wird.
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer oder ID, die für das Kontingent und die Abrechnung verwendet wird. Das Hauptkonto muss die Berechtigung serviceusage.services.use für dieses Projekt haben.

Durch Ausführen des Befehls wird eine OIDC-IdP-Konfigurationsdatei erstellt, die in etwa so aussieht:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Interaktive ausführbare Datei-basierte Anmeldedaten

Wenn Sie interaktive ausführbare Anmeldedaten verwenden, können Sie eine ausführbare Datei bereitstellen, die über stdin und stdout mit dem Nutzer interagiert. Wenn sich der Nutzer erfolgreich anmeldet, schreibt die ausführbare Datei gültige, nicht abgelaufene Anmeldedaten in die angegebene Datei.

Für diesen Modus sind die folgenden Flags erforderlich:

  • --executable-output-file: die Datei, in die die ausführbare Datei die Anmeldedaten schreibt
  • --exeutable-interactive-timeout-millis: ein Wert ungleich null, der den interaktiven Modus angibt und das Zeitlimit festlegt, z. B. 6000 für ein Zeitlimit von 60 Sekunden

Die folgenden Felder sind mit Ausnahme von expiration_time für eine erfolgreiche Antwort erforderlich:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Die ausführbare Datei muss alle Fehler in die in --executable-output-file angegebene Datei im folgenden JSON-Format schreiben. Die folgenden Felder sind alle erforderlich, wenn eine Fehlerantwort zurückgegeben wird.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Die Felder code und message müssen den entsprechenden Fehler angeben. Diese Felder werden von den Clientbibliotheken verwendet, wenn der Fehler ausgegeben wird.

Bei erfolgreicher Ausführung gibt der Befehl dieselben Felder für interaktive und nicht interaktive ausführbare Anmeldedaten zurück.

Die Umgebungsvariablen sind für interaktive und nicht interaktive ausführbare Datei-basierte Anmeldedaten identisch.

Fügen Sie den Parameter --executable-interactive-timeout-millis und den Parameter --executable-output-file hinzu, um interaktive ausführbare Anmeldedaten zu generieren.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Mitarbeiteridentitätspools.
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools.
  • EXECUTABLE_COMMAND: der vollständige Befehl, einschließlich Argumenten, um das Subjekt-Token abzurufen, so formatiert: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT: eine Dauer in Millisekunden, die gewartet wird, bis die ausführbare Datei ausgeführt wird.
  • EXECUTABLE_OUTPUT_FILE: ein Pfad zu den Anmeldedaten des Drittanbieters, die von der ausführbaren Datei generiert werden. Dieser Pfad ist nützlich, um die Anmeldedaten im Cache zu speichern. Die Authentifizierungsbibliotheken prüfen zuerst diesen Pfad, bevor die ausführbare Datei ausgeführt wird.
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer oder ID, die für das Kontingent und die Abrechnung verwendet wird. Das Hauptkonto muss die Berechtigung serviceusage.services.use für dieses Projekt haben.

Durch Ausführen des Befehls wird eine OIDC-IdP-Konfigurationsdatei erstellt, die in etwa so aussieht:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

Das Feld timeout_millis wird zurückgegeben, da eine interaktive ausführbare Datei in einigen Fällen auch im nicht interaktiven Modus ausgeführt werden kann. Im interaktiven Modus gibt der Befehl eine Standardzeitüberschreitung zurück.

SAML

Sie können die Anmeldedaten, mit denen Sie Ihre Konfigurationsdatei einrichten, aus den folgenden Quellen beziehen:

Dateibasierte Anmeldedaten

Assertionen werden aus einer Datei geladen. Vor dem Ablauf der alten Assertion muss diese Datei von einem anderen Prozess mit einer neuen base64-codierten SAML-Assertion aktualisiert werden. Wenn die Assertion beispielsweise eine Lebensdauer von einer Stunde hat, müssen Sie die Datei innerhalb einer Stunde aktualisieren.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Mitarbeiteridentitätspools.
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools.
  • CREDENTIAL_FILE: der Pfad zur Datei mit den Anmeldedaten, die vom IdP generiert wird.
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer oder ID, die für das Kontingent und die Abrechnung verwendet wird. Das Hauptkonto muss in diesem Projekt serviceusage.services.use permission haben.

URL-basierte Anmeldedaten

Assertions werden von einem lokalen Server mit einem Endpunkt geladen, der auf HTTP-GET-Anfragen antwortet. Die Antwort muss entweder eine [base64-codierte](https://toolbox.googleapps.com/apps/encode_decode/) SAML-Assertion oder eine JSON-Datei sein, die eine base64-codierte SAML-Assertion enthält. Um URL-basierte Anmeldedaten zu verwenden, verwenden Sie das Flag `--credential-source-url`: ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --output-file=federation_config.json \ --credential-source-url=CREDENTIAL_URL \ --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \ --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT ``` Ersetzen Sie Folgendes: * WORKFORCE_POOL_ID: die ID des Workforce Identity-Pools. * WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools. * CREDENTIAL_URL: die URL des lokalen Server-Endpunkts. * WORKFORCE_POOL_USER_PROJECT: die Projektnummer oder ID, die für das Kontingent und die Abrechnung verwendet wird. Das Hauptkonto muss die Berechtigung „serviceusage.services.use“ für dieses Projekt haben.

Ausführbare Datei-basierte Anmeldedaten

Assertions werden aus einer lokalen ausführbaren Datei geladen. Die ausführbare Datei muss eine gültige, nicht abgelaufene SAML-Assertion im JSON-Format für stdout bereitstellen.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Diese Felder sind mit Ausnahme von expiration_time für eine erfolgreiche Antwort erforderlich. Das Feld expiration_time ist nur erforderlich, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben ist.

Wenn ein Fehler auftritt, muss dieser von der ausführbaren Datei im folgenden JSON-Format für stdout angezeigt werden:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Alle diese Felder sind für eine Fehlerantwort erforderlich. Die Felder „code“ und „message“ werden von den Clientbibliotheken verwendet, wenn der entsprechende Fehler ausgegeben wird.

Der Befehl kann die folgenden Felder zurückgeben:

  • version: Die Version der JSON-Ausgabe. Nur Version 1 wird unterstützt.

  • success: Der Status der Antwort. Wenn der Status true lautet, muss die ausführbare Datei mit dem Exit-Code 0 beendet werden und die Antwort muss die folgenden Felder enthalten:

    • token_type: saml_response
    • Feld expiration_time, wenn in der Konfiguration der Anmeldedaten eine Ausgabedatei angegeben ist

    Wenn der Status false lautet, muss die ausführbare Datei mit einem Wert ungleich null beendet werden und die Antwort muss die folgenden Felder enthalten: + code + message

  • token_type: der Drittanbieter-Tokentyp des Subjekts, der urn:ietf:params:oauth:token-type:saml2 lauten muss

  • saml_response: die SAML-Antwort des Drittanbieters

  • expiration_time: die Ablaufzeit der SAML-Antwort des Drittanbieters in Sekunden (Unixzeit)

  • code: der Fehlercodestring

  • message: die Fehlermeldung

Die Clientbibliotheken legen die folgenden Umgebungsvariablen fest, wenn die ausführbare Datei ausgeführt wird:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: Das Feld für die Zielgruppe aus der Konfiguration der Anmeldedaten. Diese Variable ist immer festgelegt.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Der erwartete Tokentyp des Subjekts. Diese Variable ist immer festgelegt.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Der Speicherort der Ausgabedatei aus der Konfiguration von Anmeldedaten. Diese Variable ist nur vorhanden, wenn sie in der Konfiguration der Anmeldedaten angegeben ist.

Um diese Methode der Anmeldedatenbereitstellung für die Clientbibliotheken zu aktivieren, legen Sie die Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES auf 1 fest.

Führen Sie den folgenden Befehl aus, um die Konfigurationsdatei mit ausführbaren Anmeldedaten zu generieren:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Mitarbeiteridentitätspools.
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools.
  • EXECUTABLE_COMMAND: der vollständige Befehl, einschließlich Argumenten, um das Subjekt-Token abzurufen, im folgenden Format: --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT: Optional. Die Dauer in Millisekunden, die gewartet wird, bis die ausführbare Datei ausgeführt wird (standardmäßig 30 Sekunden).
  • EXECUTABLE_OUTPUT_FILE: Optional. Der Pfad zu den Anmeldedaten der Drittanbieteridentität (3PI), die von der ausführbaren Datei generiert werden. Dies ist nützlich, um die Anmeldedaten im Cache zu speichern. Die Autorisierungsbibliotheken prüfen vor der Ausführung der ausführbaren Datei, ob sie vorhanden ist.
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer, die für Kontingente und die Abrechnung verwendet wird. Das Hauptkonto muss die Berechtigung serviceusage.services.use für dieses Projekt haben.

Durch Ausführen des Befehls wird eine SAML-IdP-Konfigurationsdatei erstellt, die etwa so aussieht:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Ausführbare Datei-basierte Anmeldedaten für den interaktiven Modus von gcloud

Wenn Sie ausführbare Datei-basierte Anmeldedaten für den interaktiven Modus von gcloud verwenden, interagiert eine ausführbare Datei über die Befehlszeile mit dem Nutzer.

Ersetzen Sie im vorherigen Befehl Folgendes:

  • EXECUTABLE_OUTPUT_FILE: erforderlich. Der Pfad zur Datei mit den von der ausführbaren Datei generierten Anmeldedaten.
  • EXECUTABLE_TIMEOUT: erforderlich. Ein Zeitlimitwert ungleich null gibt auch an, dass der Befehl den interaktiven Modus verwendet.
    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

Diese Felder sind mit Ausnahme von expiration_time für eine erfolgreiche Antwort erforderlich. Wenn expiration_time weggelassen wird, wird die ausführbare Datei trotzdem ausgeführt.

Die ausführbare Datei muss alle Fehler in executable-output-file im folgenden JSON-Format anzeigen. Wenn die ausführbare Datei einen Fehler meldet, sind diese Felder alle erforderlich. Die Felder „code“ und „message“ werden von den Clientbibliotheken verwendet, wenn der entsprechende Fehler ausgegeben wird.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Bei erfolgreicher Ausführung des Befehls werden dieselben Felder zurückgegeben wie bei nicht interaktiven ausführbaren Anmeldedaten.

Die Umgebungsvariablen sind mit den nicht interaktiven ausführbaren Anmeldedaten identisch.

Fügen Sie den Parameter --executable-interactive-timeout-millis hinzu, um interaktive, ausführbare Datei-basierte Anmeldedaten zu generieren.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Mitarbeiteridentitätspools.
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools.
  • EXECUTABLE_COMMAND: der vollständige Befehl, einschließlich Argumenten, um das Subjekt-Token abzurufen, so formatiert: --executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT: eine Dauer in Millisekunden, die gewartet wird, bis die ausführbare Datei ausgeführt wird.
  • EXECUTABLE_OUTPUT_FILE: ein Pfad zu den Anmeldedaten des Drittanbieters, die von der ausführbaren Datei generiert werden. Dies ist nützlich, um die Anmeldedaten im Cache zu speichern. Die Authentifizierungsbibliotheken prüfen zuerst diesen Pfad, bevor die ausführbare Datei ausgeführt wird.
  • WORKFORCE_POOL_USER_PROJECT: die Projektnummer oder ID, die für das Kontingent und die Abrechnung verwendet wird. Das Hauptkonto muss die Berechtigung serviceusage.services.use für dieses Projekt haben.

Durch Ausführen des Befehls wird eine SAML-IdP-Konfigurationsdatei erstellt, die etwa so aussieht:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>WORKFORCE_PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

Führen Sie zur Anmeldung den folgenden Befehl aus:

gcloud auth login --cred-file=/path/to/config.json

Beachten Sie, dass weder die gcloud CLI noch das bq-Befehlszeilentool Anmeldedatentypen unterstützen, die ausführbare Dateien als Quelle haben.

Für headless-Abläufe verwendet die gcloud CLI automatisch den folgenden Bereich: https://www.googleapis.com/auth/cloud-platform. Die gcloud CLI sendet Ihre Anmeldedaten dann transparent an den Endpunkt des Security Token Service, wo sie gegen temporäre Google Cloud-Zugriffstokens ausgetauscht werden.

Sie können jetzt gcloud-Befehle mithilfe der gcloud CLI ausführen.

Verwenden Sie die Google Cloud-Clientbibliotheken

Wenn Sie eine unterstützte Clientbibliothek verwenden, können Sie die Clientbibliothek so konfigurieren, dass Google-Anmeldedaten automatisch generiert werden. Wir empfehlen Ihnen, nach Möglichkeit Anmeldedaten automatisch zu generieren, damit Sie den Tokenaustauschprozess nicht selbst implementieren müssen.

Die Google Cloud-Clientbibliothek für Workforce-Pools wird in den folgenden Sprachen unterstützt: Node.js, Java, Python, Go und C++ (gRPC).

So verwenden Sie Clientbibliotheken mit diesen Diensten oder Sprachen:

bq-Tool

Verwenden Sie zum Authentifizieren der Workforce Identity-Föderation den Befehl gcloud auth login:

gcloud auth login --cred-file=FILEPATH.json

Dabei ist FILEPATH der Pfad zur Konfigurationsdatei für Anmeldedaten.

Unterstützung für die Workforce Identity-Föderation im bq-Tool ist in Version 390.0.0 und höher der Google Cloud CLI verfügbar.

C++

Die meisten Google Cloud-Clientbibliotheken für C++ unterstützen die Workforce Identity-Föderation mithilfe eines ChannelCredentials-Objekts, das durch Aufrufen von grpc::GoogleDefaultCredentials() erstellt wird. Zur Initialisierung dieser Anmeldedaten müssen Sie die Clientbibliotheken ab Version 1.42.0 von gRPC erstellen.

Die Cloud Storage-Clientbibliotheken für C++ verwenden die REST API und nicht gRPC. Daher unterstützen sie keine Workforce Identity-Föderation.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

Verwenden Sie zum Authentifizieren der Workforce Identity-Föderation den Befehl gcloud auth login:

gcloud auth login --cred-file=FILEPATH.json

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

Die Workforce Identity-Föderation in der gcloud CLI wird ab Version 392.0.0 der Google Cloud CLI unterstützt.

Go

Cloud-Clientbibliotheken für Go unterstützen die Workforce Identity-Föderation, wenn Sie Version 0.0.0-20211005180243-6b3c2da341f1 oder höher des Moduls golang.org/x/oauth2 verwenden.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

Java

Cloud-Clientbibliotheken für Java unterstützen die Workforce Identity-Föderation, wenn Sie Version 1.2.0 oder höher des com.google.auth:google-auth-library-oauth2-http-Artefakts verwenden.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Cloud-Clientbibliotheken für Node.js unterstützen die Workforce Identity-Föderation, wenn Sie Version 7.10.0 oder höher des google-auth-library-Pakets verwenden.

Im Gegensatz zu Workload Identity-Pools sind Mitarbeiteridentitätspools einer Organisation und nicht einem Google Cloud-Projekt zugeordnet. Wenn Sie ein GoogleAuth-Objekt erstellen, müssen Sie eine Projekt-ID angeben. Weitere Informationen finden Sie in der README-Datei für das Paket google-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

Cloud-Clientbibliotheken für Python unterstützen die Workforce Identity-Föderation, wenn Sie Version 2.3.0 oder höher des google-auth-Pakets verwenden.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

Im Beispielcode kann der Wert project None sein, wenn die Bibliothek die Projekt-ID nicht automatisch erkennen kann. Sie können die Projekt-ID explizit übergeben, wenn Sie eine Dienstinstanz verwenden (wie im Beispiel des Speicherclients), oder sie über die Umgebungsvariable GOOGLE_CLOUD_PROJECT festlegen.

Weitere Informationen finden Sie im Nutzerhandbuch für das Paket google-auth.

Verwenden der REST API

Sie können die Google Cloud Security Token Service API aufrufen, um Ihre externen Anmeldedaten gegen Google Cloud-Zugriffstokens auszutauschen. Führen Sie dazu den folgenden Befehl aus:

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

Ersetzen Sie Folgendes:

  • AUDIENCE: der vollständige Ressourcenname des Anbieters, der das Subjekt ausstellt.
  • WORKFORCE_POOL_ID: die ID des Workforce Identity-Pools
  • WORKFORCE_PROVIDER_ID: die ID des Anbieters des Mitarbeiteridentitätspools

  • SUBJECT_TOKEN_TYPE: Legen Sie dafür Folgendes fest:

    • urn:ietf:params:oauth:token-type:id_token für OIDC-ID-Tokens
    • urn:ietf:params:oauth:token-type:saml2 für SAML-Assertions

  • EXTERNAL_SUBJECT_TOKEN: Das vom IdP ausgestellte Token, das die Identität des Hauptkontos darstellt, für das das Zugriffstoken angefordert wird.

    Wenn Sie einen OIDC-Anbieter konfiguriert haben, muss das Token im JWT-Format vorliegen.

  • BILLING_PROJECT_NUMBER: die Projektnummer oder ID, die für Kontingente und die Abrechnung verwendet wird. Das Hauptkonto muss die Berechtigung serviceusage.services.use für dieses Projekt haben.

Die Antwort ähnelt dem folgenden Beispiel.

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Sitzungen mithilfe der gcloud CLI verwalten

Die temporären Google Cloud-Tokens, die die gcloud CLI vom Security Token Service-Endpunkt erhält, laufen nach einem bestimmten Zeitintervall ab. Wenn das Token abläuft, prüft die gcloud CLI die von Ihnen angegebene Datei mit den Anmeldedaten und prüft die Gültigkeit der Anmeldedaten, die Sie von Ihrem IdP erhalten haben. Wenn Ihre Anmeldedaten noch gültig sind, ruft die gcloud CLI weiterhin ein neues Google Cloud-Zugriffstoken ab und Ihre aktuelle Sitzung wird ohne Unterbrechung ausgeführt.

Wenn Ihre Anmeldedaten abgelaufen sind, werden keine neuen Google Cloud-Token ausgestellt und alle Aufrufe, die Sie mit diesen Anmeldedaten ausführen, schlagen fehl. An diesem Punkt müssen Sie sich noch einmal authentifizieren.

Sie können Ihre Sitzung mit dem folgenden Befehl beenden:

gcloud auth revoke

gcloud unterstützt mehrere Nutzersitzungen. Führen Sie den folgenden Befehl aus, um die Liste der Sitzungen abzurufen, einschließlich der derzeit aktiven Sitzung:

gcloud auth list

Die Ausgabe dieses Befehls sieht in etwa so aus:

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

Führen Sie den folgenden Befehl aus, um zu einer anderen Sitzung zu wechseln und sie als aktiv festzulegen:

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

Nächste Schritte