本頁面由 Cloud Translation API 翻譯而成。

取得員工身分聯盟的短期權杖

本指南說明如何使用工作團隊身分集區和工作團隊身分集區提供者，從 Security Token Service 取得短期權杖。您可以使用這些權杖存取 Google Cloud 已獲授權的支援員工身分聯盟資源。

本指南所述方法可用於無螢幕裝置。

您可以按照下列高階程序取得短期權杖，詳情請參閱本文後續章節：

向可信任的識別資訊提供者取得憑證。
向 Security Token Service 換取憑證的權杖。

事前準備

設定員工身分聯盟，或參閱下列指南，瞭解 IdP 專屬的操作說明：
- 設定以 Microsoft Entra ID 為基礎的員工身分聯盟
- 設定以 Okta 為基礎的員工身分聯盟
記下工作團隊身分集區 ID 和工作團隊身分集區提供者 ID。
確認您具備 Identity and Access Management (IAM) 權限 serviceusage.services.use。包含這項權限的最低權限角色是服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)。
Enable the IAM and Security Token Service APIs.
Enable the APIs
After installing the Google Cloud CLI, initialize it by running the following command:
```
gcloud init
```
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

將外部憑證換成 Google Cloud 存取權杖

本節說明如何使用 Security Token Service，將外部憑證換成可授予Google Cloud存取權的存取權杖。如要執行這項操作，可以使用 gcloud CLI、REST API 和 Cloud 用戶端程式庫，詳情請參閱本指南後續內容。

如需長期存取權，您可以設定長時間執行的程序，在該機器上持續更新憑證。或者，您也可以在背景執行本機伺服器，並使用傳回憑證的端點。

本節說明如何設定 gcloud CLI，以使用瀏覽器型登入流程。如要這麼做，請建立登入設定檔，然後在對 gcloud auth login 的呼叫中參照該檔案，或啟用該檔案，使其成為預設使用的檔案。

如要建立登入設定檔，請執行下列指令。您可以視需要新增 --activate 標記，將檔案設為 gcloud CLI 的預設設定。這樣一來，您之後執行 gcloud auth login 時，就不必每次都指定設定檔路徑。

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊集區 ID
PROVIDER_ID：供應商 ID
LOGIN_CONFIG_FILE_PATH：您指定的設定檔路徑，例如 login.json

這個檔案包含 gcloud CLI 用來啟用瀏覽器式驗證流程的端點，並將目標對象設為工作團隊身分集區提供者中設定的 IdP。檔案不含機密資訊。

輸出看起來類似以下內容：

{
  "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://googleapis.com/v1/introspect",
}

如要停止讓 gcloud auth login 自動使用這個設定檔，可以執行 gcloud config unset auth/login_config_file 取消設定。

如要使用瀏覽器型登入驗證進行驗證，可以採用下列其中一種方法：

如果您在建立設定檔時使用 --activate 標記，或使用 gcloud config set auth/login_config_file 啟用設定檔，gcloud CLI 會自動使用您的設定檔：
```
gcloud auth login
```
如要指定設定檔位置來登入，請執行下列指令：
```
gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
```
如要使用環境變數指定設定檔位置，請將 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 設為設定路徑。

如要停止使用登入設定檔，請按照下列步驟操作：

如果您在建立設定檔時使用了 --activate 旗標，或是使用 gcloud config set auth/login_config_file 啟用了設定檔，則必須執行下列指令來取消設定：
```
gcloud config unset auth/login_config_file
```
清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境變數 (如果已設定)。

使用設定檔登入

除了透過瀏覽器登入，本節也會說明如何使用憑證設定檔，提供已驗證Google Cloud 動作的存取權。設定設定檔時，您不需要登入 gcloud CLI。

設定檔的設定方式取決於 IdP 使用 OIDC 或 SAML。

OIDC

您可以使用下列來源的憑證設定設定檔：

檔案來源憑證
透過網址取得憑證
非互動式可執行檔來源憑證
互動式可執行檔來源憑證

檔案來源憑證

使用檔案來源憑證時，權杖會從檔案載入。在舊權杖到期前，其他程序必須使用新的 OIDC 權杖重新整理這個檔案。舉例來說，如果權杖的效期為一小時，您必須在一小時前重新整理檔案。

如要使用檔案來源憑證產生設定檔，請執行下列指令：

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID
PATH_TO_OIDC_TOKEN：OIDC IdP 憑證檔案的路徑
WORKFORCE_POOL_USER_PROJECT：與工作人員集區使用者專案相關聯的專案編號或 ID。

