迁移到托管 SSO

此功能属于 Enterprise Plus 套餐的一部分。

本指南面向正在将现有组织从标准组织转换为 Managed SSO 组织的组织管理员。

开始之前，最重要的一点是：成员现有的个人 Hugging Face 账户不会被转换为托管账户。每位成员都会获得一个全新的托管账户，由您的身份提供商（IdP）进行配置。在成员被配置之前，他们必须在其个人账户上释放其工作邮箱地址。

在本指南中，我们使用 my-org 作为示例组织名称。

先决条件

SSO 必须已在您的组织上完成配置、测试并启用。迁移过程将复用您现有的 OIDC 或 SAML 应用程序。

迁移步骤

1. 准备您的成员。 与您的成员一起查看迁移前检查清单。
2. 联系 Hugging Face。 与 Hugging Face 团队取得联系并确认切换。我们将转换该组织，并向您发送 my-org:owner 紧急恢复账户的凭据。
3. 请成员释放其工作邮箱。参见 释放工作邮箱地址。请在启用配置之前执行此操作：已分配给你的 SSO 应用的用户会在 SCIM 开启后立即被配置。Hugging Face 团队可以向你发送仍使用工作邮箱的个人账户成员列表，以便你与他们跟进。
4. Set up SCIM in your IdP. 使用您组织的 SSO → SCIM 设置中的 SCIM 租户 URL 和令牌，在现有的 OIDC 或 SAML 应用中配置，然后按照您的 IdP 指南操作。
   • Okta：请遵循 Okta 指南，包括 步骤 3。Name ID 必须是 Okta 用户 ID。
   • Microsoft Entra ID：请遵循 Entra ID 指南。userName 必须符合 用户名规则，因此像 jdoe@example.com 这样的邮箱格式值会被拒绝。
   • 其他 IdP：请参阅 用户配置（SCIM），用户名规则相同。
5. 在您的 IdP 中分配用户和组。 在配置用户时，会创建托管账户。
6. 在每个成员的托管账户配置完成后，尽快从组织中移除遗留的个人账户。出于安全考虑，此步骤是必需的，因为个人账户在被移除之前仍保留访问权限。移除这些账户也会将它们从组织的资源组中移除。
7. （可选）将组映射到资源组和角色。 将您的 SCIM 组链接到资源组，并设置 角色映射 以从您的 IdP 分配组织角色。只有当资源组没有成员且自动加入功能已关闭时，才能将其链接到 SCIM 组。如果自动加入功能处于开启状态，新预配的管理账户也会被添加到该组中，因此请在预配用户之前关闭该功能，或在链接之前移除所有剩余成员。

有哪些更改

转换的作用

• 转换由 Hugging Face 团队完成。没有自助切换选项。一旦您提交请求，Hugging Face 团队就会将您的组织切换到托管模式。
• 您组织的内容和配置将保持不变。 仓库、设置、Resource Groups 以及现有的 SSO 配置（OIDC 或 SAML 应用）都会保留。您将继续使用相同的 IdP 应用，但某些设置可能需要针对 SCIM 进行调整（参见 步骤 4）。
• 会创建一个紧急管理账户，名称为 my-org:owner。该账户通过用户名和密码登录（而非通过 SSO），并且是组织的管理员。Hugging Face 团队会将该账户的凭据共享给您。请妥善保存这些凭据：当您的 IdP 不可用或配置错误时，您可以使用此账户访问您的组织。
• SSO 不再可以设为可选。 但仍可以完全禁用。

在托管组织上禁用 SSO 会导致所有托管用户被锁定，因为托管账户没有密码。

托管账户是新账户

• 现有的个人 Hugging Face 账户不会被转换、合并或关联到托管账户中。当用户在 IdP 中被分配时，您的 IdP 会通过 SCIM 为每位成员创建一个新账户。
• 托管的用户名以组织名称为前缀：<org-name>:<username>，例如 my-org:jdoe。
• 仅托管用户通过您的 IdP 登录。他们没有 Hugging Face 密码，且“忘记密码”功能对他们无效。
• 托管账户受托管账户限制的约束。

