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.

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:

  2. Sie müssen Ihre Pool-ID oder Anbieter-ID kennen.

  3. 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).

  4. IAM and Security Token Service APIs aktivieren.

    Aktivieren Sie die APIs

  5. Installieren Sie die Google Cloud CLI und initialisieren Sie sie mit folgendem Befehl: 

    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-Kommandozeile, 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. Sie können die Datei optional mit dem Flag --activate als Standard für die gcloud CLI aktivieren. 

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

Ersetzen Sie Folgendes:

  • WORKFORCE_POOL_ID: die ID des Workforce-Pools
  • PROVIDER_ID: die Anbieter-ID
  • LOGIN_CONFIG_FILE: ein Pfad zur von Ihnen angegebenen Konfigurationsdatei, 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 Anbieter festzulegen, den Sie zuvor in dieser Anleitung erstellt haben. 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/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 beim Erstellen der Konfigurationsdatei das Flag --activate verwendet oder die Konfigurationsdatei mit gcloud config set auth/LOGIN_CONFIG_FILE aktiviert haben, verwendet die gcloud CLI Ihre Konfigurationsdatei automatisch: 

    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. Für die Einrichtung der Konfigurationsdateien müssen Sie nicht in der gcloud CLI angemeldet sein.

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

OIDC

Sie können die Anmeldedaten, die Sie zum Einrichten der Konfigurationsdatei verwenden, aus den folgenden Quellen abrufen:

Dateibasierte Anmeldedaten

Tokens werden 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 vor 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/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-Pools
  • PROVIDER_ID: die Anbieter-ID
  • 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/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

Tokens werden 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 die Konfigurationsdatei mit URL-basierten Anmeldedaten zu generieren:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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 Workforce-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • 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/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

Tokens werden 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 füllen die folgenden Umgebungsvariablen aus, wenn die ausführbare Datei ausgeführt wird:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: Das Feld für die Zielgruppe aus der Konfiguration der Anmeldedaten. Immer vorhanden.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Der erwartete Tokentyp des Subjekts. Immer vorhanden.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Der Speicherort der Ausgabedatei aus der Konfiguration von Anmeldedaten. Nur vorhanden, wenn in der Konfiguration der Anmeldedaten angegeben.

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/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 Workforce-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • EXECUTABLE_COMMAND: der vollständige Befehl, einschließlich Argumenten, um das Subjekt-Token, z. B. ein OIDC-ID-Token, im folgenden Format abzurufen: --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 Dateipfad 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/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

Sie können eine ausführbare Datei bereitstellen, die mit dem Nutzer über stdin und stdout 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 zurück, unabhängig davon, ob oben interaktive oder nicht interaktive ausführbare Anmeldedaten erhalten werden.

Die Umgebungsvariablen sind mit den normalen ausführbaren 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/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 Workforce-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • 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 Dateipfad 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 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/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",
    }
  }
}

SAML

Sie können die Anmeldedaten, die Sie zum Einrichten der Konfigurationsdatei verwenden, aus den folgenden Quellen abrufen:

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/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 Workforce-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • 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

Assertionen werden von einem lokalen Server mit einem Endpunkt geladen, der auf HTTP-GET-Anfragen antwortet. Die Antwort muss entweder eine base64-codierte SAML-Assertion oder eine JSON-Datei sein, die eine base64-codierte SAML-Assertion enthält.

Um URL-basierte Anmeldedaten zu verwenden, nutzen Sie das Flag --credential-source-url:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • 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 serviceusage.services.use permission 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 füllen die folgenden Umgebungsvariablen aus, wenn die ausführbare Datei ausgeführt wird:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: Das Feld für die Zielgruppe aus der Konfiguration der Anmeldedaten. Immer vorhanden.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Der erwartete Tokentyp des Subjekts. Immer vorhanden.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Der Speicherort der Ausgabedatei aus der Konfiguration von Anmeldedaten. Nur vorhanden, wenn in der Konfiguration der Anmeldedaten angegeben.

