Configurando a integração do SCIM

Este guia explica como configurar a integração do SCIM (Sistema para Gerenciamento de Identidade entre Domínios) entre seu provedor de identidade e o Cosafe.

Notas importantes

Este artigo aborda a integração do 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 do SCIM
2. Receber dados de conexão: O suporte da Cosafe fornecerá a URL do SCIM

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

1. Acesse seu Painel de Administração Cosafe
2. Navegue até Conta -> aba Integrações
3. Criar chave de API SCIM
4. Copie a chave

Importante

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

Etapa 3: Configurar grupos no Cosafe

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

1. Acesse seu Painel de Administração Cosafe
2. Navegue até o gerenciamento de grupos
3. Crie grupos onde os usuários do SCIM serão atribuídos. Coloque esses grupos nas subcontas apropriadas. Se um grupo já existir, você poderá usar um grupo existente para a associação.
4. Somente Entra — Configurar ID externo: Para cada grupo no Painel de administração do Cosafe, defina o campo ID do grupo 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 o URL base do Cosafe SCIM. As etapas exatas variam de acordo com o provedor:

Para ID de entrada:

1. Navegue até Aplicativos empresariais no Entra ID
2. Crie um novo ou selecione seu aplicativo Cosafe existente. Para novas aplicações:
   • 2.1. "Novo aplicativo" -> "Crie seu próprio aplicativo" (canto superior esquerdo)
   • 2.2. "Nome do seu aplicativo" — qualquer nome, por exemplo Cosafe SCIM. É preferível que você consiga distingui-lo mais tarde.
   • 2.3. Selecione "Não galeria"
3. Navegue até "Provisionamento" (lado esquerdo), "Criar nova configuração" (topo)
4. Insira a URL base do SCIM da Etapa 1 e a chave da API da Etapa 2

   Observação: você não precisa adicionar a parte "Bearer" à chave de API; cole-a diretamente na entrada, conforme fornecido.

5. Pressione "Testar conexão"
6. Certifique-se de que o escopo de provisionamento seja "Sincronizar apenas usuários e grupos atribuídos" (deve ser definido por padrão)

Etapa 5: Configuração do mapeamento de atributos

Entrada

Mapeamento de atributos de grupo:

Atributo SCIM Cosafe	Atributo do Provedor de Identidade	Obrigatório	Precedência correspondente	Descrição
ID externo	objetoId	Sim	1	O id que foi usado para criar grupos no Cosafe
nome de exibição	nome de exibição	Não		O nome do grupo
membros	membros	Sim		Associações de 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 que você substitua displayName como um atributo correspondente por externalId:

• Alterar a precedência de displayName para 2
• Edite o atributo externalId através do botão "editar" (veja a captura de tela), defina "Combinar objetos usando este atributo": "Sim", "Precedência de correspondência": 1
• Volte a displayName e defina "Corresponder a objetos usando este atributo": "Não", para remover a precedência de correspondência deste atributo. Salvar

---

• Se você deseja excluir displayName, siga os passos no vídeo abaixo, na seção "Opcional: Remover DisplayName".

Opcional: Remover Nome de Exibição

---

Mapeamento de atributos do usuário:

Atributo SCIM Cosafe	Atributo do provedor de identidade	Obrigatório	Precedência correspondente	Descrição
userName	userPrincipalName	Sim	1	Nome de usuário único. Deve ser por e-mail.
ativo	Switch([IsSoftDeleted], , "False", "True", "True", "False")	Sim		Indica se o usuário está habilitado.
displayName	displayName ou name	Sim		Nome completo do usuário
título	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 no formato internacional (ex.: +46701234567).
• Definir active como falso acionará o desprovisionamento do usuário. Mais detalhes sobre a desprovisionação do usuário: Desprovisionamento do Usuário

Informações adicionais para configurar o mapeamento de atributos no Entra: Entra Personalizar Atributos do Aplicativo

Etapa 6: Atribua grupos à integração

Entrar

Navegue até "Provisionamento" -> "Usuários e grupos"

1. Pressione "Adicionar usuário/grupo"
2. Selecione os grupos que deseja atribuir. Observação: é possível selecionar várias opções ao mesmo tempo.
3. Pressione "Atribuir"

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 começar o provisionamento!

Operações SCIM suportadas

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

Operações do usuário

• ✅ Listar usuários (GET /Users)
• ✅ Encontrar usuário (GET /Users?filter=userName eq "user@example.com")
• ✅ Ler Usuário (GET /Users/{id})
• ✅ Criar Usuário (POST /Users)
• ✅ Atualizar Usuário (PUT /Users/{id})
• ✅ Patch User (PATCH /Users/{id})
• ✅ Excluir Usuário (DELETE /Users/{id}, mais detalhes sobre a desprovisionação do usuário: Desprovisionamento de Usuário)

Operações do Grupo

• ✅ Listar Grupos (GET /Groups)
• ✅ Encontrar Grupo (GET /Groups?filter=externalId eq "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx")
• ✅ Ler Grupo (GET /Groups/{id})
• ❌ Criar (os grupos são criados dentro do Cosafe)
• ✅ Atualizar Grupo (PUT /Groups/{id})
• ✅ Grupo de Patch (PATCH /Groups/{id})
• ✅ Excluir Grupo (DELETE /Groups/{id})

Atributos suportados

Usuários:

• userName (obrigatório, atualizável)
• displayName (obrigatório, atualizável)
• phoneNumbers (opcional, atualizável)
• título (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)
• ativo (obrigatório)

Grupos:

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

Fluxo de desprovisionamento de usuários

O usuário será desativado quando o Cosafe SCIM receber:

• DELETE /Users/{id}
• PUT /Users/{id} com ativo: falso
• PATCH /Users/{id} com ativo: falso

Todas essas 3 variantes acionarão o desprovisionamento do usuário, e o usuário será excluído. As sessões dos usuários serão invalidadas e eles não terão mais acesso ao aplicativo móvel ou à versão web do Cosafe. Posteriormente, o usuário poderá ser recriado automaticamente.

Quando o desprovisionamento é acionado?

• Quando um 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 um usuário é excluído permanentemente do seu diretório, o provedor de identidade enviará uma solicitação SCIM via DELETE. Mas, para excluir um usuário permanentemente, geralmente os provedores de identidade exigem que o usuário seja excluído temporariamente primeiro; o que desencadeia o primeiro caso.
• Quando um usuário não tiver mais uma atribuição de integração SCIM direta ou indireta (por meio de associação a um grupo atribuído; consulte Atribuir grupos), o usuário será excluído.
  Se o provedor for a 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 sincronizando:

• Verifique se a chave da API está correta e ativa.
• Verifique se o formato do URL base SCIM está conforme fornecido em Etapa 1: Contatar o Suporte da Cosafe
• Verifique se os usuários necessários são membros dos grupos atribuídos em seu provedor de identidade.
• Confirme a configuração de mapeamento de usuários.
• Analise os registros de provisionamento do seu provedor de identidade.

Atribuições em 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.
• Analise os registros de provisionamento do seu provedor de identidade.

Atrasos de sincronização:

• As operações iniciais de configuração do SCIM geralmente são processadas em 3 a 5 minutos.
• A taxa de operações de sincronização SCIM depende do seu provedor de identidade. Veja Com que rapidez as alterações são sincronizadas
• Lotes grandes de usuários podem demorar mais.

Como obter apoio

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

1. Coletar registros de erros de provisionamento e seus respectivos carimbos de data/hora.
2. Observe quais operações estão falhando.
3. Entre em contato com support@cosafe.com e forneça informações detalhadas.

---

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