# 用户配置（SCIM）

> [!WARNING]
> 此功能包含在 Enterprise 和 Enterprise Plus 套餐中。

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

SCIM 的工作方式因 SSO 模型而异。有关详细对比，请参阅 [SSO 概述](./enterprise-sso#user-provisioning-scim)。

## 基础 SSO：基于邀请的预配

使用 [Basic SSO](./security-sso-basic)（企业版套餐），SCIM 可自动向您的组织发送对现有 Hugging Face 用户的**邀请**。

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

## 托管 SSO：完整生命周期配置

使用 [Managed SSO](./enterprise-advanced-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**选项卡将其与[资源组](./enterprise-resource-groups)关联。

### 将 SCIM 组关联到资源组

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

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

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

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

### 链接之后会发生什么

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

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

### SCIM 管理的资源组

与 SCIM 组关联的资源组被视为 **SCIM 管理**。IdP 是其常规用户的唯一可信数据源。因此：

- 对于普通用户，通过 Hub UI 或 API 进行的手动成员变更操作是**被阻止的**——任何尝试在 SCIM 管理的资源组中添加、移除普通用户或更改其角色的操作都会返回 `403` 错误。
- [服务账号](./enterprise-service-accounts)是例外：由于它们从不通过 SCIM 配置，您仍然可以在 SCIM 管理的资源组中手动添加、删除服务账号或更改其角色。
- 在由 SCIM 管理的资源组上，**无法启用**自动加入。若要重新启用自动加入，请先移除 SCIM 链接。

在资源组设置中，由 SCIM 管理的资源组会显示 **SCIM 已同步** 徽章，并且成员表单会注明只能手动添加或移除服务账户。

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

## 支持的用户属性

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

| 属性 | 描述 | 基本 SSO | 托管 SSO |
| --- | --- | --- | --- |
| `userName` | Hugging Face 用户名 | 只读 | 读取/写入 |
| `name.givenName` | 名字 | 只读 | 读取/写入 |
| `name.familyName` | 姓氏 | 只读 | 读取/写入 |
| `emails[type eq "work"].value` | 电子邮件地址 | 只读 | 读取/写入 |
| `externalId` | IdP 分配的标识符 | 读取/写入 | 读取/写入 |
| `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。我们为一些最流行的提供商提供了专门的指南：
- [如何配置 Microsoft Entra ID 的 SCIM](./security-sso-entra-id-scim)
- [如何配置 Okta 的 SCIM](./security-sso-okta-scim)