员工身份联合的 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(Gemini Enterprise 和 Looker):在 Web 登录和 OAuth 登录工作流中,使用通过 SCIM 同步的用户和群组数据作为 IAM 授权的声明来源。评估 google.subject、google.group 和所有已配置的用户声明(例如 google.display_name、google.profile_photo、google.email、google.posix_username 和自定义 attribute.<var>KEY</var>)。
  • 互斥性:设置 --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 租户。
  • 唯一性强制执行: Google Cloud 会验证并强制执行 SCIM 租户中映射到 google.subject(用户)和 google.group(群组)的属性的唯一性。如果您的 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(Gemini Enterprise 和 Looker):评估 google.subject、google.group 和所有已配置的用户声明(例如 google.display_name、google.profile_photo、google.email、google.posix_username 和自定义 attribute.<var>KEY</var>)。 Google Cloud 在以下登录工作流中使用 SCIM 声明:
    • Web 登录:当用户登录 Gemini Enterprise 时, Google Cloud 会使用通过 SCIM 同步的用户和群组声明。当用户登录其他产品(例如 Google Cloud 控制台)时, Google Cloud 会使用提供方的 --attribute-mapping 标志从 IdP 令牌映射的特性。
    • OAuth 登录:当用户登录使用员工身份联合 OAuth 流程的 Gemini Enterprise 和 Looker 应用时, Google Cloud 会使用 SCIM 同步的用户和群组声明。当用户登录其他应用时, Google Cloud 会使用提供商的 --attribute-mapping 标志从 IdP 令牌映射的属性。

用于确保主体一致性的映射示例

如支持声明映射的属性中所述,用于填充 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()

支持的端点和不支持的端点

IAM SCIM 服务 (iamscim.googleapis.com) 实现了 SCIM 2.0 协议 (RFC 7644),并在 SCIM 租户的 baseUri 处处理请求:

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

在此 URI 中,SCIM_TENANT_UID 是 SCIM 租户的唯一标识符。

IAM SCIM 服务支持以下相对于租户 baseUri 的标准 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() 进行不区分大小写的比较。

属性限制

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

用户属性

下表列出了用户属性及其在员工身份联合声明中的可用性:

属性 子属性 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 不受支持。 否

群组属性

下表列出了群组属性及其在员工身份联合声明中的可用性:

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

企业用户架构扩展属性

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

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

后续步骤