本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

您可以使用員工身分集區和員工身分集區提供者，從 Security Token Service 或 Cloud OAuth API 取得短期權杖。這些權杖可讓您存取 Cloud de Confiance by S3NS 資源，前提是這些資源支援員工身分聯盟，且您具備相關權限。

您可以在無頭機器上使用本文所述的方法。

如要取得短期權杖，請按照下列概略程序操作：

從信任的身分識別提供者 (IdP) 取得憑證，或將使用者重新導向至授權端點 (https://auth.cloud.google/authorize)，以便透過 IdP 登入並取得授權碼。
將憑證或授權碼，交換為 Security Token Service 或 Cloud OAuth API 的權杖。

事前準備

設定員工身分聯盟，或參閱下列指南，瞭解特定 IdP 的操作說明：
- 設定以 Microsoft Entra ID 為基礎的員工身分聯盟
- 設定以 Okta 為基礎的員工身分聯盟
記下工作團隊身分集區 ID 和工作團隊身分集區提供者 ID。
請確認使用 Security Token Service 交換權杖的每個主體，都具備 Identity and Access Management (IAM) 權限 serviceusage.services.use。包含這項權限的最低權限角色是服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)。
啟用 IAM、Security Token Service 和 Cloud OAuth API API (如有尚未啟用的 API)。
啟用 API 所需的角色
您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API
安裝 Google Cloud CLI，然後使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：
```
gcloud init
```
注意：如果您已經安裝 gcloud CLI，請務必執行 gcloud components update，確認您安裝的是最新版本。

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

本節說明如何使用安全權杖服務或 Cloud OAuth API，將外部憑證換成可授予 Cloud de Confiance存取權的存取權杖。如要執行這項操作，請使用 gcloud CLI、REST API 和 Cloud 用戶端程式庫，詳情請參閱本文後續章節。

