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
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 para
displayName
e 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 | displayName ou nome | 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
userPrincipalName
que você tem em entra, você pode mapeá-lo para a propriedadeemail
Entra - 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
ativo
comoSwitch([IsSoftDeleted], , "False", "True", "True", "False")
— é o mapeamento padrão - Definir
ativo
como 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 auserName
)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}
comativo: falso
PATCH /Usuários/{id}
comativo: 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.