informação

This translation has not been approved yet, read in English to be sure you get an accurate article.

Configurando a integração do SCIM

Este guia orienta você na configuração da integração SCIM (System for Cross-domain Identity Management) entre seu provedor de identidade e o Cosafe.

Notas importantes

Este artigo aborda a integração SCIM com o Entra ID (Azure AD) como provedor de identidade. Para configurar o Cosafe SCIM com outros provedores de identidade, entre em contato com o suporte.

Provedores de identidade suportados

Pré-requisitos

Antes de iniciar a configuração do SCIM, certifique-se de ter:

• Acesso administrativo ao seu provedor de identidade
• Acesso administrativo à sua conta Cosafe
• Credenciais de API fornecidas pelo suporte da Cosafe

Etapa 1: Entre em contato com o suporte da Cosafe

1. Solicitar ativação do SCIM: Envie um e-mail para support@cosafe.com para solicitar a ativação da integração SCIM
2. Receber dados de conexão: O suporte da Cosafe fornecerá a URL SCIM

Etapa 2: Criar chave de API para integração SCIM

1. Acesse seu Cosafe Admin Panel
2. Navegue até a aba Account -> Integrations
3. Crie a chave de API SCIM
4. Copie a chave

Importante

Certifique-se de copiar a chave de API, pois você não poderá vê-la novamente.

Etapa 3: Configurar grupos no Cosafe

Antes de habilitar a sincronização SCIM, configure grupos no Cosafe:

1. Acesse seu Cosafe Admin Panel
2. Navegue até o gerenciamento de grupos
3. Crie grupos onde os usuários SCIM serão atribuídos. Coloque esses grupos nas subcontas apropriadas. Se um grupo já existir, você pode usar um grupo existente para a associação.
4. Apenas Entra — Configurar External ID: Para cada grupo no Cosafe Admin Panel, defina o campo Group ID para corresponder ao ID do grupo do seu provedor de identidade (objectId no Entra).

Etapa 4: Configuração do provedor de identidade

Configure seu provedor de identidade para usar a URL base SCIM da Cosafe. As etapas exatas variam por provedor:

Para Entra ID:

1. Navegue até Enterprise Applications no Entra ID
2. Crie um novo ou selecione seu aplicativo Cosafe existente. Para novos aplicativos:
   • 2.1. "New application" -> "Create your own application" (canto superior esquerdo)
   • 2.2. "Name of your app" — qualquer nome, por exemplo Cosafe SCIM. É preferível que você consiga distingui-lo mais tarde.
   • 2.3. Selecione "Non-gallery"
3. Navegue até "Provisioning" (lado esquerdo), "Create new configuration" (topo)
4. Insira a SCIM Base URL da Etapa 1 e a chave de API da Etapa 2

   Observação: Você não precisa adicionar a parte "Bearer " à chave de API; cole-a diretamente no campo de entrada como fornecida.

5. Pressione "Test Connection"
6. Certifique-se de que o escopo de provisionamento seja "Sync only assigned users and groups" (deve estar definido por padrão)

Etapa 5: Configuração do mapeamento de atributos

Entra

Mapeamento de atributos de grupo:

Atributo SCIM da Cosafe	Atributo do provedor de identidade	Obrigatório	Precedência de correspondência	Descrição
externalId	objectId	Sim	1	O id que foi usado para criar grupos no Cosafe
displayName	displayName	Não		O nome do grupo
members	members	Sim		Associações a grupos de usuários

Notas importantes

externalId deve ser um atributo correspondente. Por padrão, o atributo correspondente é definido como displayName com precedência de correspondência 1.

Para fazer com que o Entra permita substituir displayName como atributo correspondente por externalId:

• Altere a precedência de displayName para 2
• Edite o atributo externalId pelo botão "edit" (veja a captura de tela), defina "Match objects using this attribute": "Yes", "Matching precedence": 1
• Volte ao displayName e defina "Match objects using this attribute": "No", para remover a precedência de correspondência deste atributo. Salve

---

• Se você quiser excluir displayName, siga as etapas no vídeo abaixo, em "Optional: Remove DisplayName".

Optional: Remove DisplayName

---

Mapeamento de atributos de usuário:

Atributo SCIM da Cosafe	Atributo do provedor de identidade	Obrigatório	Precedência de correspondência	Descrição
userName	userPrincipalName	Sim	1	Nome de usuário único. Deve ser e-mail
active	Switch([IsSoftDeleted], , "False", "True", "True", "False")	Sim		Indica se o usuário está habilitado
displayName	displayName ou name	Sim		Nome completo do usuário
title	jobTitle	Não		Cargo do usuário
phoneNumbers[type eq "work"].value	Switch(IsNullOrEmpty([telephoneNumber]), "tel:", "True", "tel:", "False", [telephoneNumber])	Não		Número de telefone principal
phoneNumbers[type eq "mobile"].value	Switch(IsNullOrEmpty([mobile]), "tel:", "True", "tel:", "False", [mobile])	Não		Número de telefone secundário

Notas importantes

• O nome de usuário deve ser um endereço de e-mail
• O nome de usuário (endereço de e-mail) deve ser único em toda a plataforma Cosafe
• O nome de usuário (endereço de e-mail) deve corresponder ao e-mail que você deseja que seus usuários sincronizados tenham no Cosafe. Se não corresponder ao userPrincipalName que você tem no Entra, você pode mapeá-lo para a propriedade email do Entra
• Você deve excluir a linha emails[type eq "work"].value
• Os números de telefone devem estar em formato internacional (ex.: +46701234567)
• Definir active como false acionará o desprovisionamento do usuário. Mais detalhes sobre desprovisionamento de usuários: Desprovisionamento de Usuário

