Переход на управляемый SSO

Эта функция входит в план Enterprise Plus.

Это руководство предназначено для администраторов организаций, которые переводят существующую организацию из стандартной в организацию с Managed SSO.

Самое важное, что нужно понять перед началом: существующие личные аккаунты Hugging Face участников не конвертируются в управляемые аккаунты. Каждый участник получает новый управляемый аккаунт, создаваемый вашим Identity Provider (IdP). Прежде чем аккаунт будет создан, участник должен освободить свой рабочий адрес электронной почты в личном аккаунте.

В этом руководстве в качестве примера имени организации используется my-org.

Предварительные требования

SSO должен быть уже настроен, протестирован и включен в вашей организации. При миграции используется ваше существующее приложение OIDC или SAML.

Шаги миграции

1. Подготовьте участников. Пройдите с участниками чек-лист перед миграцией.
2. Свяжитесь с Hugging Face. Вступите в контакт с командой Hugging Face и подтвердите переключение. Мы конвертируем организацию и отправим вам учётные данные для аварийного аккаунта my-org:owner.
3. Попросите участников освободить свои рабочие адреса электронной почты. См. Освобождение рабочих адресов электронной почты. Сделайте это до включения provisioning: пользователи, уже назначенные на ваше SSO-приложение, будут provisioned сразу после включения SCIM. Команда Hugging Face может отправить вам список участников, чьи личные аккаунты всё ещё содержат рабочий адрес электронной почты, чтобы вы могли связаться с ними.
4. Set up SCIM in your IdP. Используйте SCIM Tenant URL и токен из настроек SSO → SCIM вашей организации в существующем приложении OIDC или SAML, затем следуйте инструкции для вашего IdP.
   • Okta: следуйте руководству Okta, включая шаг 3. Идентификатор Name ID должен совпадать с идентификатором пользователя Okta.
   • Microsoft Entra ID: следуйте руководству по Entra ID. Значение userName должно соответствовать правилам для имени пользователя, поэтому значения в формате электронной почты, например jdoe@example.com, отклоняются.
   • Другие IdP: см. User Provisioning (SCIM), правила именования пользователей те же.
5. Назначьте пользователей и группы в вашем IdP. Управляемые учетные записи создаются по мере добавления пользователей.
6. Удаляйте оставшиеся личные аккаунты из организации сразу после создания управляемого аккаунта для каждого участника. Этот шаг необходим с точки зрения безопасности, поскольку личные аккаунты сохраняют доступ до их удаления. Их удаление также исключает их из групп ресурсов организации.
7. (Необязательно) Сопоставьте группы с Resource Groups и ролями. Свяжите ваши SCIM-группы с Resource Groups и настройте Role Mapping, чтобы назначать роли организации из вашего IdP. Resource Group можно связать с SCIM-группой только в том случае, если в ней нет участников и автоматическое присоединение отключено. Если автоматическое присоединение включено, новые провижнированные управляемые учетные записи также будут добавлены в группу, поэтому отключите его перед провижнингом пользователей или удалите оставшихся участников перед связыванием.

Что изменилось

Что делает конвертация

• Конвертация выполняется командой Hugging Face. Самостоятельно переключить режим невозможно. После подачи запроса команда Hugging Face переводит вашу организацию в управляемый режим.
• Контент и конфигурация вашей организации остаются без изменений. Репозитории, настройки, группы ресурсов и существующая конфигурация SSO (приложение OIDC или SAML) сохраняются. Вы продолжаете использовать то же самое приложение IdP, хотя некоторые настройки может потребоваться скорректировать для SCIM (см. шаг 4).
• Создаётся аварийная административная учётная запись с именем my-org:owner. Она входит по имени пользователя и паролю (не через SSO) и является администратором организации. Команда Hugging Face передаст вам её учётные данные. Храните их в надёжном месте: эта учётная запись позволяет получить доступ к вашей организации, если ваш IdP недоступен или настроен неверно.
• SSO больше нельзя сделать необязательным. Его по-прежнему можно полностью отключить.

Отключение SSO в управляемой организации блокирует доступ всем управляемым пользователям, так как у управляемых учетных записей нет пароля.

Управляемые аккаунты — это новые аккаунты

• Существующие личные аккаунты Hugging Face не конвертируются, не объединяются и не связываются с управляемыми аккаунтами. Каждому участнику создаётся новый аккаунт, который ваш IdP формирует через SCIM при назначении пользователя в IdP.
• Имена пользователей, управляемые организацией, имеют префикс с названием организации: <org-name>:<username>, например my-org:jdoe.
• Управляемые пользователи входят только через ваш IdP. У них нет пароля Hugging Face, и функция «Забыли пароль» для них не работает.
• Управляемые аккаунты подчиняются ограничениям для управляемых аккаунтов.

Членство

• Регулярных участников больше нельзя добавлять по приглашению. Внутренних участников необходимо создавать через SCIM.
• Приглашения остаются доступными только для внешних соавторов.

Существующие личные аккаунты в организации

Личные аккаунты, которые остаются участниками организации после конвертации, сохраняют свою роль. Их токены доступа, уже авторизованные OAuth-приложения и git over SSH продолжают работать, так как эти параметры не проверяются по 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. Полностью удалите рабочий адрес электронной почты. Недостаточно сделать его вторичным.

Держите свою личную учётную запись в организации до тех пор, пока не будет создана управляемая учётная запись. Затем ваш администратор удалит её.

Если в вашей организации уже включён Managed SSO и у неё есть проверенный домен электронной почты, вход по адресу электронной почты на этом домене перенаправляет вас на страницу SSO организации. Чтобы войти в личный аккаунт, используйте имя пользователя.

Когда рабочий адрес электронной почты станет свободен, администратор может повторить процесс настройки для этого пользователя в IdP или дождаться следующей синхронизации, которая обработает его.

После миграции

Жизненный цикл пользователя управляется из вашего IdP:

• Отключение пользователя в вашем IdP исключает его из организации. Если тот же пользователь будет повторно активирован позже, его существующая управляемая учетная запись будет переиспользована.
• Удаление пользователя через SCIM безвозвратно удаляет его управляемую учётную запись. См. Отключение.