Migrando para o SSO gerenciado

Este recurso faz parte do plano Enterprise Plus.

Este guia é para administradores de organização que estão convertendo uma organização existente de uma organização padrão para uma organização Managed SSO.

A coisa mais importante a entender antes de começar: as contas pessoais existentes dos membros no Hugging Face não são convertidas em contas gerenciadas. Cada membro recebe uma nova conta gerenciada, provisionada pelo seu Identity Provider (IdP). Antes que um membro possa ser provisionado, ele deve liberar seu endereço de e-mail corporativo em sua conta pessoal.

Ao longo deste guia, usamos my-org como exemplo de nome de organização.

Pré-requisitos

O SSO já deve estar configurado, testado e habilitado na sua organização. A migração reutiliza o seu aplicativo OIDC ou SAML existente.

Etapas de migração

1. Prepare seus membros. Passe pelo checklist pré-migração com seus membros.
2. Entre em contato com a Hugging Face. Fale com a equipe da Hugging Face e confirme a troca. Nós convertemos a organização e enviamos as credenciais para a conta de emergência my-org:owner.
3. Peça aos membros que liberem seus e-mails corporativos. Consulte Liberando endereços de e-mail corporativos. Faça isso antes de habilitar o provisionamento: os usuários já atribuídos ao seu aplicativo SSO são provisionados assim que o SCIM for ativado. A equipe do Hugging Face pode enviar a você a lista de membros cujas contas pessoais ainda possuem um endereço de e-mail corporativo, para que você possa entrar em contato com eles.
4. Set up SCIM in your IdP. Use a URL do inquilino SCIM e o token da sua organização nas configurações de SSO → SCIM do seu aplicativo OIDC ou SAML existente e, em seguida, siga o guia para o seu IdP.
   • Okta: siga o guia do Okta, incluindo a Etapa 3. O Name ID deve ser o ID do usuário do Okta.
   • Microsoft Entra ID: siga o guia do Entra ID. O userName deve seguir as regras de nome de usuário, portanto, valores no formato de e-mail, como jdoe@example.com, são rejeitados.
   • Outros IdPs: consulte User Provisioning (SCIM), com as mesmas regras de nome de usuário.
5. Atribua usuários e grupos no seu IdP. As contas gerenciadas são criadas conforme os usuários são provisionados.
6. Remova as contas pessoais restantes da organização assim que a conta gerenciada de cada membro for provisionada. Essa etapa é necessária por questões de segurança, pois as contas pessoais mantêm o acesso até serem removidas. A remoção delas também as exclui dos Grupos de Recursos da organização.
7. (Opcional) Mapear grupos para Resource Groups e papéis. Vincule seus grupos SCIM aos Resource Groups e configure o Role Mapping para atribuir papéis da organização a partir do seu IdP. Um Resource Group só pode ser vinculado a um grupo SCIM se não tiver membros e se o auto-join estiver desativado. Se o auto-join estiver ativado, as contas gerenciadas recém-provisionadas também serão adicionadas ao grupo, portanto, desative-o antes de provisionar usuários ou remova quaisquer membros restantes antes de vincular.

O que muda

O que a conversão faz

• A conversão é realizada pela equipe do Hugging Face. Não há uma opção de autoatendimento. Assim que você solicita, a equipe do Hugging Face alterna sua organização para o modo gerenciado.
• O conteúdo e a configuração da sua organização permanecem inalterados. Repositórios, configurações, Resource Groups e sua configuração de SSO existente (aplicativo OIDC ou SAML) são mantidos. Você mantém o mesmo aplicativo de IdP, embora algumas configurações possam precisar de ajustes para SCIM (veja etapa 4).
• Uma conta de administrador de emergência é criada, com o nome my-org:owner. Ela faz login com nome de usuário e senha (não por meio de SSO) e é administradora da organização. A equipe do Hugging Face compartilha suas credenciais com você. Armazene-as com segurança: essa conta permite acessar sua organização caso seu IdP esteja indisponível ou mal configurado.
• O SSO não pode mais ser opcional. Ele ainda pode ser desativado por completo.

Desativar o SSO em uma organização gerenciada bloqueia todos os usuários gerenciados, pois as contas gerenciadas não possuem senha.

Contas gerenciadas são novas contas

• Contas pessoais existentes do Hugging Face não são convertidas, mescladas ou vinculadas a contas gerenciadas. Cada membro recebe uma nova conta, criada pelo seu IdP por meio de SCIM quando o usuário é atribuído no IdP.
• Os nomes de usuário gerenciados são prefixados com o nome da organização: <org-name>:<username>, por exemplo my-org:jdoe.
• Usuários gerenciados fazem login apenas por meio do seu IdP. Eles não possuem senha do Hugging Face, e a opção “Esqueci a senha” não funciona para eles.
• As contas gerenciadas estão sujeitas às restrições para contas gerenciadas.