主體必須具備這項專案的 serviceusage.services.use 權限。

執行指令後，會產生類似下列內容的 OIDC IdP 設定檔：

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

網址來源憑證

使用網址來源憑證時，權杖會從本機伺服器載入，該伺服器的端點會回應 HTTP GET 要求。回應必須是 OIDC ID 權杖，格式為純文字或 JSON。

如要使用網址來源憑證產生設定檔，請執行下列指令：

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID。
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。
URL_TO_RETURN_OIDC_ID_TOKEN：用於擷取 OIDC 憑證 (例如 OIDC ID 權杖) 的呼叫網址，例如：http://localhost:5000/token。
WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號。主體必須具備這項專案的 serviceusage.services.use permission 權限。

執行指令後，會產生類似下列內容的 OIDC IdP 設定檔：

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

從可執行檔來源取得的非互動式憑證

使用非互動式可執行檔來源憑證時，系統會從本機可執行檔載入權杖。可執行檔必須以 JSON 格式向 stdout 提供有效的未過期 OIDC ID 權杖：

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

這些欄位是成功回應的必要條件，但 expiration_time 除外。只有在憑證設定中指定輸出檔案時，才需要 expiration_time 欄位。

可執行檔必須以以下 JSON 格式向 stdout 回報任何錯誤：

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

這些欄位都是錯誤回應的必填欄位。用戶端程式庫會使用程式碼和訊息欄位，引發適當的錯誤。

這項指令可以傳回下列欄位：

version：JSON 輸出內容的版本。僅支援版本 1。
success：回應的狀態。如果狀態為 true，可執行檔必須以結束代碼 0 結束，且回應必須包含下列欄位：
- token_type：id_token
- expiration_time 欄位 (如果憑證設定中指定了輸出檔案)
如果狀態為 false，可執行檔必須以非零值結束，且回應必須包含下列欄位：
- code
- message
token_type：第三方主體權杖類型，必須為 urn:ietf:params:oauth:token-type:id_token
id_token：第三方 OIDC 權杖
expiration_time：第三方 OIDC 權杖的到期時間 (以秒為單位，Unix 紀元時間)
code：錯誤代碼字串
message：錯誤訊息

執行可執行檔時，用戶端程式庫會設定下列環境變數：

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE：憑證設定中的目標對象欄位。這個變數一律會設定。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE：預期的主體權杖類型。這個變數一律會設定。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE：憑證設定的輸出檔案位置。只有在憑證設定中指定這個變數時，才會顯示這個變數。

可執行檔可以使用這些環境變數，避免對這些值進行硬式編碼。

如要透過用戶端程式庫啟用這項憑證來源方法，請將 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境變數設為 1。

如要使用可執行檔來源的憑證產生設定檔，請執行下列指令：

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID。
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。
EXECUTABLE_COMMAND：完整指令，包括要執行的引數，用於以 --executable-command="/path/to/command --foo=bar" 格式擷取主體權杖 (例如 OIDC ID 權杖)。
EXECUTABLE_TIMEOUT：選用。等待可執行檔執行的時間長度 (以毫秒為單位)，預設為 30 秒。
EXECUTABLE_OUTPUT_FILE：選用。可執行檔產生的第三方憑證路徑。這項功能有助於快取憑證。Auth 程式庫會先檢查這個路徑，再執行可執行檔。
WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號或 ID。主體必須具備這項專案的 serviceusage.services.use 權限。

執行指令後，會產生類似下列內容的 OIDC IdP 設定檔：

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

互動式可執行檔來源憑證

使用互動式可執行檔來源憑證時，您可以提供透過 stdin 和 stdout 與使用者互動的可執行檔。如果使用者成功登入，可執行檔會將有效且未過期的憑證寫入指定檔案。

如要使用這個模式，必須設定下列標記：

--executable-output-file：可執行檔將憑證資訊寫入的檔案
--exeutable-interactive-timeout-millis：非零值，表示互動模式並設定逾時時間，例如 60 秒逾時時間的 6000

以下欄位為成功回應的必要欄位，但 expiration_time 除外：

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

可執行檔必須將所有錯誤寫入 --executable-output-file 中指定的檔案，並採用下列 JSON 格式。傳回錯誤回應時，必須填寫下列欄位。

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

