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

設定員工身分聯盟 (BYOID)

本指南說明如何使用員工身分聯盟和 Workload Identity Federation，為多方運算 API 設定自備身分 (BYOID)。透過身分聯盟，人類使用者和自動化簽署者工作負載，可以使用貴組織的外部身分識別資訊提供者 (IdP) (例如 Okta、Microsoft Entra ID 或 Ping Identity)，向多方運算進行驗證。您不需要建立 Google 帳戶，也不必管理長期服務帳戶金鑰。

總覽

身分聯盟與多方運算縱深防禦安全模型整合，涵蓋下列層級：

Edge Identity and Access Management (IAM) 授權：呼叫端會將外部 OpenID Connect (OIDC) 或 SAML 2.0 IdP 的憑證，與 Google Cloud Security Token Service (Security Token Service) 交換，以取得短效期的聯合存取權杖。 Google Cloud API 閘道會先根據聯合主體 URI 評估 IAM 角色繫結，再將要求轉送至多方運算執行個體，並為 Cloud 稽核記錄傳播聯合身分 (principalSubject)。
分散權責和密碼編譯核准：IAM 角色會區分管理佈建 (roles/mpc.admin)、作業參與 (roles/mpc.editor) 和唯讀監督 (roles/mpc.viewer)。在執行個體中，管理員、政策作者和簽署者也需要使用者，執行個體會檢查該使用者的角色 (ADMIN、POLICY_AUTHOR 或 SIGNER)，確認是否有代表使用者執行的方法，且核准必須使用在該使用者註冊的授權金鑰簽署。詳情請參閱「如何授權要求」。

視呼叫端類型而定，您可以使用兩種身分聯合機制：

員工身分聯盟 (locations/global/workforcePools/...)：使用對應至企業 IdP 的組織層級員工集區，驗證人類使用者 (管理員、政策作者、簽署者和法規遵循人員)。本指南將逐步說明如何設定員工身分聯盟。
Workload Identity Federation (projects/.../locations/global/workloadIdentityPools/...)：使用專案層級的 workload identity pool，驗證自動化工作負載 (例如在 AWS、Azure 或 Kubernetes 中執行的無頭共同簽署者 daemon)。

如要進一步瞭解 IAM 角色如何對應至多方運算角色，請參閱「安全性與授權」。

事前準備

開始前，請確認您具備以下項目：

Google Cloud 組織和用戶專案已加入多方運算。
已安裝 gcloud CLI 和 jq，且 gcloud 已使用具備下列角色的管理員帳戶完成驗證：
- Google Cloud 組織的工作團隊集區管理員 (roles/iam.workforcePoolAdmin) (如果在步驟 1 建立新的工作團隊集區)。
- 在用戶專案中具備專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 和服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin) 角色。

在用戶專案中啟用的必要 API：

gcloud services enable mpc.googleapis.com iam.googleapis.com sts.googleapis.com \
  --project="my-project"

在企業 IdP 中設定的外部 OIDC 或 SAML 2.0 應用程式。如果您打算透過 gcloud CLI 使用互動式瀏覽器登入，請在 IdP 應用程式中設定 Google Cloud 重新導向 URI (請參閱 Okta 和 Microsoft Entra ID 的設定指南)。

設定

更新下列變數，填入本指南中的指令。

必要設定參數

請根據您的 Google Cloud 環境和外部 IdP 設定，自訂這些參數。

參數	值	說明
組織 ID	`123456789012`	您的 Google Cloud 組織 ID (數字)。
專案 ID	`my-project`	為多方運算執行個體註冊的用戶專案 ID。
網域 ID	`67317436-0f29-ba9e-9146-d11c0bd8df9b`	指派給多方運算執行個體的專屬網域 ID。
執行個體路徑 ID	`mpc-unit-bob-123`	指派給多方運算執行個體的執行個體路徑 ID。
位置	`us-central1`	部署位置 (`us-central1`)。詳情請參閱「Multi-party Compute 位置」。
工作團隊集區 ID	`mpc-workforce-pool`	組織層級的工作團隊身分集區 ID。
Provider ID	`mpc-oidc-provider`	員工身分集區提供者 ID。
IdP 核發者 URI	`https://idp.example.com`	外部 OIDC IdP 核發者 URI。
IdP 用戶端 ID	`mpc-client`	在外部 IdP 中設定的 OAuth 2.0 用戶端 ID。

