Como configurar o SCIM com o Microsoft Entra ID (Azure AD)

Este guia explica como configurar o provisionamento automático de usuários e grupos entre o Microsoft Entra ID e sua organização no Hugging Face usando SCIM.

Este recurso faz parte dos planos Enterprise e Enterprise Plus.

O SCIM requer que o SSO esteja configurado na sua organização primeiro. O SSO básico é autoatendimento, enquanto o SSO gerenciado é configurado com a equipe da Hugging Face.

Etapa 1: Obter a configuração SCIM do Hugging Face

1. Faça login em uma conta do Hugging Face que seja proprietária da organização.
2. Acesse a página de configurações da sua organização no Hugging Face.
3. Vá para a aba SSO e, em seguida, clique na subaba SCIM.
4. Copie a SCIM Tenant URL. Você precisará disso para a configuração do Entra ID.
5. Clique em Generate an access token. Um novo token SCIM será gerado. Copie este token imediatamente e armazene-o com segurança, pois você não poderá visualizá-lo novamente.

Etapa 2: Configure o Provisioning no Microsoft Entra ID

1. No centro de administração do Microsoft Entra, navegue até o seu Aplicativo Empresarial do Hugging Face.
2. No menu à esquerda, selecione Provisioning.
3. Clique em Começar.
4. Alterne o Modo de Provisionamento de “Manual” para Automático.

Etapa 3: Insira as credenciais de administrador

1. Na seção Credenciais de administrador, cole a URL do inquilino SCIM do Hugging Face no campo URL do inquilino.
2. Cole o SCIM token do Hugging Face no campo Secret Token.
3. Clique em Test Connection. Você deve ver uma notificação de sucesso.
4. Clique em Salvar.

Etapa 4: Configure os Mapeamentos de Atributos

1. Na seção Mappings, clique em Provision Microsoft Entra ID Users.

2. Os mapeamentos de atributos padrão frequentemente exigem ajustes para um provisionamento robusto. Recomendamos usar a seguinte configuração. Você pode excluir atributos que não estão listados aqui:

   Atributo customappsso	Atributo do Microsoft Entra ID	Precedência de correspondência
   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. O Nome de usuário precisa estar em conformidade com as seguintes regras.

• Apenas caracteres comuns e `-` são aceitos no Nome de usuário.
• -- (traço duplo) é proibido.
• - não pode iniciar ou terminar o nome.
• Nomes contendo apenas dígitos não são aceitos.
• O comprimento mínimo é 2 e o comprimento máximo é 42.
• O nome de usuário deve ser único dentro da sua organização.

4. Após configurar os mapeamentos de usuários, volte para a tela de Provisioning e clique em Provision Microsoft Entra ID Groups para revisar os mapeamentos de grupos. As configurações padrão para grupos geralmente são suficientes.

Etapa 5: Iniciar o provisionamento

1. Na tela principal de Provisioning, defina o Status do Provisioning como On.
2. Em Configurações, você pode configurar o Escopo para “Sincronizar apenas usuários e grupos atribuídos” ou “Sincronizar todos os usuários e grupos”. Recomendamos começar com “Sincronizar apenas usuários e grupos atribuídos”.
3. Salve suas alterações.

A sincronização inicial pode levar até 40 minutos para começar. Você pode monitorar o progresso na aba Provisioning logs.

Atribuindo usuários e grupos para provisionamento

Para controlar quais usuários e grupos são provisionados para sua organização no Hugging Face, você precisa atribuí-los ao Hugging Face Enterprise Application no Microsoft Entra ID. Isso é feito na aba Usuários e grupos do seu aplicativo.

1. Acesse seu aplicativo Hugging Face Enterprise no centro de administração do Microsoft Entra.
2. Vá para a aba Usuários e grupos.
3. Clique em Adicionar usuário/grupo.
4. Selecione os usuários e grupos que deseja provisionar e clique em Assign.

Somente os usuários e grupos que você atribuir aqui serão provisionados no Hugging Face se você tiver definido o Escopo como “Sincronizar apenas usuários e grupos atribuídos”.

Considerações sobre o plano do Active Directory

• Com os planos Free, Office 365 e Premium P1/P2, você pode atribuir usuários individuais ao aplicativo para provisionamento.
• Com os planos Premium P1/P2, você também pode atribuir grupos. Essa é a abordagem recomendada para gerenciar o acesso em escala, pois você pode gerenciar a membresia dos grupos no AD e as alterações serão refletidas automaticamente no Hugging Face.

Etapa 6: Verifique o provisionamento no Hugging Face

Quando a sincronização for concluída, volte para as configurações da sua organização no Hugging Face:

• Usuários provisionados aparecerão na aba Users Management.
• Os grupos provisionados aparecerão na aba SCIM sob SCIM Groups. Em seguida, esses grupos podem ser atribuídos a Resource Groups para controle de acesso granular.

Etapa 7: Vincular grupos SCIM a grupos de recursos do Hugging Face

Depois que seus grupos forem provisionados a partir do Entra ID, você pode vinculá-los aos Hugging Face Resource Groups para gerenciar permissões em escala. Isso permite que todos os membros de um grupo SCIM recebam automaticamente papéis específicos (como leitura ou escrita) para uma coleção de recursos.

Before linking, make sure the Resource Group you want to link is empty (has no existing members) and does not have auto-join enabled. Both conditions are required — linking will fail otherwise.

1. Nas configurações da sua organização no Hugging Face, navegue até a aba SSO -> SCIM. Você verá uma lista dos seus grupos provisionados sob SCIM Groups.

2. Localize o grupo que deseja configurar e clique em Link resource groups em sua linha.
3. Uma caixa de diálogo será exibida. Clique em Link a Resource Group.
4. Nos menus suspensos, selecione o Resource Group que deseja vincular e a Role Assignment que deseja conceder aos membros do grupo SCIM.
5. Clique em Link to SCIM group e salve o mapeamento.

Uma vez vinculado, o Resource Group passa a ser gerenciado via SCIM: todos os membros já presentes no grupo SCIM são adicionados imediatamente ao Resource Group (backfill), e todas as alterações futuras de membros no Entra ID são refletidas automaticamente. Edições manuais de membros no Resource Group por meio da interface do Hub ou da API serão bloqueadas.

Update on GitHub