Informações adicionais para configurar o mapeamento de atributos no Entra: Entra Customize Application Attributes

Etapa 6: Atribuir grupos à integração

Entra

Navegue até "Provisioning" -> "Users and groups"

1. Pressione "Add user/group"
2. Selecione os grupos que você deseja atribuir. Observação: é possível selecionar vários ao mesmo tempo
3. Pressione "Assign"

Se o usuário for membro do grupo no AD que está atribuído à integração SCIM, esse usuário também será considerado como atribuído à integração SCIM.

Etapa 7: Iniciar o provisionamento

Agora você pode iniciar o provisionamento!

Opcional: Configurar e-mails automáticos de boas-vindas

Após o SCIM estar habilitado em sua conta, você pode escolher se os usuários recém-provisionados receberão automaticamente um e-mail de boas-vindas.

1. No Cosafe Admin Panel, navegue até Conta → Integrações.
2. Localize a alternância de e-mails automáticos de boas-vindas. Esta alternância só é visível quando o SCIM está habilitado em sua conta.
3. Defina a alternância no estado desejado:
   • Ativada: Cada usuário criado via SCIM recebe automaticamente um convite por e-mail de boas-vindas.
   • Desativada: Os usuários SCIM são criados e ativados sem receberem um e-mail. Você pode convidá-los manualmente pela página Usuários no Admin Panel.

Operações SCIM suportadas

A Cosafe implementa um subconjunto do padrão SCIM 2.0, suportando as seguintes operações:

Operações de usuário

• ✅ List Users (GET /Users)
• ✅ Find User (GET /Users?filter=userName eq "user@example.com")
• ✅ Read User (GET /Users/{id})
• ✅ Create User (POST /Users)
• ✅ Update User (PUT /Users/{id})
• ✅ Patch User (PATCH /Users/{id})
• ✅ Delete User (DELETE /Users/{id}, mais detalhes sobre desprovisionamento de usuários: Desprovisionamento de Usuário)

Operações de grupo

• ✅ List Groups (GET /Groups)
• ✅ Find Group (GET /Groups?filter=externalId eq "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx")
• ✅ Read Group (GET /Groups/{id})
• ❌ Create (grupos são criados dentro do Cosafe)
• ✅ Update Group (PUT /Groups/{id})
• ✅ Patch Group (PATCH /Groups/{id})
• ✅ Delete Group (DELETE /Groups/{id})

Atributos suportados

Usuários:

• userName (obrigatório, atualizável)
• displayName (obrigatório, atualizável)
• phoneNumbers (opcional, atualizável)
• title (opcional, atualizável)
• id (atribuído pela Cosafe, não atualizável)
• externalId (opcional, atualizável)
• emails (atribuído pela Cosafe, será sempre igual a userName)
• active (obrigatório)

Grupos:

• id (atribuído pela Cosafe, não atualizável)
• externalId (obrigatório, atualizável)
• displayName (obrigatório, atualizável)
• members (obrigatório, atualizável)

Fluxo de desprovisionamento de usuário

O usuário é desprovisionado quando o Cosafe SCIM recebe:

• DELETE /Users/{id}
• PUT /Users/{id} com active: false
• PATCH /Users/{id} com active: false

Todas essas três variantes acionarão o desprovisionamento do usuário, e o usuário será excluído. As sessões do usuário se tornarão inválidas, eles não terão mais acesso ao aplicativo móvel ou web do Cosafe. Posteriormente, o usuário pode ser recriado automaticamente.

Quando o desprovisionamento é acionado?

• Quando o usuário é excluído logicamente do seu diretório, o provedor de identidade enviará uma solicitação SCIM via PATCH ou PUT para definir o usuário como active: false
• Quando o usuário é excluído permanentemente do seu diretório, o provedor de identidade enviará uma solicitação SCIM via DELETE. Mas, para excluir permanentemente um usuário, geralmente os provedores de identidade exigem que se exclua logicamente o usuário primeiro; o que aciona o primeiro caso.
• Quando um usuário não tem mais uma atribuição direta ou indireta de integração SCIM (por meio de associação a um grupo atribuído; veja Atribuir grupos), o usuário será excluído.
  Se o provedor for o Entra, você pode mover o usuário entre grupos dentro do intervalo de sincronização sem acionar o desprovisionamento.

Solução de problemas

Problemas comuns

Usuários não estão sincronizando:

• Verifique se a chave de API está correta e ativa
• Verifique se o formato da SCIM Base URL é o fornecido na Etapa 1: Entre em contato com o suporte da Cosafe
• Verifique se os usuários necessários são membros dos grupos atribuídos no seu provedor de identidade
• Confirme a configuração de mapeamento de usuários
• Revise os logs de provisionamento no seu provedor de identidade

Atribuições de grupo não estão funcionando:

• Verifique se os IDs de grupo existem no Cosafe
• Verifique se os grupos estão atribuídos à integração nas configurações de integração do seu provedor de identidade
• Confirme a configuração de mapeamento de grupo
• Revise os logs de provisionamento no seu provedor de identidade

Atrasos de sincronização:

• As operações iniciais de configuração do SCIM normalmente são processadas em 3-5 minutos
• A taxa de operações SCIM de sincronização depende do seu provedor de identidade. Veja Quão rápido as alterações são sincronizadas
• Lotes grandes de usuários podem demorar mais

Obtendo suporte

Se você encontrar problemas com a integração SCIM:

1. Colete logs de erro de provisionamento e timestamps
2. Anote quais operações estão falhando
3. Entre em contato com support@cosafe.com com informações detalhadas

---

Para outras dúvidas sobre a integração SCIM, entre em contato com nossa equipe de suporte em support@cosafe.com.