Provisionamento de usuários (SCIM)

Este recurso faz parte dos planos Enterprise e Enterprise Plus.

SCIM (System for Cross-domain Identity Management) é um padrão para automatizar o provisionamento de usuários. Ele permite conectar seu Identity Provider (IdP) ao Hugging Face para gerenciar os membros da sua organização.

O SCIM funciona de maneira diferente dependendo do seu modelo de SSO. Para uma comparação detalhada, consulte a visão geral do SSO.

SSO básico: provisionamento baseado em convites

Com o SSO Básico (plano Enterprise), o SCIM automatiza o convite de usuários existentes do Hugging Face para a sua organização.

• Os usuários devem já possuir uma conta no Hugging Face antes de poderem ser provisionados via SCIM
• Quando seu IdP provisiona um usuário, o Hugging Face envia a ele um e-mail de convite para entrar na organização
• O usuário deve aceitar o convite para se tornar um membro — o provisionamento não concede acesso imediato
• SCIM não pode modificar as informações do perfil do usuário (nome, e-mail, nome de usuário) — o usuário mantém controle total sobre sua conta do Hugging Face
• Quando um usuário é desprovisionado no seu IdP, o convite dele é desativado e o acesso dele à organização é revogado

SSO gerenciado: provisionamento de ciclo de vida completo

Com o Managed SSO (plano Enterprise Plus), o SCIM gerencia o ciclo de vida completo do usuário no Hugging Face.

• SCIM cria uma nova conta do Hugging Face quando um usuário é provisionado — não é necessário que já exista uma conta
• O usuário é adicionado imediatamente à organização como membro, sem etapa de convite
• O SCIM pode atualizar as informações do perfil do usuário (nome, e-mail, nome de usuário) à medida que as alterações ocorrem no seu IdP
• Quando um usuário é desprovisionado no seu IdP, a conta do Hugging Face dele é desativada e o acesso é revogado

Como habilitar o SCIM

Para habilitar o SCIM, acesse as configurações da sua organização, navegue até a aba SSO e, em seguida, selecione a subaba SCIM.

Você encontrará a SCIM Tenant URL e um botão para gerar um SCIM token. Você precisará de ambos para configurar seu IdP. O SCIM token é um segredo e deve ser armazenado com segurança na configuração do seu IdP.

Quando o SCIM é ativado no seu IdP, os usuários provisionados aparecerão na aba Users Management e os grupos provisionados aparecerão na aba SCIM nas configurações da sua organização.

Provisionamento de grupos

Além do provisionamento de usuários, o SCIM suporta provisionamento de grupos. Os grupos enviados do seu IdP são armazenados como grupos SCIM no Hugging Face e podem ser vinculados a Resource Groups na aba SCIM das configurações da sua organização.

Vinculando um grupo SCIM a um grupo de recursos

Para vincular um grupo SCIM, acesse a aba SSO → SCIM da sua organização. Os grupos provisionados são listados em uma tabela. Na coluna Resource Groups, cada grupo exibe um botão Link resource groups (se ainda não houver vínculos) ou o número de grupos de recursos atualmente vinculados (por exemplo, “2 resource groups”). Ao clicar em qualquer um deles, uma janela modal é aberta, onde você pode adicionar um ou mais Resource Groups, cada um com sua própria atribuição de papel. Você também pode alterar ou remover vínculos existentes a partir da mesma janela modal.

Antes de vincular, verifique se as seguintes condições são atendidas:

• O Resource Group deve ter nenhum membro existente. A vinculação a um Resource Group não vazio não é permitida.
• O Resource Group não deve ter o auto-join habilitado. O auto-join (que adiciona automaticamente cada novo membro da organização ao RG) é mutuamente exclusivo com o gerenciamento via SCIM. Desative o auto-join no RG antes de vinculá-lo.

Um grupo SCIM pode ser vinculado a vários Resource Groups, cada um com seu próprio papel.

O que acontece após o vínculo

Quando um grupo SCIM é vinculado a um Resource Group:

• Backfill: Todos os membros que já estão no grupo SCIM são adicionados imediatamente ao Resource Group no papel configurado.
• Ongoing sync: As alterações de associação no seu IdP são refletidas automaticamente:
  • Quando um usuário é adicionado ao grupo no seu IdP, ele é adicionado a todos os Resource Groups vinculados.
  • Quando um usuário é removido do grupo no seu IdP, ele é removido de todos os Resource Groups vinculados, exceto aqueles aos quais o usuário está vinculado por meio de outros grupos SCIM. Nesses casos, a função do usuário será atualizada para a função “mais alta” concedida pelos outros grupos SCIM.
  • Quando um grupo SCIM é excluído no seu IdP, todos os seus membros são removidos dos Resource Groups vinculados, exceto os usuários que pertencem a esses Resource Groups por meio de outros grupos SCIM. Para cada um desses Resource Groups, as funções dos usuários são atualizadas para a função “mais alta” concedida pelos outros grupos SCIM.
• Mudanças de papel: Se você atualizar o papel em um link, os papéis de todos os membros atuais do grupo naquele Resource Group são atualizados imediatamente.

Grupos de Recursos gerenciados por SCIM

Um Resource Group vinculado a um grupo SCIM é considerado gerenciado por SCIM. O IdP é a única fonte de verdade para seus usuários regulares. Como resultado:

• Alterações manuais de membros via a interface do Hub ou a API são bloqueadas para usuários comuns — qualquer tentativa de adicionar, remover ou alterar o papel de um usuário comum em um Grupo de Recursos gerenciado por SCIM retornará um erro 403.
• Contas de serviço são a exceção: como nunca são provisionadas por meio do SCIM, você ainda pode adicionar, remover ou alterar o papel de uma conta de serviço manualmente em um Resource Group gerenciado por SCIM.
• O auto-join não pode ser ativado em um Resource Group gerenciado por SCIM. Para reativar o auto-join, primeiro remova o link SCIM.

Nas configurações do Resource Group, um Resource Group gerenciado por SCIM exibe o selo SCIM synced, e o formulário de membros observa que apenas contas de serviço podem ser adicionadas ou removidas manualmente.

O provisionamento de grupos funciona da mesma maneira tanto para o SSO Básico quanto para o SSO Gerenciado.

Atributos de usuário suportados

O endpoint SCIM da Hugging Face suporta os seguintes atributos de usuário:

Atributo	Descrição	SSO básico	SSO gerenciado
userName	Nome de usuário do Hugging Face	Somente leitura	Leitura/Gravação
name.givenName	Nome	Somente leitura	Leitura/Gravação
name.familyName	Sobrenome	Somente leitura	Leitura/Gravação
emails[type eq "work"].value	Endereço de e-mail	Somente leitura	Leitura/Gravação
externalId	Identificador atribuído pelo IdP	Leitura/Gravação	Leitura/Gravação
active	Se o usuário é um membro ativo	Leitura/Gravação	Leitura/Gravação

Com o SSO Básico, apenas active e externalId podem ser modificados via SCIM — todos os outros atributos são controlados pelo usuário em sua conta do Hugging Face.

Para o provisionamento de grupos, os atributos suportados são displayName, members e externalId.

Deprovisioning

O comportamento de desprovisionamento depende de como o usuário é removido e do modelo de SSO utilizado.

Definir active como false (desprovisionamento suave):

• O usuário perde o acesso à organização
• Com SSO Básico: o convite é desativado
• Com SSO gerenciado: o usuário é removido da organização, mas sua conta e seu conteúdo são preservados — isso é reversível ao definir active novamente como true

Exclusão do usuário via SCIM (desprovisionamento definitivo):

• Com o SSO Básico: o usuário é removido da organização e de todos os seus grupos de recursos. Sua conta do Hugging Face e o conteúdo pessoal não são afetados — eles simplesmente perdem a membresia na sua organização.
• Com SSO gerenciado: a conta do Hugging Face do usuário é permanentemente excluída, junto com todo o conteúdo que ele criou. Essa ação é irreversível.

Provedores de identidade suportados

Suportamos SCIM com qualquer IdP que implemente o protocolo SCIM 2.0. Temos guias específicos para alguns dos provedores mais populares:

• Como configurar o SCIM com o Microsoft Entra ID
• Como configurar o SCIM com o Okta

Update on GitHub