code 和 message 欄位必須指出適當的錯誤。用戶端程式庫引發錯誤時，會使用這些欄位。

成功執行後，指令會傳回互動式和非互動式可執行檔來源憑證的相同欄位。

互動式和非互動式可執行檔來源憑證的環境變數也相同。

如要產生互動式可執行檔來源憑證，請新增 --executable-interactive-timeout-millis 參數和 --executable-output-file 參數。

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID。
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。
EXECUTABLE_COMMAND：完整指令，包括要執行的引數，用於擷取主體權杖，格式如下： --executable-command="/path/to/command --arg1=val1 --arg2=val2"
EXECUTABLE_INTERACTIVE_TIMEOUT：等待可執行檔執行的時間長度 (以毫秒為單位)。
EXECUTABLE_OUTPUT_FILE：可執行檔產生的第三方憑證路徑。這個路徑可用於快取憑證。驗證程式庫會先檢查這個路徑，再執行可執行檔。
WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號或 ID。主體必須具備這項專案的「serviceusage.services.use」權限。

執行指令後，會產生類似下列內容的 OIDC IdP 設定檔：

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

因為在某些情況下，互動式可執行檔也可以在非互動模式下執行，所以系統會傳回 timeout_millis 欄位。在互動模式中，指令會傳回預設逾時。

SAML

您可以使用下列來源的憑證設定設定檔：

檔案來源憑證
透過網址取得憑證
可執行檔來源憑證
gcloud 互動模式的可執行檔來源憑證

檔案來源憑證

系統會從檔案載入斷言。在舊的 SAML 判斷提示過期前，另一個程序必須以新的 base64 編碼 SAML 判斷提示重新整理這個檔案。舉例來說，如果聲明效期為一小時，您就必須在一小時前重新整理檔案。

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID。
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。
CREDENTIAL_FILE：IdP 產生的憑證檔案路徑。
WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號或 ID。主體必須具備這項專案的 serviceusage.services.use permission。

網址來源憑證