如要瞭解如何從授權端點 (https://auth.cloud.google/authorize) 取得授權碼，以及如何使用 Cloud OAuth API 交換授權碼和更新權杖，請參閱「使用 Cloud OAuth API 交換權杖」。

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

本節說明如何設定 gcloud CLI，以使用瀏覽器登入流程。為此，請建立登入設定檔，然後在呼叫 gcloud auth login 時參照該檔案，或啟用該檔案，以便預設使用。

執行下列指令，建立登入設定檔：

Linux 和 macOS

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

Windows (PowerShell)

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

注意：您可以選擇新增 --activate 旗標，將登入設定檔啟用為 gcloud CLI 的預設設定。接著，您可以執行 gcloud auth login 來授權 gcloud CLI，而不必每次都指定登入設定檔路徑。

更改下列內容：

WORKFORCE_POOL_ID：員工身分聯盟集區 ID。
WORKFORCE_PROVIDER_ID：員工身分聯盟提供者 ID。
LOGIN_CONFIG_PATH：：寫入登入設定檔的路徑。例如：login-config.json。

登入設定檔包含 gcloud CLI 使用的端點，可啟用瀏覽器型驗證流程，並將目標對象設為員工身分集區供應商中設定的 IdP。檔案不含機密資訊。

登入設定檔內容大致如下：

{
  "universe_domain": "s3nsapis.fr",
  "universe_cloud_web_domain": "cloud.s3nscloud.fr",
  "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.s3nscloud.fr/authorize",
  "token_url": "https://sts.s3nsapis.fr/v1/oauthtoken",
  "token_info_url": "https://sts.s3nsapis.fr/v1/introspect"
}

使用環境變數、有效 gcloud CLI 設定中的屬性，指向登入設定檔，或直接搭配 gcloud auth login 指令使用：

環境變數

如要搭配環境變數使用登入設定檔，請完成下列操作說明：

將 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境變數設為登入設定檔的路徑。
執行下列指令：
```
gcloud auth login
```
gcloud CLI 會參照環境變數來尋找登入設定檔，然後啟動驗證程序。按照瀏覽器流程驗證及授權 gcloud CLI，以便日後代表您存取資源。

如要停止使用 gcloud auth login 指令的登入設定檔，請清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 環境變數。

gcloud CLI 設定

如要搭配使用登入設定檔和 gcloud CLI 設定屬性，請完成下列操作：

使用下列指令，將有效 gcloud CLI 設定的 auth/login_config_file 屬性設為登入設定檔的路徑：
```
gcloud config set auth/login_config_file LOGIN_CONFIG_PATH
```
執行下列指令：
```
gcloud auth login
```
gcloud CLI 會參照設定屬性來尋找登入設定檔，然後啟動驗證程序。按照瀏覽器流程驗證及授權 gcloud CLI，以便日後代表您存取資源。

如要停止使用 gcloud auth login 指令的登入設定檔，請使用下列指令取消設定屬性：

gcloud config unset auth/login_config_file

如要直接搭配 gcloud auth login 指令使用登入設定檔，請完成下列操作說明：

如果您在建立登入設定檔時使用了 --activate 旗標，請執行下列指令：
```
gcloud auth login
```
如果您在建立登入設定檔時未使用 --activate 旗標，請執行下列指令：
Linux 和 macOS
gcloud auth login \ --login-config=LOGIN_CONFIG_PATH
Windows (PowerShell)
gcloud auth login ` --login-config=LOGIN_CONFIG_PATH
將 LOGIN_CONFIG_PATH 替換為登入設定檔的路徑。

gcloud auth login 指令會將存取憑證儲存在主目錄中。通過驗證的主體會成為有效 gcloud CLI 設定中的有效主體。除非遭到覆寫，否則 gcloud CLI 會使用這些儲存的憑證存取 Cloud de Confiance by S3NS。

使用設定檔登入

除了透過瀏覽器登入，本節也說明如何使用憑證設定檔，提供已驗證Cloud de Confiance 動作的存取權。設定設定檔時，不需登入 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 權限。

執行指令後，會產生類似下方的 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：執行後可擷取主體權杖 (例如 OIDC ID 權杖) 的完整指令 (包括引數)，格式如下：--executable-command="/path/to/command --foo=bar"。
EXECUTABLE_TIMEOUT：選用。等待執行檔執行的時間長度 (以毫秒為單位，預設為 30 秒)。
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",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

互動式可執行檔來源憑證

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

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

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

如要成功回應，必須提供下列欄位 (expiration_time 除外)：

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

執行檔必須以 JSON 格式將錯誤寫入 --executable-output-file 指定的檔案，傳回錯誤回應時，下列欄位皆為必填。

{
  "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 權限。

網址來源憑證

系統會從本機伺服器載入斷言，並使用端點回應 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 欄位。

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

{
  "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 端點，並在該端點交換臨時Cloud de Confiance 存取權杖。

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

使用 Cloud de Confiance 用戶端程式庫

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

Cloud de Confiance 用戶端程式庫支援下列語言的工作團隊集區：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++

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

C++ 適用的 Cloud Storage Cloud 用戶端程式庫使用 REST API，而非 gRPC，因此不支援員工身分聯盟。

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

如果您使用 1.2.0 以上版本的 com.google.auth:google-auth-library-oauth2-http 構件，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

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

與 workload identity pool 不同，員工身分集區與組織相關聯，而非 Cloud de Confiance 專案。建立 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

如果您使用 2.3.0 以上版本的 google-auth 套件，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。

如要從授權端點 (https://auth.cloud.google/authorize) 取得授權碼，並使用 Cloud OAuth API (cloudoauth.googleapis.com) 交換授權碼或更新權杖，請參閱「使用 Cloud OAuth API 交換權杖」。

您也可以呼叫 Cloud de Confiance Security Token Service API，執行下列指令，將外部憑證換成 Cloud de Confiance 存取權杖：

curl https://sts.s3nsapis.fr/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 權杖
- SAML 宣告的urn:ietf:params:oauth:token-type:saml2
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 端點取得的臨時 Cloud de Confiance 權杖，會在指定時間間隔後到期。權杖即將到期時，gcloud CLI 會檢查您提供的憑證檔案，以及從 IdP 收到的憑證是否有效。如果憑證仍有效，gcloud CLI 會繼續以透明方式取得新的Cloud de Confiance 存取權杖，目前的工作階段也會不中斷地執行。

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

如要終止工作階段，請執行下列指令：

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

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

事前準備

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

使用 gcloud CLI 透過瀏覽器登入

建立登入設定檔

Linux 和 macOS

Windows (PowerShell)

使用瀏覽器驗證登入

環境變數

gcloud CLI 設定

gcloud auth login

Linux 和 macOS

Windows (PowerShell)

使用設定檔登入

OIDC

檔案來源憑證

網址來源憑證

非互動式可執行檔來源憑證

互動式可執行檔來源憑證

SAML

檔案來源憑證

網址來源憑證

可執行檔來源憑證

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

使用 Cloud de Confiance 用戶端程式庫

bq 工具

C++

gcloud

Go

Java

Node.js

Python

使用 REST API。

使用 gcloud CLI 管理工作階段

後續步驟