在 Microsoft Entra ID 中配置 SCIM

重要提示：SCIM 配置仅适用于 Gemini Enterprise 和 Looker（预览版）。

本文档介绍了如何在员工身份池中配置 SCIM 租户。如需详细了解 SCIM，请参阅为员工身份联合配置 SCIM。

每个员工身份池仅支持一个 SCIM 租户。如需在已有一个 SCIM 租户的身份池中配置新的 SCIM 租户，您必须先硬删除现有租户。

SCIM 租户的 --claim-mapping 标志只能包含特定的通用表达式语言 (CEL) 表达式。如需了解支持哪些表达式，请参阅声明映射。

确保您的 IdP 为映射到 google.subject 和 google.group 的属性提供唯一的非空值。同步重复值会失败并显示 HTTP 409 Conflict 错误，而同步 null 或空值会失败并显示 HTTP 400 Bad Request 错误。如需了解详情，请参阅 SCIM 支持。

如需配置跨网域身份管理系统 (SCIM)，请执行以下操作：

1. 在 Google Cloud中配置 SCIM 租户和令牌
2. 在 Microsoft Entra ID 中配置 SCIM
3. 更新提供方以启用 SCIM
4. 验证 SCIM 同步

在 Google Cloud中配置 SCIM 租户和令牌

如需在 Google Cloud中配置 SCIM 租户，请执行以下操作：

1. 创建 SCIM 租户。

       gcloud iam workforce-pools providers scim-tenants create SCIM_TENANT_ID \
           --workforce-pool="WORKFORCE_POOL_ID" \
           --provider="PROVIDER_ID" \
           --display-name="SCIM_TENANT_DISPLAY_NAME" \
           --description="SCIM_TENANT_DESCRIPTION" \
           --claim-mapping="CLAIM_MAPPING" \
           --location="global"
       

   请替换以下内容：

   • SCIM_TENANT_ID：SCIM 租户的 ID。
   • WORKFORCE_POOL_ID：您在本文档前面部分创建的员工池的 ID。
   • PROVIDER_ID：您在本文档前面部分创建的员工身份池提供方的 ID。
   • SCIM_TENANT_DISPLAY_NAME：SCIM 租户的显示名称。
   • SCIM_TENANT_DESCRIPTION：SCIM 租户的说明。
   • CLAIM_MAPPING：属性映射的逗号分隔列表。如需查看扩展的映射属性列表，请参阅声明映射。建议为 Gemini Enterprise 进行以下映射：

     google.subject=user.emails[0].value.lowerAscii(),google.group=group.externalId

     您在 SCIM 租户中映射的 google.subject 属性必须使用 --attribute-mapping 标志唯一引用在员工身份池提供方的 google.subject 属性中映射的相同身份。 创建 SCIM 租户后，您无法更新声明映射。如需替换，您可以硬删除 SCIM 租户，然后立即创建一个新的 SCIM 租户。如需详细了解使用 SCIM 的注意事项，请参阅 SCIM 支持。

2. 命令完成后，执行以下操作：

   1. 在输出的 baseUri 字段中，保存整个 URI，其格式为 https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID。您需要向 IdP 提供此 URI。
   2. 此外，从 URI 中，仅保存 SCIM_TENANT_UID。 您需要在本文档后面部分使用此 UID 为相应 SCIM 租户设置 IAM 允许政策。

3. 创建 SCIM 令牌：

       gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \
           --display-name DISPLAY_NAME \
           --scim-tenant SCIM_TENANT_ID \
           --workforce-pool WORKFORCE_POOL_ID \
           --provider PROVIDER_ID \
           --location global
       

   请替换以下内容：

   • SCIM_TOKEN_ID：SCIM 令牌的 ID
   • DISPLAY_NAME：SCIM 令牌的显示名称
   • WORKFORCE_POOL_ID：员工池的 ID
   • SCIM_TENANT_ID：SCIM 租户的 ID
   • PROVIDER_ID：员工身份池提供方的 ID