步驟 1：設定工作團隊身分集區和提供者

員工身分集區 (locations/global/workforcePools/mpc-workforce-pool) 是組織層級資源，會對應至企業 IdP 租戶。您不必為每項專案或角色建立個別的工作團隊集區。

在 Google Cloud 組織中建立員工身分集區：

gcloud iam workforce-pools create "mpc-workforce-pool" \
  --organization="123456789012" \
  --location="global" \
  --display-name="MPC Workforce Pool"

建立 OIDC 工作團隊集區提供者，信任外部 IdP 並對應主體和群組憑證附加資訊：
```
gcloud iam workforce-pools providers create-oidc "mpc-oidc-provider" \
  --workforce-pool="mpc-workforce-pool" \
  --location="global" \
  --display-name="MPC Enterprise OIDC Provider" \
  --issuer-uri="https://idp.example.com" \
  --client-id="mpc-client" \
  --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups" \
  --web-sso-response-type="id-token" \
  --web-sso-assertion-claims-behavior="only-id-token-claims"
```
注意： 根據預設，Security Token Service 會從 IdP 的 /.well-known/openid-configuration 端點探索及輪替公開簽署金鑰。如果您使用離線或合成 OIDC 核發者進行測試，且該核發者無法公開存取，請傳遞 --jwk-json-path="<var>PATH_TO_JWK_FILE</var>"，並將 <var>PATH_TO_JWK_FILE</var> 替換為核發者公開 JSON Web Key Set (JWKS) 檔案的本機路徑。如果是 SAML 2.0 供應商，請使用 gcloud iam workforce-pools providers create-saml 和 --idp-metadata-path。

步驟 2：將 IAM 角色授予聯合主體

如要呼叫 MPC API，聯合主體必須在用戶專案 (my-project) 具備兩種 IAM 角色繫結：

服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)：授權聯合身分將 API 配額和帳單歸因於消費者專案。
Multi-party Compute 角色 (roles/mpc.admin、roles/mpc.editor 或 roles/mpc.viewer)，可授權特定 Multi-party Compute 作業。

在正式環境中，將 IAM 角色繫結至工作團隊集區中的不同 IdP 群組：

# 1. Allow members of the workforce pool to consume APIs through the consumer project
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/serviceusage.serviceUsageConsumer" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/*"

# 2. Grant MPC Admin to the enterprise administrators group
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.admin" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-admins"

# 3. Grant MPC Editor to Policy Authors and Signers groups
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.editor" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-policy-authors"

gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.editor" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-signers"

# 4. Grant MPC Viewer to the Compliance group
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.viewer" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-auditors"

自動化簽署者工作負載 (Workload Identity Federation)

如果您在 Google Cloud 外部 (例如 AWS、Azure 或 Kubernetes) 執行自動化共同簽署者 daemon，請設定專案範圍的 workload identity pool 和提供者。將 roles/serviceusage.serviceUsageConsumer 和 roles/mpc.editor 授予工作負載主體 (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>，將 <var>PROJECT_NUMBER</var>、<var>WORKLOAD_POOL_ID</var> 和 <var>SIGNER_NODE_SUBJECT</var> 替換為您的專案編號、工作負載集區 ID 和工作負載 sub 宣告)，並使用 gcloud iam workload-identity-pools create-cred-config 產生應用程式預設憑證檔案。

將聯合身分新增為 v1beta 使用者

在 v1beta API 中，這個步驟的 IAM 角色可讓聯合身分呼叫執行個體。如要在執行個體中以管理員、政策作者或簽署者的身分執行操作，身分也需要使用者。執行個體會比對呼叫端的主體與每位使用者的 principal 欄位，藉此識別呼叫端。

