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.

Important Notas

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

Formato de URL base do SCIM

A comunicação SCIM ocorre por meio de solicitações aos terminais SCIM do provedor de serviços SCIM. De acordo com o protocolo padrão, todos eles têm uma parte de URL base, que os provedores de identidade usam para configurar a integração do SCIM e, posteriormente, usam essa base para formar endpoints (como ../scim/v2/Users/).

Para Azure AD/Entra ID:

https://api.[região].prod.cosafe.com/core/v1/scim/v2?aadOptscim062020

Importante: O parâmetro ?aadOptscim062020 é especificamente necessário para integração do Azure AD/Entra ID. Isso garante que o cliente Entra scim enviará solicitações de acordo com a especificação SCIM 2.0.

Para outros provedores:

https://api.[região].prod.cosafe.com/core/v1/scim/v2

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. Receba credenciais de API: O suporte da Cosafe fornecerá a você:
   • Chave de API: Token de autenticação para solicitações SCIM
   • URL base do SCIM: com base na sua região

Etapa 2: 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 3: 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 e a chave da API da Etapa 1. Certifique-se de que a URL base esteja no formato descrito em Formato da URL base.

   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 da provisão seja "Sincronizar apenas usuários e grupos atribuídos". (Deve ser definido por padrão).

Etapa 4: 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

Important Notas

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

Important Notas

• 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 propriedade email 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 como Switch([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 5: Atribuir grupos à integração

Entrada

Navegue em "Provisionamento" -> "Usuários e grupos"

1. Pressione "Adicionar usuário/grupo"
2. Selecione os grupos que você deseja atribuir. Nota: pode selecionar vários ao mesmo tempo
3. 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 6: 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 o usuário não tem mais atribuição de integração direta ao scim ou atribuição de integração indireta ao scim (por meio de associação de grupo de um grupo atribuído ao scim, consulte Atribuir grupos). Portanto, se você remover um usuário do seu diretório de qualquer grupo atribuído, o usuário será excluído. Se o seu provedor for a Entra, você poderá mover um usuário entre grupos dentro do período de solicitações de sincronização, e a Entra não tentará desprovisionar esse usuário.

Solução de problemas

Problemas comuns

Usuários não sincronizando:

• Verifique se a chave da API está correta e ativa
• Verifique o formato da URL base do SCIM: Formato da URL base
• 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:

1. Coletar logs de provisionamento de erros e registros de data e hora
2. Observe quais operações estão falhando
3. 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.