会员

• 常规成员无法再通过邀请添加。内部成员必须通过 SCIM 进行配置。
• 邀请仅面向外部协作者开放。

组织中的现有个人账户

在转换后仍保留组织成员身份的个人账户将保留其角色。他们的访问令牌、已授权的 OAuth 应用以及通过 SSH 进行的 git 操作将继续正常工作，因为这些不会针对 SSO 进行检查。他们无法再对该组织发起新的 SSO 登录：

• 如果用户使用其个人账户登录，或者该账户已关联到您的 IdP，他们将看到：You cannot login with SSO with this account because it's not managed by this organization. Contact your organization administrators.
• 否则，他们会看到 User not found。

迁移之前

在请求转换之前，请与团队成员一起检查以下清单：

• 个人仓库：希望在切换到新托管账户后仍能访问其个人命名空间中的仓库的成员，应在切换前将这些仓库转移到组织中。托管账户无法拥有个人命名空间中的内容。成员仍可通过其个人（非托管）账户访问其个人命名空间下的任何仓库。
• 令牌与自动化：来自个人账户的令牌在账户从组织中移除之前，将保留对该组织的访问权限。请将脚本、CI 作业和流水线迁移到 服务账户，或迁移到切换后从托管账户创建的令牌，然后移除旧账户。
• 其他组织：托管账户无法加入其他组织。需要在其他组织中继续工作的成员应保留一个独立的个人账户（参见下文选项 2）。
• 工作邮箱地址：在配置之前，每位成员都必须释放其工作邮箱。请参阅 释放工作邮箱地址。

释放工作邮箱地址

一个电子邮件地址只能属于一个 Hugging Face 账户。这适用于账户的所有电子邮件地址，包括主要和次要地址。匹配时不区分大小写。

当 SCIM 尝试使用已被个人账号占用的工作邮箱来创建托管账号时，配置过程会因 409 错误而失败：

The email address (jdoe@example.com) is already associated with another Hugging Face account. Please delete the account.

您的 IdP 会将此显示为该用户的配置错误。

为避免此问题，每位成员在配置之前，必须使用以下两种选项之一释放其工作邮箱地址 之前。

我应该选择哪个选项？

• 如果你仅使用你的 Hugging Face 账户在此组织中工作，请选择 选项 1：删除个人账户。
• 如果您还将其用于开源工作、个人项目或其他组织，请选择选项 2：保留个人账户，并从中移除工作邮箱。

选项 1：删除个人账户

从您的账户设置中删除您的个人账户。这将永久删除您个人命名空间中的所有仓库，并将您从所有组织中移除。

删除账户是永久性的操作。请先将需要保留的仓库转移到组织中。

如果您只是另一个组织的唯一管理员，则删除操作会被阻止。请先为该组织添加其他管理员，或先删除该组织。正在迁移的组织不会有问题，因为 my-org:owner 也是管理员。

选项 2：保留个人账户

1. 在您的账户设置中，添加一个个人电子邮件地址并进行验证。
2. 将个人电子邮件地址设置为主要电子邮件地址。
3. 完全移除工作邮箱地址。仅将其设为次要邮箱是不够的。

在您的托管账户配置完成之前，请将您的个人账户保留在该组织中。之后，您的管理员会将其移除。

如果您的组织已启用托管 SSO 并拥有已验证的电子邮件域名，使用该域名下的电子邮件地址登录时，您将被重定向到该组织的 SSO 页面。若要登录您的个人账户，请改用您的用户名。

一旦工作邮箱可用，管理员可以在 IdP 中为该用户重试配置，或等待下一次同步将其纳入。

迁移后

用户生命周期由您的 IdP 管理：

• 在您的 IdP 中停用用户会将其从组织中移除。如果之后重新激活该用户，系统将复用其现有的托管账户。
• 通过 SCIM 删除用户将永久删除其托管账户。请参阅取消配置。