如果是員工身分聯盟身分，請將 principal 設為身分的主體主體 ID：

principal://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/subject/SUBJECT_ID

將 SUBJECT_ID 替換為供應商對應至 google.subject 的值。根據步驟 1 的屬性對應，這是使用者 ID 權杖的 sub 宣告。

設定 principal 時，請注意下列事項：

請使用 principal:// ID，而非 principalSet:// ID。「使用者」是指一個人。principalSet://.../group/mpc-signers 等群組和集區 ID 可用於 IAM 角色繫結，但不會與呼叫端相符，因此使用這類 ID 建立的使用者無法在執行個體中執行操作。
與主旨完全一致。執行個體會區分大小寫來比較工作團隊和工作負載主體，因此請複製 IdP 核發的主體。比對 Google 帳戶電子郵件 (例如 alice@example.com) 時，不區分大小寫。
principal設定後即無法變更。如要變更使用者身分，請停用該使用者並建立新使用者。

步驟 3：驗證並取得聯合存取權杖

MPC API 不會直接接受 IdP 的 OIDC 權杖或 SAML 斷言。呼叫多方運算執行個體端點 (*.mpc.goog) 前，請先使用 Security Token Service 將 IdP 憑證換成聯合 Google Cloud 存取權杖。

您可以使用應用程式預設憑證 (ADC) 和 gcloud CLI 自動取得及管理聯合存取權杖，也可以使用 Security Token Service API，透過程式輔助方式取得及管理聯合存取權杖。

應用程式預設憑證和 gcloud CLI

在正式版用戶端應用程式和互動式 CLI 工作階段中，請使用設定檔，讓 Google Cloud SDK 和 Cloud 用戶端程式庫自動處理背景 Security Token Service 權杖交換、快取和重新整理作業。

方法 A：互動式瀏覽器登入

產生登入設定檔，並使用公司 IdP 驗證 gcloud CLI 和應用程式預設憑證 (ADC)：

gcloud iam workforce-pools create-login-config \
  "locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --activate \
  --output-file="login-config.json"

gcloud config set billing/quota_project "my-project"
gcloud auth login --login-config="login-config.json"
gcloud auth application-default login --login-config="login-config.json"

方法 B：使用憑證設定檔 (ADC) 進行非互動式登入

如果外部程序在本機檔案 (例如 /var/run/secrets/tokens/oidc-token) 中提供並重新整理已簽署的 OIDC 權杖，請在權杖到期前產生外部憑證設定檔：

gcloud iam workforce-pools create-cred-config \
  "locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
  --credential-source-file="/var/run/secrets/tokens/oidc-token" \
  --workforce-pool-user-project="my-project" \
  --output-file="credential-config.json"

export GOOGLE_APPLICATION_CREDENTIALS="$(pwd)/credential-config.json"

匯出 curl 要求的存取權杖：

完成選項 A 或選項 B 後，請將 ADC 的聯合存取權杖匯出至 ACCESS_TOKEN：

export ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"

直接 REST STS 權杖交換

如果您要整合不含 Google Cloud SDK 的自訂用戶端，請直接與 Security Token Service 交換已簽署的 OIDC ID 權杖 (<var>IDP_ID_TOKEN</var>)。在 options 欄位中加入 userProject，讓 Google Cloud 將權杖歸因於您的消費者專案：

# Set IDP_ID_TOKEN to the signed OIDC JWT assertion from your external IdP
# export IDP_ID_TOKEN="eyJhbGciOiJSUzI1NiIs..."

STS_RESPONSE=$(curl -sS -X POST "https://sts.googleapis.com/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
  --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  --data-urlencode "subject_token=${IDP_ID_TOKEN}" \
  --data-urlencode 'options={"userProject":"my-project"}')

export ACCESS_TOKEN=$(echo "${STS_RESPONSE}" | jq -er '.access_token') || echo "${STS_RESPONSE}" | jq .

步驟 4：驗證聯合 API 存取權

