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:
- Rufen Sie Anmeldedaten vom vertrauenswürdigen Identitätsanbieter ab.
- Tauschen Sie die Anmeldedaten gegen ein Token des Security Token Service aus.
Hinweise
Konfigurieren der Workforce Identity-Föderation oder lesen Sie für IdP-spezifische Anweisungen die folgenden Anleitungen:
Sie müssen Ihre Pool-ID oder Anbieter-ID kennen.
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
).Enable the IAM and Security Token Service APIs.
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-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-PoolsPROVIDER_ID
: die Anbieter-IDLOGIN_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 mitgcloud 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 mitgcloud 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
- URL-basierte Anmeldedaten
- Nicht interaktive ausführbare Datei-basierte Anmeldedaten
- Interaktive ausführbare Datei-basierte Anmeldedaten
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-PoolsPROVIDER_ID
: die Anbieter-IDPATH_TO_OIDC_TOKEN
: der Pfad zur OIDC-IdP-AnmeldedatendateiWORKFORCE_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-IDURL_TO_RETURN_OIDC_ID_TOKEN
: die URL, die zum Abrufen der OIDC-Anmeldedaten aufgerufen werden soll, z. B. ein OIDC-ID-Token wiehttp://localhost:5000/token
.WORKFORCE_POOL_USER_PROJECT
: die Projektnummer, die für Kontingente und die Abrechnung verwendet wird. Das Hauptkonto mussserviceusage.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 Version1
wird unterstützt.success
: Der Status der Antwort. Wenn der Statustrue
lautet, muss die ausführbare Datei mit dem Exit-Code0
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, derurn:ietf:params:oauth:token-type:id_token
lauten mussid_token
: das OIDC-Token des Drittanbietersexpiration_time
: die Ablaufzeit des OIDC-Tokens des Drittanbieters in Sekunden (Unixzeit)code
: der Fehlercodestringmessage
: 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-IDEXECUTABLE_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 Berechtigungserviceusage.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 ü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 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-IDEXECUTABLE_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 Berechtigungserviceusage.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
- URL-basierte Anmeldedaten
- Ausführbare Datei-basierte Anmeldedaten
- Ausführbare Datei-basierte Anmeldedaten für den interaktiven Modus von gcloud
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-IDCREDENTIAL_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 Projektserviceusage.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-IDCREDENTIAL_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 mussserviceusage.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 Version1
wird unterstützt.success
: Der Status der Antwort. Wenn der Statustrue
lautet, muss die ausführbare Datei mit dem Exit-Code0
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, derurn:ietf:params:oauth:token-type:saml2
lauten musssaml_response
: die SAML-Antwort des Drittanbietersexpiration_time
: die Ablaufzeit der SAML-Antwort des Drittanbieters in Sekunden (Unixzeit)code
: der Fehlercodestringmessage
: 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-IDEXECUTABLE_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 Berechtigungserviceusage.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-IDEXECUTABLE_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 Berechtigungserviceusage.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-IDSUBJECT_TOKEN_TYPE
: Legen Sie dafür Folgendes fest:urn:ietf:params:oauth:token-type:id_token
für OIDC-ID-Tokensurn: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 Berechtigungserviceusage.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
- Nutzer von Workforce Identity-Föderation und deren Daten löschen
- Weitere Informationen dazu, welche Google Cloud-Produkte die Workforce Identity-Föderation unterstützen
- Nutzerzugriff auf die Console (föderiert) einrichten