4. gcloud iam workforce-pools providers scim-tenants tokens create 命令完成后，执行以下操作：

   1. 在输出中，保存 securityToken 字段中 SCIM_TOKEN 的值。您需要向 IdP 提供此安全令牌。安全令牌仅在此输出中显示，如果丢失，您必须创建新的 SCIM 令牌。

   2. 如需检查 SCIM_TOKEN 是否因组织政策而被拒绝，请运行以下命令：

      curl -v -H "Authorization: Bearer SCIM_TOKEN"  https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users

      如果该命令因权限相关错误而失败，请运行 gcloud organizations add-iam-policy-binding，如后续步骤中所述。如果该命令成功执行，则可以跳过该步骤。

5. 为 SCIM 租户和令牌设置 IAM 允许政策。如果上一步中的 curl 命令因权限相关错误而失败，则必须运行以下命令：

       gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
           --member=serviceAccount:SERVICE_AGENT_EMAIL \
           --role roles/iam.scimSyncer
       

   请替换以下内容：

   • ORGANIZATION_ID：组织的 ID。
   • SERVICE_AGENT_EMAIL：服务代理的邮箱。该邮箱的格式如下：o-ORGANIZATION_ID-SCIM_TENANT_UID@gcp-sa-iamscim.。创建 SCIM 租户时，系统会返回 SCIM_TENANT_UID。

在 IdP 中配置群组时，确保每个群组的显示名称（在 displayName 字段中提供）在 SCIM 租户中都是唯一的。如需详细了解 Microsoft Entra ID 中的群组和 SCIM，请参阅群组。

在 Microsoft Entra ID 中配置 SCIM

如需在 Microsoft Entra ID 中配置 SCIM，请执行以下操作：

1. 打开 Azure 门户，并以具有全局管理员权限的用户身份登录。
2. 依次选择 Microsoft Entra ID > 企业应用。
3. 点击新建应用。
4. 在浏览 Microsoft Entra 应用库中，点击创建您自己的应用。
5. 在随即显示的创建您自己的应用面板中，执行以下操作：
   1. 在应用名称是什么字段中，输入应用的名称。
   2. 选择集成您在图库中找不到的任何其他应用（非图库）。
   3. 如需创建应用，请点击创建。
6. 在您的应用中，执行以下操作：
   1. 在管理部分中，点击预配。
   2. 在随即显示的右侧窗格中，点击新配置。

   3. 在管理员凭证下的租户网址中，输入您在创建 SCIM 租户时获得的 SCIM 网址，并在末尾添加 ?aadOptscim062020。 您必须在基本 URI 的末尾附加 ?aadOptscim062020。

      Microsoft Entra ID 需要此查询参数，以确保 SCIM PATCH 请求符合 SCIM RFC 标准。如需了解详情，请参阅 Microsoft 的文档。

      Microsoft Entra ID 中的最终租户网址应采用以下格式：

      https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020

      将 SCIM_TENANT_UID 替换为 SCIM 租户 UID。

   4. 在 Secret 令牌中，输入您在创建 SCIM 令牌时获得的 Secret 令牌。
   5. 如需使用员工身份联合测试 SCIM 配置，请点击测试连接。
   6. 如需保存配置，请点击创建。
7. 在管理部分中，执行以下操作：
   1. 点击属性映射。
   2. 点击预配 Microsoft Entra ID 用户。
   3. 在属性映射页面中，执行以下操作：
      1. 在属性映射表中，找到 externalId 所在的行，然后点击该行中的修改。 在修改属性页面中，执行以下操作：
         1. 在来源属性下拉列表中，选择 objectId。
         2. 点击确定。
      2. 如需保存属性映射，请点击保存。

更新提供方以启用 SCIM

如需为提供方启用 SCIM，请根据产品目标设置 --scim-usage 标志：

• 已为群组启用 (enabled-for-groups)：用于 Gemini Enterprise。使用 SCIM 同步的群组进行 IAM 授权和政策评估。用户属性继续从 IdP 登录令牌获取。
• 已为用户和群组启用 (enabled-for-users-groups)：用于 Looker（预览版）。使用 SCIM 同步的用户和群组数据作为 IAM 授权和 OAuth 登录工作流的声明的主要来源。

