如果您的身份提供方 (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出现重复值,则预配会失败,并显示 HTTP409 Conflict错误。如果映射的属性计算结果为 null 或空,则预配会失败,并显示 HTTP400 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 |
必填 |
进行身份验证的用户的唯一标识符。 用于填充 |
仅限以下基本表达式(或使用 .lowerAscii()):
长度上限:127 字节。 注意:SCIM 租户创建后,此映射便不可变;如需更新,您必须硬删除并重新创建 SCIM 租户。 |
google.group |
SCIM 群组必须提供 | 使用 SCIM 同步的群组成员资格的唯一标识符。 | 仅限以下基本表达式(或使用 .lowerAscii()):
注意: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 替换为您要使用的属性名称。 例如,您可以定义一个自定义属性(如 |
最多 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 令牌映射的属性。
- Web 登录:当用户登录 Gemini Enterprise 时, Google Cloud 会使用通过 SCIM 同步的用户和群组声明。当用户登录其他产品(例如 Google Cloud 控制台)时, Google Cloud 会使用提供方的
用于确保主体一致性的映射示例
如支持声明映射的属性中所述,用于填充 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和ListGroupsAPI 会返回空成员列表。如需检索特定群组的成员,请使用ListGroupsAPI 并添加成员过滤条件。包含无效令牌的不合规 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的值重复,并失败,并显示 HTTP409 Conflict错误。计算结果为 null 或空的映射属性会失败,并显示 HTTP400 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 中不支持) |