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.
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.
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
- Solicitar ativação do SCIM: Envie um e-mail para support@cosafe.com para solicitar a ativação da integração do SCIM
- Receber dados de conexão: O suporte da Cosafe fornecerá a URL do SCIM
Etapa 2: Criar chave de API para integração SCIM
- Acesse seu Painel de Administração Cosafe
- Navegue até Conta -> aba Integrações
- Criar chave de API SCIM
- Copie a chave
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:
- Acesse seu Painel de Administração Cosafe
- Navegue até o gerenciamento de grupos
- 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.
- 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:
- Navegue até Aplicativos empresariais no Entra ID
- 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"
 
- Navegue até "Provisionamento" (lado esquerdo), "Criar nova configuração" (topo)
- 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. 
- Pressione "Testar conexão"
- 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 | Sim | O nome do grupo | |
| membros | membros | Sim | Associações de grupos de usuários | 
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 displayNamepara 2
- Edite o atributo externalIdatravés do botão "editar" (veja a captura de tela), defina"Combinar objetos usando este atributo": "Sim","Precedência de correspondência": 1
- Volte para displayNamee defina"Match objects using this attribute": "No", para remover a precedência correspondente deste atributo. Salvar


Mapeamento de atributos do usuário:
| Atributo SCIM Cosafe | Atributo do Provedor de Identidade | Obrigatório | Precedência correspondente | Descrição | 
|---|---|---|---|---|
| nome de usuário | userPrincipalName | Sim | 1 | Nome de usuário exclusivo. Deve ser e-mail | 
| ativo | Switch([IsSoftDeleted], , "Falso", "Verdadeiro", "Verdadeiro", "Falso") | Sim | Indica se o usuário está habilitado | |
| nome de exibição | displayNameounome | Sim | Nome completo do usuário | |
| título | Título do trabalho | Não | Cargo do usuário | |
| phoneNumbers[tipo eq "trabalho"].valor | número de telefone | Não | Número de telefone principal | 
- 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 na 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 userPrincipalNameque você tem em entra, você pode mapeá-lo para a propriedadeemailEntra
- Você deve excluir a linha emails[type eq "work"].value
- Os números de telefone devem estar em formato internacional (por exemplo, +46701234567)
- Entrada: o número de telefone deve ser exatamente um
- valor ativocomoSwitch([IsSoftDeleted], , "False", "True", "True", "False")— é o mapeamento padrão
- Definir ativocomo falso acionará o desprovisionamento do usuário. Mais detalhes sobre o desprovisionamento 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: Atribuir grupos à integração
Entrada
Navegue em "Provisionamento" -> "Usuários e grupos"
- Pressione "Adicionar usuário/grupo"
- Selecione os grupos que você deseja atribuir. Nota: pode selecionar vários ao mesmo tempo
- Pressione "Atribuir"
Se o usuário for membro do grupo no AD, que está atribuído à integração do scim, esse usuário também será considerado como atribuído à integração do scim.
Etapa 7: iniciar o provisionamento
Agora você pode começar a provisionar!
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 /Usuários)
- ✅ Encontrar usuário (GET /Users?filter=userName eq "user@example.com")
- ✅ Ler usuário (GET /Usuários/{id})
- ✅ Criar usuário (POST /Usuários)
- ✅ Atualizar usuário (PUT /Usuários/{id})
- ✅ Patch de usuário (PATCH /Usuários/{id})
- ✅ Excluir usuário (DELETE /Users/{id}, mais detalhes sobre o desprovisionamento de usuários: Desprovisionamento de usuários)
Operações de Grupo
- ✅ Listar Grupos (GET /Groups)
- ✅ Encontrar grupo (GET /Groups?filter=externalId eq "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx")
- ✅ Ler Grupo (GET /Grupos/{id})
- ❌ Criar (os grupos são criados dentro do Cosafe)
- ✅ Atualizar Grupo (PUT /Grupos/{id})
- ✅ Grupo de Patches (PATCH /Grupos/{id})
- ✅ Excluir Grupo (DELETE /Grupos/{id})
Atributos suportados
Usuários:
- userName(obrigatório, atualizável)
- displayName(obrigatório, atualizável)
- phoneNumbers(opcional, não 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 do usuário
O usuário está sendo desprovisionado quando o Cosafe SCIM receber:
- EXCLUIR /Usuários/{id}
- PUT /Usuários/{id}com- ativo: falso
- PATCH /Usuários/{id}com- ativo: falso
Todas essas três variantes acionarão o desprovisionamento do usuário, e o usuário será excluído. As sessões dos usuários se tornarão inválidas e eles não terão mais acesso ao aplicativo Cosafe Mobile nem ao aplicativo Web. Mais tarde, o usuário pode ser recriado automaticamente.
Quando o desprovisionamento é acionado?
- Quando o usuário é excluído temporariamente do seu diretório, o provedor de identidade enviará uma solicitação SCIM via PATCH ou PUT para definir o usuário como ativo: falso
- Quando o usuário for excluído definitivamente do seu diretório, o provedor de identidade enviará uma solicitação SCIM via DELETE. Mas para excluir definitivamente um usuário, geralmente os provedores de identidade exigem que ele seja excluído de forma reversível primeiro; o que aciona 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 Entra, você poderá 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 da URL base do SCIM é conforme fornecido em Etapa 1: Entre em contato com o suporte da Cosafe
- Verifique se os usuários necessários são membros de grupos atribuídos no seu provedor de identidade
- Confirmar configuração de mapeamento de usuário
- Revise os logs de provisionamento no seu provedor de identidade
Tarefas 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
- Confirmar 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 a 5 minutos
- A taxa de operações de sincronização do SCIM depende do seu provedor de identidade. Veja Com que rapidez as mudanças são sincronizadas
- Grandes lotes de usuários podem levar mais tempo
Obtendo suporte
Se você encontrar problemas com a integração do SCIM:
- Coletar logs de provisionamento de erros e registros de data e hora
- Observe quais operações estão falhando
- Entre em contato com support@cosafe.com com informações detalhadas
Para perguntas adicionais sobre a integração do SCIM, entre em contato com nossa equipe de suporte em support@cosafe.com.