员工身份联合的 SCIM 配置

如果您的身份提供方 (IdP) 支持跨网域身份管理系统 (SCIM)，您可以将其配置为在 Google Cloud中预配和管理用户及群组。

功能

员工身份联合 SCIM 支持提供以下功能：

  • 身份同步：将用户和群组从外部 IdP 同步到 Google Cloud ，以全面了解员工身份。
  • 声明的主要来源：为员工提供方启用 SCIM 后， Google Cloud 会将同步的 SCIM 用户和群组用作 IAM 政策评估的用户属性和群组成员资格的可信来源。
  • 身份自动补全：在 Gemini Enterprise 中授予访问权限和共享资源（例如 Notebooks 和代理）时，启用用户和群组自动补全功能。

注意事项

使用员工身份联合 SCIM 支持时，请注意以下事项：

  • 您必须先设置员工身份池和提供方，然后再配置 SCIM 租户。
  • 每个员工身份池仅支持一个 SCIM 租户，该租户与单个提供方相关联。您无法在同一身份池中的任何其他提供方上启用 SCIM 使用 (--scim-usage)。 如需在同一员工身份池中配置新的 SCIM 租户，您必须先删除现有租户。如需删除 SCIM 租户，请使用以下方法之一：
    • 软删除（默认）：删除 SCIM 租户会启动 30 天的软删除期。在此期间，租户处于隐藏状态，无法使用，并且您无法在同一员工身份池中创建新的 SCIM 租户。
    • 硬删除：如需永久且立即删除 SCIM 租户，请将 --hard-delete 标志与删除命令结合使用。此操作不可逆，可让您立即在同一员工身份池中创建新的 SCIM 租户，而无需等待 30 天的保留期限。或者，您可以创建新的员工身份池和新的 SCIM 租户，也可以使用之前未配置 SCIM 租户的员工身份池。
  • SCIM 使用模式 (--scim-usage)：
    • enabled-for-groups (Gemini Enterprise)：使用 SCIM 同步的群组进行 IAM 授权和政策评估。 用户属性继续从登录令牌中获取。仅评估 google.subject 和 google.group 映射。
    • enabled-for-users-groups (Looker)（预览版）：使用 SCIM 同步的用户和群组数据作为 IAM 授权和 OAuth 登录工作流的声明来源。评估 google.subject、google.group 和所有已配置的用户声明（例如 google.display_name、google.profile_photo、google.email、google.posix_username 和自定义 attribute.KEY）。
  • 互斥性：设置 --scim-usage=enabled-for-users-groups（预览版）与额外属性 (extra_attributes_oauth2_client) 和扩展属性 (extended_attributes_oauth2_client) 互斥。
  • 使用 SCIM 时，您需要在员工身份池提供方和 SCIM 租户中映射属性。google.subject 属性必须唯一引用相同的身份。您可以使用 --attribute-mapping 标志在 员工身份池提供方中指定 google.subject，并使用 --claim-mapping 标志在 SCIM 租户中指定。映射非唯一身份值可能会导致 Google Cloud 将不同的 IdP 身份视为同一身份。因此，授予一个用户或群组身份的访问权限可以扩展到其他身份，但撤消一个身份的访问权限可能不会撤消所有身份的访问权限。
  • 如果您在没有附加 SCIM 租户的情况下在提供方上启用 SCIM 使用，则登录尝试会失败，因为 Google Cloud 找不到该提供方的 SCIM 租户。
  • 强制执行唯一性：验证并强制执行 SCIM 租户中映射到 google.subject（用户）和 google.group（群组）的属性的唯一性。 Google Cloud 如果您的 IdP 提供的映射属性在同步期间导致 google.subject 或 google.group 的值重复，则配置会失败并显示 HTTP 409 Conflict 错误。如果映射的属性的计算结果为 null 或空值，则配置会失败并显示 HTTP 400 Bad Request 错误。
  • 属性大小限制：序列化映射的用户属性（不包括 google.group）的大小上限为 16 kB。如果映射的属性超出此限制，登录尝试将会失败。
  • SCIM 令牌限制：每个 SCIM 租户最多支持两个 SCIM 令牌（例如，为了支持零停机时间令牌轮换）。如果您已有两个令牌，请先删除一个现有令牌，然后再创建新令牌。
  • SCIM API (iamscim.googleapis.com) 受速率配额限制，该配额与标准 IAM 资源 API 配额不同。默认情况下，写入和读取请求的限制为每个组织每分钟每个 SCIM 租户 3,000 个请求。如需了解详情，请参阅配额和限制。

声明映射

配置 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 个字符。

基于提供方 SCIM 使用情况的行为 (--scim-usage)

SCIM 声明映射的评估取决于员工身份池提供方上配置的 --scim-usage 模式：

  • enabled-for-groups (Gemini Enterprise)：仅评估 google.subject 和 google.group 映射。--claim-mapping 中的任何其他用户声明映射都会被忽略。
  • enabled-for-users-groups (Looker)（预览版）：评估 google.subject、google.group 和所有已配置的用户声明（例如 google.display_name、google.profile_photo、google.email、google.posix_username 和自定义 attribute.<var>KEY</var>）。

