Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

配置员工身份联合 (BYOID)

本指南介绍了如何使用员工身份联合和工作负载身份联合为 Multi-party Compute API 配置自备身份 (BYOID)。借助身份联合，人类用户和自动化签名者工作负载可以使用组织的外部身份提供方 (IdP)（例如 Okta、Microsoft Entra ID 或 Ping Identity）向多方计算进行身份验证。您无需创建 Google 账号或管理长期有效的服务账号密钥。

概览

身份联合在以下层级与多方计算纵深防御安全模型集成：

边缘 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 Audit Logs 传播联合身份 (principalSubject)。
职责分离和加密审批：IAM 角色将管理配置 (roles/mpc.admin)、操作参与 (roles/mpc.editor) 和只读监督 (roles/mpc.viewer) 分开。在实例中，管理员、政策作者和签名者还需要一个用户，实例会检查该用户的角色（ADMIN、POLICY_AUTHOR 或 SIGNER），以确定是否可以使用代表该用户执行操作的方法，并且审批必须使用在该用户上注册的授权密钥进行签名。如需了解详情，请参阅如何对请求进行授权。

根据调用方类型，您可以使用两种身份联合机制：

员工身份联合 (locations/global/workforcePools/...)：使用映射到企业 IdP 的组织级员工池对人类用户（管理员、政策作者、签名者和合规人员）进行身份验证。本指南将逐步介绍如何端到端配置员工身份联合。
工作负载身份联合 (projects/.../locations/global/workloadIdentityPools/...)：使用项目级工作负载身份池对自动化工作负载（例如在 AWS、Azure 或 Kubernetes 中运行的无头共同签名者守护程序）进行身份验证。

如需详细了解 IAM 角色如何映射到多方计算角色，请参阅安全和授权。

准备工作

在开始之前，请确保您具备以下条件：

Google Cloud 组织和已加入多方计算的使用方项目。
已安装 gcloud CLI 和 jq，并且 gcloud 已使用具有以下角色的管理员账号进行身份验证：
- Google Cloud 组织的 Workforce Pool Admin (roles/iam.workforcePoolAdmin)（如果在第 1 步中创建新的员工池）。
- 针对使用方项目的 Project IAM Admin (roles/resourcemanager.projectIamAdmin) 和 Service Usage Admin (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`)。如需了解详情，请参阅多方计算位置。
员工池 ID	`mpc-workforce-pool`	组织级层员工身份池 ID。
提供方 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 密钥集 (JWKS) 文件的本地路径。对于 SAML 2.0 提供商，请将 gcloud iam workforce-pools providers create-saml 与 --idp-metadata-path 搭配使用。

第 2 步：向联合主账号授予 IAM 角色

如需调用 MPC API，联合主账号需要在您的使用方项目 (my-project) 中拥有两种类型的 IAM 角色绑定：

Service Usage Consumer (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"

自动化签名者工作负载（工作负载身份联合）

如果您在 Google Cloud 之外（例如在 AWS、Azure 或 Kubernetes 中）运行自动化共同签名者守护程序，请配置项目级工作负载身份池和提供方。向工作负载主账号（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 声明）授予 roles/serviceusage.serviceUsageConsumer 和 roles/mpc.editor，并使用 gcloud iam workload-identity-pools create-cred-config 生成应用默认凭据文件。

将联合身份添加为 v1beta 用户

在 v1beta API 中，此步骤中的 IAM 角色可让联合身份调用您的实例。如需在实例中以管理员、政策作者或签名者的身份执行操作，该身份还需要一个用户。实例通过将调用方的主账号与每个 User 的 principal 字段进行匹配来识别调用方。

对于员工身份联合身份，请将 principal 设置为该身份的主体主账号标识符：

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

将 SUBJECT_ID 替换为提供商映射到 google.subject 的值。根据第 1 步中的属性映射，它是用户 ID 令牌的 sub 声明。

设置 principal 时，请注意以下几点：

使用 principal:// 标识符，而不是 principalSet:// 标识符。用户是指一个人。群组和池标识符（例如 principalSet://.../group/mpc-signers）在 IAM 角色绑定中有效，但它们永远不会与调用方匹配，因此使用其中一个标识符创建的用户无法在实例中执行操作。
与主题完全匹配。实例会区分大小写地比较员工和工作负载主体，因此请复制 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 中指定的使用方项目。
解决方法：向使用方项目中的 principal:// 或 principalSet:// 成员授予 roles/serviceusage.serviceUsageConsumer 权限（请参阅第 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 角色。
解决方法：请让您的 Organization Policy Administrator 将您的员工池主账号集添加到使用方项目或组织中允许的政策成员网域，或者在 constraints/iam.allowedPolicyMemberDomains 允许您的员工池的项目中进行测试。

后续步骤

如需创建用户、团队、交易政策和密钥，以及使用联合身份对交易进行签名，请参阅多方计算用户指南。将每个 User 的主账号设置为将联合身份添加为 v1beta User 中所述的 principal:// 标识符。
用户指南使用 gcloud auth print-access-token 检索每个角色的访问令牌，该令牌使用 gcloud CLI 凭证，而不是应用默认凭据。使用 gcloud auth login --login-config 让每个联合用户登录，如第 3 步的选项 A 所示。
如需详细了解用户角色、IAM 权限和资源级条件，请参阅安全和授权。