Setzen Sie die Umgebungsvariable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES auf 1, um diese Methode der Anmeldedatenbereitstellung für die Clientbibliotheken zu aktivieren.

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/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 Workforce-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • EXECUTABLE_COMMAND: der vollständige Befehl, einschließlich Argumenten, um das Subjekt-Token im folgenden Format abzurufen: --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 Dateipfad zu den 3PI-Anmeldedaten, die von der ausführbaren Datei generiert werden. Dies ist nützlich, um die Anmeldedaten im Cache zu speichern. Die Auth-Bibliotheken prüfen, ob sie vorhanden sind, bevor die ausführbare Datei ausgeführt wird.
  • 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 der folgenden ähnelt:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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

Eine ausführbare Datei interagiert mit dem Nutzer über die Befehlszeile.

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 fehlt, wird dies als Signal behandelt, dass wir die ausführbare Datei in irgendeiner Weise ausführen.

Die ausführbare Datei muss alle Fehler in executable-output-file 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.

Die Befehlsrückgabefelder für eine erfolgreiche Ausführung sind genau die gleichen Ergebnisse für die oben beschriebenen normalen ausführbaren Anmeldedatenergebnisse.

Die Umgebungsvariablen sind mit den normalen 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/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 Workforce-Pools.
  • PROVIDER_ID: die Anbieter-ID
  • 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 Dateipfad 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 festlegen.

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>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 die Befehlszeilen (gcloud, bq, gsutil) derzeit keine auf ausführbaren Dateien basierenden Anmeldedatentypen unterstützen.

Für monitorlose Abläufe verwendet gcloud automatisch den folgenden Bereich: https://www.googleapis.com/auth/cloud-platform. gcloud 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

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 Dateipfad zur Konfigurationsdatei für Anmeldedaten.

Unterstützung für Workforce Identity-Föderation in bq ist in Version 390.0.0 und späteren Versionen der Google Cloud CLI verfügbar.

C++

Die meisten Google Cloud-Clientbibliotheken für C++ unterstützen 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-Clientbibliothek für C++ verwendet die REST API und nicht gRPC. Daher unterstützt 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

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

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

Go

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)
}

gsutil

Verwenden Sie eine der folgenden Methoden, um sich mit einer Workforce Identity-Föderation zu authentifizieren:

Wenn Sie gsutil zusammen mit gcloud verwenden, melden Sie sich wie gewohnt an:

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

Wenn Sie gsutil als eigenständige Befehlszeilenanwendung verwenden, bearbeiten Sie die .boto-Datei so, dass sie den folgenden Abschnitt enthält:

[Credentials]
gs_external_account_file = FILEPATH

FILEPATH ist in beiden Fällen der Dateipfad zur Konfigurationsdatei für Anmeldedaten.

Unterstützung für Workforce Identity-Föderation in gsutil ist in Version 379.0.0 und späteren Versionen der Google Cloud CLI verfügbar.

Java

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

Clientbibliotheken für Node.js unterstützen die Identitätsföderation von Mitarbeitern. Sie müssen die Version 7.10.0 oder höher des Pakets google-auth-library verwenden. Im Gegensatz zu Workload Identity-Pools sind Personalpools 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

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 obigen Beispiel kann der Wert project None sein, wenn die Bibliothek dies nicht automatisch erkennen kann. Sie können es explizit übergeben, wenn Sie eine Dienstinstanz verwenden (wie im Beispiel des Speicherclients) oder ü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.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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.
  • PROVIDER_ID: die Anbieter-ID

  • 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. Hinweis: Wenn Sie OIDC verwenden, ist das Token JWT-formatiert.

  • BILLING_PROJECT_NUMBER: 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.

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 gcloud vom Security Token Service-Endpunkt erhält, laufen nach einem bestimmten Zeitintervall ab. Wenn das Token abläuft, prüft gcloud 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 gcloud 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