主题一致性示例映射

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

Google 属性 员工身份池提供方映射 SCIM 租户映射 (SCIM)
google.subject assertion.oid (Entra ID) user.externalId
google.subject assertion.sub (Okta) user.externalId
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 协议端点：

  • /Users：管理用户资源。支持的操作：Create、Get、Update、Delete、Patch 和 Put。

  • /Groups：管理群组资源。支持的操作：Create、Get、Update、Delete 和 Patch。群组不支持 PUT 方法。

  • /Schemas：检索架构信息。

  • /ServiceProviderConfig：检索服务提供商配置。

不支持以下 SCIM 协议端点：

  • /Me

  • /Bulk

  • /Search

  • /ResourceTypes

限制

以下部分介绍了员工身份联合 SCIM 实现与 SCIM 规范（RFC 7643 和 7644）的限制和偏差。

协议功能限制

  • 过滤条件支持：使用 /Users 或 /Groups 端点列出用户或群组时，过滤表达式仅支持 eq（等于）运算符。您可以将多个 eq 过滤条件与 and 结合使用。不支持其他 SCIM 过滤条件运算符，例如 co（包含）或 sw（开头为）。

  • 分页：IAM SCIM API 不支持用于列出用户或群组的标准分页。

    • startIndex：此参数始终为 1。无论您为 startIndex 提供什么值，API 最多都会返回 100 个结果。

    • itemsPerPage：单个响应中返回的资源数上限为 100。

    • totalResults：API 不会返回匹配资源的实际总数。响应中的 totalResults 字段始终等于相应响应中返回的商品数量，最多为 100。

  • 获取群组和列出不含过滤条件的群组： GetGroup 和 ListGroups API 会返回一个空成员列表。如需检索特定群组的成员，请使用带有成员过滤条件的 ListGroups API。

  • 包含无效令牌的不合规 JSON 响应：包含无效 API 令牌的请求会从 Google Cloud返回 HTTP 401 状态代码。响应不是 SCIM 规范要求的有效 JSON。

SCIM 行为限制

  • 不可变标识符：映射到 google.subject 或 google.group 的 SCIM 属性的值在 Google Cloud中被视为不可变标识符。如果您需要更改这些值，必须从 IdP 中永久删除相应用户或群组，然后使用新值重新创建该用户或群组。

  • 唯一且非空的标识符： Google Cloud 强制要求映射到 SCIM 租户中的 google.subject 和 google.group 的值必须唯一。 同步映射的属性，导致 google.subject 或 google.group 的值重复，会失败并显示 HTTP 409 Conflict 错误。 如果映射的属性的求值结果为 null 或空，则会失败并显示 HTTP 400 Bad Request 错误。

  • 单一电子邮件地址要求：为确保 SCIM 同步成功，每位用户都必须拥有一个且仅一个类型为 work 的电子邮件地址。如果您的 IdP 发送多封电子邮件，或者提供的单封电子邮件不是 work 类型，则配置或更新将失败。

  • 不区分大小写的转换：SCIM 声明映射支持有限的通用表达式语言 (CEL) 转换。对于 user.userName 和 user.emails[0].value，仅支持 .lowerAscii() 进行不区分大小写的比较。

属性限制

以下部分介绍了用户、群组和企业用户架构扩展的属性支持。

用户属性

下表列出了用户属性及其在 Workforce Identity Federation 声明中的可用性：

属性 子属性 在 SCIM 配置中受支持 限制 在 --claim-mapping 中支持
userName 不适用 是 不适用 是
name formatted、familyName、givenName、middleName、honorificPrefix、honorificSuffix 是 不适用 是
displayName 不适用 是 不适用 是
nickName 不适用 是 不适用 是
profileUrl 不适用 是 不适用 是
title 不适用 是 不适用 是
userType 不适用 是 不适用 是
preferredLanguage 不适用 是 不适用 是
locale 不适用 是 不适用 是
timezone 不适用 是 不适用 是
active 不适用 是 不适用 是
password 不适用 否 不适用 否
emails display、type、value、primary 是 仅支持 work 电子邮件类型。 是
phoneNumbers display、type、value、primary 是 不适用 是
ims display、type、value 是 不适用 是
photos display、type、value 是 不适用 是
addresses formatted、streetAddress、locality、region、postalCode、country 是 不适用 是
groups 不适用 否 不适用 否
entitlements display、type、value 是 不适用 是
roles type，value 是 display 不受支持。 是
x509Certificates type，value 是 display 不受支持。 否

群组属性

下表列出了群组属性及其在 Workforce Identity Federation 声明中的可用性：

属性 支持的子属性 在 --claim-mapping 中受支持
displayName 不适用 是
externalId 不适用 是
members value、type、$ref、display 否

企业用户架构扩展属性

下表详细介绍了对企业用户架构扩展的支持：

属性 支持的子属性 在 --claim-mapping 中受支持
employeeNumber 不适用 是
costCenter 不适用 是
organization 不适用 是
division 不适用 是
department 不适用 是
manager value、$ref、displayName 是（$ref 仅在 SCIM 配置中受支持，在 --claim-mapping 中不受支持）

后续步骤