列出多方運算執行個體中的使用者，確認聯合憑證、userProject 歸因和 IAM 角色繫結是否正常運作。由於 mpc.googleapis.com/users.list 包含在 roles/mpc.viewer、roles/mpc.editor 和 roles/mpc.admin 中，因此任何獲得授權的聯合角色都可以執行這項檢查：

curl -sS -X GET \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: my-project" \
  "https://67317436-0f29-ba9e-9146-d11c0bd8df9b.us-central1.mpc.goog/v1beta/projects/my-project/locations/us-central1/instances/mpc-unit-bob-123/users" | jq .

200 OK JSON 回應 (新執行個體上的 {} 或 users 清單) 確認聯合身分已通過驗證，並有權呼叫多方運算執行個體。

這項檢查只會使用 IAM。如要確認執行個體也將您的身分視為使用者，請檢查傳回的使用者中，是否有一個使用者的 principal 欄位含有您的 principal:// 識別碼。詳情請參閱「將聯合身分新增為 v1beta 使用者」。

疑難排解

使用聯合憑證呼叫多方運算時，如果發生驗證或權限錯誤，請確認是否符合下列要求：

使用者專案歸因 (`401 UNAUTHENTICATED: Unable to determine client project number`)

原因：除非在權杖交換期間或要求中指定使用者專案，否則組織層級工作團隊集區憑證不會與單一 Google Cloud 專案繫結。
解決方法：在 Security Token Service 權杖交換要求主體中加入 options: {"userProject": "<var>PROJECT_ID</var>"} (或在 gcloud iam workforce-pools create-cred-config 中加入 --workforce-pool-user-project)，並在 MPC API 呼叫中加入 X-Goog-User-Project: <var>PROJECT_ID</var> 標頭。

缺少 Service Usage 權限 (`403 PERMISSION_DENIED`)

原因：聯合主體或群組沒有權限，無法將 API 用量歸因於 userProject 或 X-Goog-User-Project 中指定的消費者專案。
解決方法：將 roles/serviceusage.serviceUsageConsumer 授予用戶專案的 principal:// 或 principalSet:// 成員 (請參閱步驟 2)。

消費者專案不符 (`403 PERMISSION_DENIED: Project is not allowed to call the API through this host`)

原因：每個專屬多方運算執行個體端點，只會接受來自為該執行個體設定的消費者專案要求。
解決方法：確認要求網址路徑和 userProject/X-Goog-User-Project 標頭中的 <var>PROJECT_ID</var>，與為多方運算執行個體佈建的用戶專案相符。

憑證無效 (`401 UNAUTHENTICATED: Request credential is invalid`)

原因：第三方 OIDC 權杖或 SAML 斷言直接傳送至多方運算端點，未先使用 Security Token Service 交換。
解決方法：透過 https://sts.googleapis.com/v1/token 交換 IdP 憑證 (或使用應用程式預設憑證)，並在 Authorization: Bearer 標頭中傳遞產生的 Google Cloud 存取權杖。

網域限制共用政策會封鎖角色繫結 (`400 FAILED_PRECONDITION`)

原因： Google Cloud 組織強制執行 constraints/iam.allowedPolicyMemberDomains 組織政策，限制哪些主體網域可獲得專案的 IAM 角色。
解決方法：請要求組織政策管理員，將工作團隊集區主體集，新增至用戶專案或組織中允許的政策成員網域，或是在 constraints/iam.allowedPolicyMemberDomains 允許工作團隊集區的專案中測試。

後續步驟

如要建立使用者、團隊、交易政策和金鑰，以及使用聯合身分簽署交易，請參閱多方運算使用手冊。將每位使用者的主體設為「將聯合身分新增為 v1beta 使用者」一節所述的 principal:// 識別碼。
使用者指南會使用 gcloud auth print-access-token 擷取每個角色的存取權杖，該指令會使用 gcloud CLI 憑證，而非應用程式預設憑證。使用 gcloud auth login --login-config 登入每位聯合使用者，如步驟 3 的選項 A 所示。
如要進一步瞭解使用者角色、IAM 權限和資源層級條件，請參閱「安全性與授權」。