为群组启用 SCIM (Gemini Enterprise)

OIDC

      gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-groups
    

请替换以下内容：

• PROVIDER_ID：员工身份池提供方的 ID
• WORKFORCE_POOL_ID：员工池的 ID
• LOCATION：员工池的位置

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-groups
    

请替换以下内容：

• PROVIDER_ID：员工身份池提供方的 ID
• WORKFORCE_POOL_ID：员工池的 ID
• LOCATION：员工池的位置

为用户和群组启用 SCIM (Looker)（预览版）

OIDC

      gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-users-groups
    

请替换以下内容：

• PROVIDER_ID：员工身份池提供方的 ID
• WORKFORCE_POOL_ID：员工池的 ID
• LOCATION：员工池的位置

SAML

      gcloud iam workforce-pools providers update-saml PROVIDER_ID \
          --workforce-pool=WORKFORCE_POOL_ID \
          --location=LOCATION \
          --scim-usage=enabled-for-users-groups
    

请替换以下内容：

• PROVIDER_ID：员工身份池提供方的 ID
• WORKFORCE_POOL_ID：员工池的 ID
• LOCATION：员工池的位置

如需验证 SCIM 同步，请参阅验证 SCIM 同步。

声明映射

配置 SCIM 时，您需要在 SCIM 租户中定义声明映射 (--claim-mapping)，以将 SCIM 用户和群组属性映射到 Google 属性。

支持用于声明映射的 Google Cloud 属性

下表列出了您可以使用通用表达式语言 (CEL) 在 SCIM 租户 (--claim-mapping) 中映射的 Google Cloud 属性：

Google Cloud 属性	要求	说明	支持的表达式和限制
google.subject	必填	进行身份验证的用户的唯一标识符。 用于填充 google.subject 的底层 IdP 属性在提供方映射 (--attribute-mapping) 和 SCIM 租户 (--claim-mapping) 中必须完全相同。如果这些映射不一致，用户可能能够登录，但不会被识别为 SCIM 预配的群组的成员。	仅限以下基本表达式（或使用 .lowerAscii()）： user.externalId user.userName user.emails[0].value 长度上限：127 字节。 注意：SCIM 租户创建后，此映射便无法更改；如需更新，您必须硬删除并重新创建 SCIM 租户。
google.group	对于 SCIM 群组，此字段为必需字段	使用 SCIM 同步的群组成员资格的唯一标识符。	仅限以下基本表达式（或使用 .lowerAscii()）： group.externalId group.displayName 注意：SCIM 租户创建后，此映射便无法更改；如需更新，您必须硬删除并重新创建 SCIM 租户。
google.display_name	可选	用于在 Google Cloud 控制台中设置所登录用户的名称的属性。不能用于 IAM 允许政策。	映射到字符串属性（例如 user.displayName 或 user.name.formatted）。长度上限：100 字节。
google.profile_photo	可选	用户的缩略照片的网址，该照片会在 Google Cloud 控制台中显示为用户的个人资料照片。不能用于 IAM 允许政策。	必须计算为有效的网址字符串（例如 user.photos.filter(p, p.type == 'thumbnail')[0].value 或 user.photos[0].value）。
google.email	可选	一种属性，用于将电子邮件地址从 IdP 映射到使用员工身份联合 OAuth 客户端集成进行集成的产品。不能用于 IAM 允许政策。	映射到电子邮件属性（例如 user.emails.filter(e, e.type == 'work')[0].value 或 user.emails[0].value）。
google.posix_username	可选	符合 POSIX 标准的唯一用户名字符串，用于 SSH-in-browser 和使用员工身份联合的 OS Login。此属性不能用于 IAM 允许政策。	最大长度为 32 个字符。
attribute.KEY	可选	IdP 中的自定义属性，可用于在 IAM 允许政策中定义授权策略。将 KEY 替换为您要使用的属性名称。 例如，您可以定义一个自定义属性（例如 costcenter = "1234"），然后使用 principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234 引用该属性。向此主账号标识符授予访问权限后，在 IdP 中配置为具有该成本中心的所有身份都有权访问。	最多 50 个自定义属性映射规则。每条规则的大小上限：256 个字符。

