如何配置 SCIM 以配合 Microsoft Entra ID (Azure AD)

本指南介绍如何使用 SCIM 在 Microsoft Entra ID 与您的 Hugging Face 组织之间设置自动用户和组配置。

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

SCIM 要求您的组织先配置 SSO。基础 SSO 可自助配置，托管 SSO 需由 Hugging Face 团队协助配置。

步骤 1：从 Hugging Face 获取 SCIM 配置

1. 登录一个拥有该组织所有权的 Hugging Face 账户。
2. 在 Hugging Face 上导航至您组织的设置页面。
3. 前往 SSO 选项卡，然后单击 SCIM 子选项卡。
4. 复制 SCIM Tenant URL。在配置 Entra ID 时需要用到此 URL。
5. 点击 生成访问令牌。系统将生成一个新的 SCIM 令牌。请立即复制此令牌并妥善保存，因为您将无法再次查看它。

步骤 2：在 Microsoft Entra ID 中配置预配

1. 在 Microsoft Entra 管理中心中，导航至您的 Hugging Face 企业应用程序。
2. 在左侧菜单中，选择 Provisioning。
3. 点击 开始使用。
4. 将 Provisioning Mode 从“Manual”更改为 Automatic。

步骤 3：输入管理员凭据

1. 在 Admin Credentials 部分，将 Hugging Face 中的 SCIM Tenant URL 粘贴到 Tenant URL 字段中。
2. 将 Hugging Face 的 SCIM token 粘贴到 Secret Token 字段中。
3. 点击 Test Connection。您应该会看到成功通知。
4. 点击 保存。

步骤 4：配置属性映射

1. 在 Mappings 部分下，点击 Provision Microsoft Entra ID Users。

2. 默认的属性映射通常需要进行调整，以实现稳健的配置。我们建议使用以下配置。您可以删除此处未列出的属性：

   customappsso 属性	Microsoft Entra ID 属性	匹配优先级
   userName	Replace([mailNickname], ".", "", "", "", "", "")
   active	Switch([IsSoftDeleted], , "False", "True", "True", "False")
   emails[type eq "work"].value	userPrincipalName
   name.givenName	givenName
   name.familyName	surname
   externalId	objectId	1

3. 用户名需要符合以下规则。

• 用户名仅接受常规字符和 -。
• --（双破折号）是被禁止的。
• - 不能位于名称的开头或结尾。
• 不接受仅包含数字的名称。
• 最小长度为 2，最大长度为 42。
• 用户名在您的组织中必须是唯一的。

4. 配置完用户映射后，返回 Provisioning 屏幕并点击 Provision Microsoft Entra ID Groups 以查看组映射。组的默认设置通常已足够。

步骤 5：开始配置

1. 在主配置屏幕上，将配置状态设置为开启。
2. 在 设置 中，您可以将 范围 配置为“仅同步已分配的用户和组”或“同步所有用户和组”。我们建议从“仅同步已分配的用户和组”开始。
3. 保存您的更改。

初始同步可能需要长达 40 分钟才能开始。您可以在 Provisioning logs 选项卡中监控进度。

为配置分配用户和组

要控制哪些用户和组被配置到您的 Hugging Face 组织中，您需要将它们分配到 Microsoft Entra ID 中的 Hugging Face Enterprise Application。此操作在您的应用程序的 Users and groups 选项卡中完成。

1. 在 Microsoft Entra 管理中心中，导航至您的 Hugging Face Enterprise Application。
2. 前往 Users and groups 选项卡。
3. 点击 添加用户/组。
4. 选择要配置的用户和组，然后单击 分配。

如果您已将 Scope 设置为“仅同步已分配的用户和组”，则只有您在此处分配的用户和组才会被配置到 Hugging Face。

Active Directory 方案考量

• 使用 Free、Office 365 和 Premium P1/P2 计划，您可以将单个用户分配给该应用程序以进行配置。
• 使用 Premium P1/P2 计划，您还可以分配组。这是大规模管理访问权限的推荐方法，因为您可以在 AD 中管理组成员身份，并且更改会自动反映在 Hugging Face 中。

步骤 6：在 Hugging Face 中验证配置

同步完成后，返回您的 Hugging Face 组织设置：

• 预配的用户将显示在 用户管理 选项卡中。
• 预置组将显示在 SCIM Groups 下的 SCIM 选项卡中。随后，可以将这些组分配给 Resource Groups，以实现细粒度的访问控制。

步骤 7：将 SCIM 组链接到 Hugging Face 资源组

当您的组从 Entra ID 配置完成后，您可以将它们与 Hugging Face Resource Groups 关联，以便大规模管理权限。这使得 SCIM 组的所有成员都能自动获得一组资源的具体角色（例如读取或写入）。

在关联之前，请确保要关联的资源组是空的（没有现有成员），并且未启用自动加入。这两个条件都是必需的，否则关联将会失败。

1. 在您的 Hugging Face 组织设置中，导航至 SSO -> SCIM 选项卡。您将在 SCIM Groups 下看到已配置组的列表。

2. 找到要配置的组，并点击其所在行中的 Link resource groups。
3. 将显示一个对话框。单击 关联资源组。
4. 从下拉菜单中，选择要链接的 资源组 以及要授予 SCIM 组成员的 角色分配。
5. 单击 SCIM 组链接 并保存映射。

完成关联后，资源组将变为SCIM 管理：SCIM 组中已有的成员会立即被添加到资源组（回填），并且 Entra ID 中后续的所有成员变更都会自动同步。通过 Hub UI 或 API 对资源组进行的手动成员编辑将被阻止。

Update on GitHub