Membros

• Membros regulares não podem mais ser adicionados por convite. Membros internos devem ser provisionados por meio do SCIM.
• Os convites permanecem disponíveis apenas para colaboradores externos.

Contas pessoais existentes na organização

Contas pessoais que ainda são membros da organização após a conversão mantêm seu papel. Seus tokens de acesso, aplicativos OAuth que já foram autorizados e o git via SSH continuam funcionando, pois esses itens não são verificados em relação ao SSO. Eles não podem mais iniciar um novo login SSO na organização:

• Se o usuário estiver conectado com sua conta pessoal, ou se essa conta já estiver vinculada ao seu IdP, ele verá: You cannot login with SSO with this account because it's not managed by this organization. Contact your organization administrators.
• Caso contrário, eles veem User not found.

Antes de migrar

Passe por esta lista de verificação com seus membros antes de solicitar a conversão:

• Repositórios pessoais: membros que possuem repositórios em seu namespace pessoal e desejam continuar acessando-os com sua nova conta gerenciada devem transferi-los para a organização antes da troca. Contas gerenciadas não podem possuir conteúdo em um namespace pessoal. Os membros ainda poderão acessar quaisquer repositórios em seu namespace pessoal por meio de sua conta pessoal (não gerenciada).
• Tokens e automação: tokens de contas pessoais mantêm seu acesso à organização até que a conta seja removida dela. Migre scripts, jobs de CI e pipelines para contas de serviço, ou para tokens criados a partir das contas gerenciadas após a troca, e então remova as contas antigas.
• Outras organizações: contas gerenciadas não podem participar de outras organizações. Membros que precisam continuar trabalhando em outras organizações devem manter uma conta pessoal separada (veja a opção 2 abaixo).
• Endereços de e-mail corporativos: cada membro deve liberar seu e-mail corporativo antes de ser provisionado. Consulte Liberando endereços de e-mail corporativos.

Liberando endereços de e-mail de trabalho

Um endereço de e-mail pode pertencer a apenas uma conta do Hugging Face. Isso se aplica a todos os endereços de e-mail de uma conta, primário e secundários. A correspondência não diferencia maiúsculas de minúsculas.

Quando o SCIM tenta criar uma conta gerenciada com um e-mail de trabalho que já é usado por uma conta pessoal, o provisionamento falha com um erro 409:

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

Seu IdP exibe isso como um erro de provisionamento para esse usuário.

Para evitar isso, cada membro deve liberar seu endereço de e-mail corporativo antes de ser provisionado, usando uma das duas opções abaixo.

Qual opção devo escolher?

• Se você usa sua conta do Hugging Face apenas para trabalho nesta organização, escolha a opção 1: exclua a conta pessoal.
• Se você também o usa para trabalho em código aberto, projetos pessoais ou outras organizações, escolha a opção 2: mantenha a conta pessoal e remova o e-mail de trabalho dela.

Opção 1: Excluir a conta pessoal

Exclua sua conta pessoal nas configurações da conta. Isso exclui permanentemente todos os repositórios no seu namespace pessoal e remove você de todas as organizações.

A exclusão de uma conta é permanente. Transfira para a organização, antes, quaisquer repositórios que você deseja manter.

A exclusão é bloqueada se você for o único administrador de outra organização. Adicione outro administrador a essa organização ou exclua-a primeiro. A organização que está sendo migrada não é um problema, pois my-org:owner também é administrador.

Opção 2: Manter a conta pessoal

1. Em suas configurações da conta, adicione um endereço de e-mail pessoal e verifique-o.
2. Torne o endereço de e-mail pessoal seu e-mail principal.
3. Remova completamente o endereço de e-mail corporativo. Torná-lo um e-mail secundário não é suficiente.

Mantenha sua conta pessoal na organização até que sua conta gerenciada seja provisionada. Seu administrador a remove em seguida.

Se a sua organização já tem o Managed SSO ativado e possui um domínio de e-mail verificado, fazer login com um endereço de e-mail nesse domínio redireciona você para a página de SSO da organização. Para fazer login na sua conta pessoal, use seu nome de usuário.

Quando o e-mail corporativo estiver disponível, o administrador pode tentar novamente o provisionamento para esse usuário no IdP ou aguardar a próxima sincronização para que ele seja processado.

Após a migração

O ciclo de vida do usuário é gerenciado a partir do seu IdP:

• Desativar um usuário no seu IdP remove-o da organização. Se o mesmo usuário for reativado posteriormente, sua conta gerenciada existente será reutilizada.
• Excluir um usuário via SCIM exclui permanentemente sua conta gerenciada. Consulte Deprovisioning.