在 Okta 中配置 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. 在 Okta 中配置 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.displayName

     您在 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，请参阅群组。

在 Okta 中配置 SCIM

如需在 Okta 中配置 SCIM，请在现有 Okta 应用中执行以下操作：

1. 登录 Okta 管理控制台。
2. 依次前往应用 > 应用。

3. 选择或创建应用：

   • 如果您想选择现有应用，请执行以下操作：

     1. 点击您使用 Google Cloud 员工身份联合模板创建的应用的名称。

     2. 在常规标签页中，执行以下操作：

        1. 在应用设置窗格中，点击修改。
        2. 在租户字段中，输入从 gcloud CLI 获取的租户 ID。
        3. 点击完成。

   • 如果您想创建新应用，请执行以下操作：

     1. 点击浏览应用目录。
     2. 在搜索字段中，输入 Google Cloud Workforce Identity Federation，然后从结果中选择 Google Cloud Workforce Identity Federation集成。

     3. 点击添加集成。

        1. 在应用字段中，为应用输入一个名称。
        2. 在租户字段中，输入从 gcloud CLI 获取的租户 ID。
        3. 点击完成。

4. 在预配标签页中，执行以下操作：

   1. 在集成窗格中，点击修改。

      1. 在 API 令牌字段中，输入您从 Google Cloud获得的 SCIM 令牌。
      2. 如需确认 API 令牌是否有效，请点击测试凭据。
      3. 选择导入群组。
      4. 点击保存。

   2. 在向应用窗格中，点击修改。

      1. 选择创建用户、更新用户属性和停用用户。
      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) 中必须完全相同。下表显示了 Okta 的参考示例：

Google 属性	员工身份池提供方映射	SCIM 租户映射
google.subject	assertion.sub	user.externalId
google.subject	assertion.subject	user.userName
google.subject	assertion.subject.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.preferred_username	user.userName
google.subject	assertion.preferred_username.lowerAscii()	user.userName.lowerAscii()
google.subject	assertion.email	user.emails[0].value
google.subject	assertion.email.lowerAscii()	user.emails[0].value.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 产品支持员工身份联合
• 设置用户对控制台（联合）的访问权限