主题一致性示例映射

如声明映射支持的属性中所述，用于填充 google.subject 的底层 IdP 属性在提供方映射 (--attribute-mapping) 和 SCIM 租户 (--claim-mapping) 中必须完全相同。下表显示了 Microsoft Entra ID 的参考示例：

Google 属性	员工身份池提供方映射	SCIM 租户映射
google.subject	assertion.oid	user.externalId
google.subject	assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'][0]	user.externalId
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0]	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'][0].lowerAscii()	user.emails[0].value.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0].lowerAscii()	user.userName.lowerAscii()

验证 SCIM 同步

重要提示：由于 SCIM 是从您的 IdP 进行推送的，因此 Google Cloud 不会主动拉取数据或检查连接健康状况。如果 IdP 与 Google Cloud 之间的连接无提示中断，身份数据可能会过时。

在最长持续时间为 90 天的延长会话时长 (ESL) 工作流中，已停用的用户可能会保留访问权限，直到下次成功同步或会话过期为止。为防止未经授权的访问，请持续监控和审核 SCIM 同步运行状况。

配置 SCIM 后，您可以使用 curl 验证用户和群组是否正确同步到 Google Cloud。这些命令需要有效的 SCIM 令牌和您的 SCIM 租户 ID。

验证用户同步

如需验证用户是否已正确同步，请使用以下过滤条件搜索用户的 userName：

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users?filter=userName%20eq%20%22USER_NAME%22"

示例响应：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "USER_ID",
      "userName": "USER_NAME",
      ...
    }
  ]
}

验证群组同步

如需验证群组是否已正确同步，请使用以下过滤条件搜索群组的 displayName：

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=displayName%20eq%20%22GROUP_NAME%22"

示例响应：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

验证群组成员资格

如需验证特定用户是否是某个群组的成员，请使用同时指定群组 ID 和用户 ID 的过滤条件。

curl -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups?filter=id%20eq%20%22GROUP_ID%22%20and%20members%20eq%20%22USER_ID%22"

如果用户是会员，则响应示例：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "id": "GROUP_ID",
      "displayName": "GROUP_NAME",
      ...
    }
  ]
}

如果用户不是会员，则返回的响应示例：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 0,
  "Resources": []
}

注意：如需获取 GROUP_ID 和 USER_ID，请先使用 displayName 和 userName 过滤条件找到群组和用户。这些 ID 会在响应的 id 字段中返回。将 SCIM_TOKEN、SCIM_TENANT_UID、USER_NAME、GROUP_NAME、GROUP_ID 和 USER_ID 替换为您的实际值。

强制删除 SCIM 租户

如需强制删除 SCIM 租户，请执行以下操作：

1. 如果您的提供商设置了 --scim-usage=enabled-for-groups 或 --scim-usage=enabled-for-users-groups，请从提供商配置中将其停用：

             gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
                 --workforce-pool=WORKFORCE_POOL_ID \
                 --location=LOCATION \
                 --scim-usage=SCIM_USAGE_UNSPECIFIED
           

   请替换以下内容：

   • PROVIDER_ID：员工身份池提供方的 ID
   • WORKFORCE_POOL_ID：员工池的 ID
   • LOCATION：员工池的位置

2. 删除 SCIM 租户：

     gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \
         --workforce-pool=WORKFORCE_POOL_ID \
         --provider=PROVIDER_ID \
         --hard-delete \
         --location=global
   

   请替换以下内容：

   • SCIM_TENANT_ID：要删除的 SCIM 租户的 ID
   • WORKFORCE_POOL_ID：员工池的 ID
   • PROVIDER_ID：员工身份池提供方的 ID
   如需详细了解 SCIM（包括删除 SCIM 租户），请参阅 SCIM 支持。

后续步骤

• 排查 SCIM 配置问题
• 删除员工身份联合用户及其数据
• 了解哪些 Google Cloud 产品支持员工身份联合
• 设置用户对控制台（联合）的访问权限