Hub documentation

用户配置(SCIM)

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

用户配置(SCIM)

此功能包含在 Enterprise 和 Enterprise Plus 套餐中。

SCIM(跨域身份管理系统)是一种用于自动化用户配置的标准。它允许您将身份提供商(IdP)连接到 Hugging Face,以管理您组织的成员。

SCIM 的工作方式因 SSO 模型而异。有关详细对比,请参阅 SSO 概述。

基础 SSO:基于邀请的预配

使用 Basic SSO(企业版套餐),SCIM 可自动向您的组织发送对现有 Hugging Face 用户的邀请。

  • 用户必须已经拥有 Hugging Face 账户,才能通过 SCIM 进行配置
  • 当您的 IdP 配置用户时,Hugging Face 会向他们发送一封邀请邮件,邀请其加入该组织
  • 用户必须接受邀请才能成为成员——预配置不会立即授予访问权限
  • SCIM 无法修改用户个人资料信息(姓名、电子邮件、用户名)——用户对其 Hugging Face 账户拥有完全的控制权
  • 当用户在您的 IdP 中被取消配置时,其邀请将被停用,并且其对组织的访问权限将被撤销

托管 SSO:完整生命周期配置

使用 Managed SSO(Enterprise Plus 套餐),SCIM 可管理 Hugging Face 上的整个用户生命周期。

  • SCIM 在配置用户时创建一个新的 Hugging Face 账户——无需预先存在的账户
  • 用户会立即作为成员被添加到该组织中,无需经过邀请步骤
  • SCIM 可以更新用户配置文件信息(姓名、电子邮件、用户名),以反映 IdP 中发生的变更
  • 当用户在您的 IdP 中被取消配置时,其 Hugging Face 账户将被停用,并且其访问权限将被撤销

如何启用 SCIM

要启用 SCIM,请前往您的组织设置,导航至 SSO 选项卡,然后选择 SCIM 子选项卡。

您会找到 SCIM 租户 URL 以及一个用于生成 SCIM 令牌 的按钮。配置您的 IdP 时需要用到这两项。SCIM 令牌属于机密信息,应安全地存储在您的 IdP 配置中。

在您的 IdP 中启用 SCIM 后,已配置的用户将显示在组织设置的 Users Management 选项卡中,已配置的组将显示在 SCIM 选项卡中。

组配置

除了用户配置外,SCIM 还支持组配置。从您的 IdP 推送的组将作为 SCIM 组存储在 Hugging Face 上,并可以通过组织设置中的SCIM选项卡将其与资源组关联。

将 SCIM 组关联到资源组

要将 SCIM 组关联起来,请前往您组织的 SSO → SCIM 选项卡。已预配的组会列在表格中。在 Resource Groups 列中,每个组会显示一个 Link resource groups 按钮(如果尚未建立关联),或者当前已关联的资源组数量(例如“2 resource groups”)。点击其中任意一项都会打开一个模态框,您可以在其中添加一个或多个 Resource Groups,并为每个组分配各自的角色。您也可以从同一个模态框中修改或移除现有的关联。

在建立链接之前,请确保满足以下条件:

  • 资源组必须没有现有成员。不允许链接到非空的资源组。
  • 资源组必须未启用自动加入。自动加入(会自动将每个新组织成员添加到资源组)与 SCIM 管理互斥。在关联之前,请先在资源组上禁用自动加入。

SCIM 组可以关联到多个资源组,每个资源组拥有各自的角色。

链接之后会发生什么

SCIM 组与资源组建立关联后:

  • 回填:SCIM 组中已有的成员会立即以配置的角色添加到资源组中。
  • Ongoing sync: IdP 中的成员变更会自动同步:
    • 当用户被添加到 IdP 中的组时,他们将被添加到所有关联的资源组中。
    • 当用户从您的 IdP 中的组中移除时,该用户将从所有关联的资源组中移除,但通过其他 SCIM 组关联的资源组除外。对于这些资源组,用户的角色将更新为其他 SCIM 组授予的“最高”角色。
    • 当 IdP 中的 SCIM 组被删除时,其所有成员都将从关联的 Resource Groups 中移除,但通过其他 SCIM 组属于这些 Resource Groups 的用户除外。对于这些 Resource Groups,用户的角色将更新为其他 SCIM 组授予的“最高”角色。
  • 角色变更:如果您更新了链接上的角色,该资源组中所有当前成员的角色都会立即更新,但角色被手动更改的成员除外。

SCIM 管理的资源组

与 SCIM 组关联的资源组被视为 SCIM 管理。身份提供商(IdP)是其成员身份的唯一可信来源。因此:

  • 通过 Hub UI 或 API 手动添加或移除成员的操作是被阻止的:任何尝试都会返回403错误。
  • 角色仍可按成员进行更改。当 SCIM 链接上的角色更新时,手动更改的角色会被保留,并可通过成员操作中的 重置为 SCIM 角色(或 API 中的 resetToScimRole)进行恢复。
  • 在由 SCIM 管理的资源组上,无法启用自动加入。若要重新启用自动加入,请先移除 SCIM 链接。

在资源组设置中,由 SCIM 管理的资源组会显示 SCIM 已同步 徽章,添加用户 操作处于禁用状态,并且角色被手动更改的成员会显示一个信息图标。

Group provisioning 在 Basic SSO 和 Managed SSO 中的工作方式相同。

支持的用户属性

Hugging Face SCIM 端点支持以下用户属性:

属性描述基本 SSO托管 SSO
userNameHugging Face 用户名只读读取/写入
name.givenName名字只读读取/写入
name.familyName姓氏只读读取/写入
emails[type eq "work"].value电子邮件地址只读读取/写入
externalIdIdP 分配的标识符读取/写入读取/写入
active用户是否为活跃成员读取/写入读取/写入

在基本 SSO 中,仅能通过 SCIM 修改 active 和 externalId — 所有其他属性均由用户在他们的 Hugging Face 账户中控制。

对于组配置,支持的属性为 displayName、members 和 externalId。

取消配置

Deprovisioning 行为取决于用户被移除的方式以及所使用的 SSO 模型。

将 active 设置为 false(软取消配置):

  • 用户将失去对该组织的访问权限
  • 使用基本 SSO:该邀请将被停用
  • 使用托管 SSO:用户将从组织中移除,但其账户和内容会保留——通过将 active 重新设置为 true 即可撤销此操作

通过 SCIM 删除用户(硬性取消配置):

  • 使用基本 SSO:该用户将从组织及其所有资源组中移除。他们的 Hugging Face 账户和个人内容不受影响——他们只是失去了您组织的成员身份。
  • 使用托管 SSO:用户的 Hugging Face 账户将被永久删除,其创建的所有内容也将一并删除。此操作不可逆。

支持的Identity Providers

我们支持任何实现了 SCIM 2.0 协议的 IdP 使用 SCIM。我们为一些最流行的提供商提供了专门的指南:

Update on GitHub