系統會從本機伺服器載入聲明，該伺服器具有可回應 HTTP `GET` 要求的端點。回應必須是 [以 base64 編碼](https://toolbox.googleapps.com/apps/encode_decode/)的 SAML 聲明，或是包含以 base64 編碼 SAML 聲明的 JSON。如要使用網址來源的憑證，請使用 `--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 ``` 請替換下列項目： * WORKFORCE_POOL_ID：員工身分集區 ID。 * WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。* CREDENTIAL_URL：本機伺服器端點的網址。 * WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號或 ID。主體必須具備這個專案的 `serviceusage.services.use 權限`。

可執行檔來源憑證

系統會從本機可執行檔載入斷言。可執行檔必須以 JSON 格式向 stdout 提供有效且未過期的 SAML 判斷。

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

這些欄位是成功回應的必要條件，但 expiration_time 除外。只有在憑證設定中指定輸出檔案時，才需要 expiration_time 欄位。

如果發生錯誤，可執行檔必須以下列 JSON 格式透過 stdout 顯示錯誤：

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

這些欄位都是錯誤回應的必填欄位。用戶端程式庫會使用程式碼和訊息欄位，引發適當的錯誤。

這項指令可以傳回下列欄位：

version：JSON 輸出內容的版本。僅支援版本 1。
success：回應的狀態。如果狀態為 true，可執行檔必須以結束代碼 0 結束，且回應必須包含下列欄位：
- token_type：saml_response
- expiration_time 欄位 (如果憑證設定中指定了輸出檔案)
如果狀態為 false，可執行檔必須以非零值結束，且回應必須包含下列欄位： + code + message
token_type：第三方主體權杖類型，必須為 urn:ietf:params:oauth:token-type:saml2
saml_response：第三方 SAML 回應
expiration_time：第三方 SAML 回應到期時間 (以秒為單位，Unix 紀元時間)
code：錯誤代碼字串
message：錯誤訊息

執行可執行檔時，用戶端程式庫會設定下列環境變數：

GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE：憑證設定中的目標對象欄位。這個變數一律會設定。
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE：預期的主體權杖類型。這個變數一律會設定。
GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE：憑證設定的輸出檔案位置。只有在憑證設定中指定這個變數時，才會顯示這個變數。

如要透過用戶端程式庫啟用這項憑證來源方法，請將 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 環境變數設為 1。

如要使用可執行檔來源的憑證產生設定檔，請執行下列指令：

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID。
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。
EXECUTABLE_COMMAND：完整指令，包括要執行的引數，用於擷取主體權杖，格式如下：--executable-command="/path/to/command --foo=bar"。
EXECUTABLE_TIMEOUT：選用。等待可執行檔執行的時間長度 (以毫秒為單位)，預設為 30 秒。
EXECUTABLE_OUTPUT_FILE：選用。可執行檔產生的第三方身分 (3PI) 憑證路徑。這項功能有助於快取憑證。授權程式庫會在執行可執行檔前檢查是否存在。
WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號。主體必須具備這項專案的「serviceusage.services.use」權限。

執行指令後，會產生類似下方的 SAML IdP 設定檔：

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

gcloud 互動模式的可執行檔來源憑證

在 gcloud 互動模式中，如果使用可執行檔來源的憑證，可執行檔會透過指令列介面與使用者互動。

在上述指令中，請替換下列項目：

EXECUTABLE_OUTPUT_FILE：必填。提供可執行檔所產生憑證的檔案路徑。
EXECUTABLE_TIMEOUT：必填。非零的逾時值也會向指令發出訊號，表示要使用互動模式。

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

這些欄位是成功回應的必要條件，但 expiration_time 除外。如果省略 expiration_time，系統仍會執行可執行檔。

可執行檔必須以以下 JSON 格式，向 executable-output-file 顯示任何錯誤。如果可執行檔回報錯誤，這些欄位就全都是必填欄位。用戶端程式庫會使用代碼和訊息欄位，引發適當的錯誤。

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

成功執行指令後，系統會傳回與非互動式可執行檔來源憑證相同的欄位。

環境變數也與非互動式可執行檔來源憑證相同。

如要產生互動式可執行檔來源憑證，請新增 --executable-interactive-timeout-millis 參數。

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

更改下列內容：

WORKFORCE_POOL_ID：工作團隊身分集區 ID。
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID。
EXECUTABLE_COMMAND：完整指令，包括要執行的引數，用於擷取主體權杖，格式如下： --executable-command="/path/to/command --foo=bar")。
EXECUTABLE_INTERACTIVE_TIMEOUT：等待可執行檔執行的時間長度 (以毫秒為單位)。
EXECUTABLE_OUTPUT_FILE：可執行檔產生的第三方憑證路徑。這項功能有助於快取憑證。驗證程式庫會先檢查這個路徑，再執行可執行檔。
WORKFORCE_POOL_USER_PROJECT：用於配額和帳單的專案編號或 ID。主體必須具備這項專案的「serviceusage.services.use」權限。

執行指令後，會產生類似下列內容的 SAML IdP 設定檔：

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

如要登入，請執行下列指令：

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

請注意，gcloud CLI 和 bq 指令列工具都不支援可執行檔來源的憑證類型。

對於無頭流程，gcloud CLI 會自動使用下列範圍：https://www.googleapis.com/auth/cloud-platform。接著，gcloud CLI 會將您的憑證透明地發布至 Security Token Service 端點，並換取臨時Google Cloud 存取權杖。

現在您可以使用 gcloud CLI 執行 gcloud 指令。

使用 Google Cloud 用戶端程式庫

如果您使用支援的用戶端程式庫，可以設定該程式庫自動產生 Google 憑證。建議您盡可能自動產生憑證，這樣就不必自行導入權杖交換程序。

Google Cloud 下列語言支援工作人員集區的用戶端程式庫：Node.js、Java、Python、Go 和 C++ (gRPC)。

如要搭配這些服務或語言使用用戶端程式庫，請按照下列步驟操作：

bq 工具

如要使用員工身分聯盟進行驗證，請使用 gcloud auth login 指令：

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

其中 FILEPATH 是指憑證設定檔的路徑。

Google Cloud CLI 390.0.0 以上版本的 bq 工具支援員工身分聯盟。

C++

大多數 Google Cloud C++ 用戶端程式庫都支援使用 ChannelCredentials 物件的 Workforce Identity 聯盟，該物件是透過呼叫 grpc::GoogleDefaultCredentials() 建立。如要初始化這項憑證，您必須使用 gRPC 1.42.0 以上版本建構用戶端程式庫。

C++ 適用的 Cloud Storage Cloud 用戶端程式庫使用 REST API，而非 gRPC，因此不支援 Workforce Identity Federation。

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

如要使用員工身分聯盟進行驗證，請使用 gcloud auth login 指令：

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

將 FILEPATH 替換為憑證設定檔的路徑。

Google Cloud CLI 392.0.0 以上版本支援 gcloud CLI 中的員工身分聯盟。

Go

使用 golang.org/x/oauth2 模組的 v0.0.0-20211005180243-6b3c2da341f1 以上版本時，Go 適用的 Cloud 用戶端程式庫支援員工身分聯盟。

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

使用 com.google.auth:google-auth-library-oauth2-http 構件 1.2.0 以上版本時，Java 適用的 Cloud 用戶端程式庫支援員工身分聯盟。

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

使用 google-auth-library 套件 7.10.0 以上版本時，Node.js 適用的 Cloud 用戶端程式庫支援員工身分聯盟。

與工作負載身分集區不同，工作團隊身分集區與機構相關聯，而非 Google Cloud 專案。建立 GoogleAuth 物件時，您必須指定專案 ID。詳情請參閱 google-auth-library 套件的 README。

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

使用 google-auth 套件 2.3.0 以上版本時，Python 適用的 Cloud 用戶端程式庫支援員工身分聯盟。

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)

在程式碼範例中，如果程式庫無法自動探索專案 ID，project 值可以是 None。使用服務執行個體時，您可以明確傳遞專案 ID (如儲存空間用戶端範例所示)，也可以透過環境變數 GOOGLE_CLOUD_PROJECT 設定專案 ID。

詳情請參閱 google-auth 套件的使用手冊。

使用 REST API。

您可以執行下列指令，呼叫 Google Cloud 安全權杖服務 API，將外部憑證換成 Google Cloud 存取權杖：

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\"}"

更改下列內容：

AUDIENCE：核發主體權杖的供應商完整資源名稱。
WORKFORCE_POOL_ID：工作團隊身分集區 ID
WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商 ID
SUBJECT_TOKEN_TYPE：設為下列其中一個值：
- urn:ietf:params:oauth:token-type:id_token，適用於 OIDC ID 權杖
- urn:ietf:params:oauth:token-type:saml2，適用於 SAML 宣告
EXTERNAL_SUBJECT_TOKEN：IdP 核發的權杖，代表要求存取權杖的主體身分。

如果您已設定 OIDC 供應商，權杖必須採用 JWT 格式。
BILLING_PROJECT_NUMBER：用於配額和帳單的專案編號或 ID。主體必須具備這項專案的「serviceusage.services.use」權限。

回應類似以下內容：

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

使用 gcloud CLI 管理工作階段

gcloud CLI 從 Security Token Service 端點取得的臨時 Google Cloud 權杖，會在指定時間間隔後過期。權杖即將過期時，gcloud CLI 會檢查您提供的憑證檔案，以及從 IdP 收到的憑證是否有效。如果憑證仍然有效，gcloud CLI 會繼續以透明方式取得新的Google Cloud 存取權杖，目前的工作階段也會繼續執行，不會中斷。

如果憑證已過期，系統就不會核發新的 Google Cloud 權杖，且您使用這些憑證進行的任何呼叫都會失敗。這時，您必須重新驗證。

您可以執行下列指令來終止工作階段：

gcloud auth revoke

gcloud 支援多個使用者工作階段。如要取得工作階段清單 (包括目前使用中的工作階段)，請執行下列指令：

gcloud auth list

指令會輸出類似以下的結果：

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

如要切換至其他工作階段並設為現行工作階段，請執行下列指令：

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

後續步驟

刪除 Workforce Identity Federation 使用者及其資料
瞭解 Google Cloud 支援員工身分聯盟的產品
設定使用者對控制台 (聯合) 的存取權

取得員工身分聯盟的短期權杖 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

將外部憑證換成 Google Cloud 存取權杖

使用 gcloud CLI 透過瀏覽器登入

建立登入設定檔

使用瀏覽器驗證功能登入

停用透過瀏覽器登入

使用設定檔登入

OIDC

檔案來源憑證

網址來源憑證

從可執行檔來源取得的非互動式憑證

互動式可執行檔來源憑證

SAML

檔案來源憑證

網址來源憑證

可執行檔來源憑證

gcloud 互動模式的可執行檔來源憑證

使用 Google Cloud 用戶端程式庫

bq 工具

C++

gcloud

Go

Java

Node.js

Python

使用 REST API。

使用 gcloud CLI 管理工作階段

後續步驟

取得員工身分聯盟的短期權杖