Skip to main content
O ClickHouse Cloud oferece suporte ao SCIM 2.0 (System for Cross-domain Identity Management) para o gerenciamento automatizado do ciclo de vida de usuários e grupos. Depois de se conectar ao seu provedor de identidade, cada usuário atribuído ao aplicativo ClickHouse Cloud é criado automaticamente na sua organização com a função correta, as atualizações de perfil são aplicadas automaticamente e, ao remover um usuário do seu IdP, o acesso dele é revogado — sem convites manuais nem contas órfãs. Este guia mostra como configurar o provisionamento SCIM de ponta a ponta com o Microsoft Entra ID (anteriormente Azure Active Directory). O endpoint SCIM do ClickHouse Cloud segue o SCIM 2.0 (RFC 7644). O Entra ID autentica-se no endpoint usando um Bearer token de longa duração, que você monta a partir da chave e do Secret do token SCIM gerados no Cloud Console.
Usa o Okta?Se o seu provedor de identidade for o Okta, siga o guia Provisionamento SCIM com Okta. O lado do ClickHouse Cloud é idêntico; apenas a configuração do IdP é diferente.

​
Antes de começar

Você precisará de:
  • A role Admin na sua organização do ClickHouse Cloud.
  • SAML SSO já configurado entre o Entra ID e o ClickHouse Cloud. O SCIM cria as contas de usuário, que fazem login por meio do SAML. Portanto, o SSO precisa estar funcionando primeiro.
  • Acesso ao Centro de administração do Microsoft Entra com, no mínimo, a role Administrador de Aplicativos (ou Administrador de Aplicativos em Nuvem) e permissão para configurar o Provisioning no aplicativo empresarial.
  • Uma lista das roles que você deseja atribuir por meio do SCIM (por exemplo: Admins, Developers, Read-only). Defina isso antecipadamente — você criará grupos correspondentes no Entra ID.

​
Como o SCIM funciona com o ClickHouse Cloud

  1. Um administrador no Entra ID atribui um usuário — diretamente ou por meio de um grupo — ao aplicativo empresarial do ClickHouse Cloud.
  2. O serviço de Provisioning do Entra ID chama o endpoint SCIM do ClickHouse Cloud via HTTPS, autenticado com um Bearer token gerado por você.
  3. O ClickHouse Cloud cria o usuário na sua organização e atribui roles com base na associação a grupos no Entra ID.
  4. O usuário faz login no ClickHouse Cloud por meio do fluxo SAML SSO existente.
  5. Alterações de perfil, alterações de grupo e desativações no Entra ID são propagadas automaticamente para o ClickHouse Cloud.

​
Configure o SCIM na sua organização do ClickHouse Cloud

1

Habilitar SCIM

Entre no ClickHouse Cloud Console como administrador da organização e abra Configurações da organização → Configurações de SAML e SCIM → SCIM Configuration.Clique em Enable SCIM. O SCIM é habilitado após a conexão do SAML SSO. Se a opção estiver desabilitada, conclua primeiro a configuração do SAML.Uma SCIM endpoint URL é gerada no seguinte formato:
Copie-a — você a inserirá posteriormente no Entra ID como a Tenant URL.
2

Gerar um token de acesso SCIM

Localize a seção Generate new key e escolha uma data de expiração.
Planeje a rotaçãoRecomendamos definir uma expiração de 12 meses e adicionar um lembrete no calendário. O ClickHouse Cloud oferece suporte a até dois tokens SCIM ativos simultaneamente, permitindo a rotação sem interrupção: gere o novo token, atualize-o no Entra ID, confirme que o provisionamento continua funcionando e revogue o token antigo.
Clique em Generate new key. O token é exibido apenas uma vez, como uma chave (com o prefixo scim_) e um secret. Copie ambos imediatamente e armazene-os em um gerenciador de secrets seguro — não será possível recuperá-los mais tarde. Se os perder, revogue o token e gere um novo.Você combinará a chave e o secret em um único Bearer token para o Entra ID, no formato:
Especificamente, a chave do token (iniciada por scim_), seguida de dois-pontos e do secret do token, sem espaços. O Entra ID envia esse valor no header Authorization: Bearer em cada request.
3

Definir o mapeamento de função

No painel SCIM Configuration, clique em Map roles in “Users and roles” (ou navegue diretamente por Users and roles → Roles).Os grupos SCIM são vinculados às funções do ClickHouse Cloud pelo nome, com algumas regras a considerar:
  • Não é possível mapear um grupo SCIM para uma função de sistema predefinida. Os mapeamentos SCIM se aplicam apenas a funções personalizadas. Se precisar disponibilizar uma capacidade de nível de sistema por meio do SCIM, crie uma função personalizada que inclua as permissões desejadas.
  • Nomes correspondentes são vinculados automaticamente. Se uma função personalizada tiver o mesmo nome do grupo SCIM recebido, o ClickHouse Cloud os vinculará automaticamente — não será necessário mapeamento manual.
  • Para usar um nome de função diferente do nome do grupo, crie a função personalizada com o nome desejado e defina o campo SCIM group como o nome do grupo SCIM ao qual ela deve ser vinculada.
  • Grupos não mapeados criam novas funções. Se o Entra ID enviar um grupo que não corresponda ao nome de uma função existente e não seja referenciado pelo campo SCIM group de nenhuma função, o ClickHouse Cloud criará uma nova função personalizada com o nome desse grupo. Depois, você poderá conceder a ela as permissões desejadas.

​
Configure o provisioning no Microsoft Entra ID

1

Abra seu aplicativo Enterprise do ClickHouse Cloud

Abra a visão geral do Microsoft Entra ID e, em Manage no menu à esquerda, selecione Enterprise applications. Abra a aplicação criada ao configurar o SAML SSO para o ClickHouse Cloud.Se você ainda não criou a aplicação empresarial, siga primeiro o guia de configuração do SAML SSO — com SSO baseado em SAML, a mesma aplicação empresarial é usada tanto para single sign-on quanto para provisionamento SCIM.
2

Defina o modo de Provisioning e as credenciais

Na barra lateral esquerda do aplicativo, selecione Provisioning e clique em Get started (ou em Provisioning → Edit provisioning).Defina Provisioning Mode como Automatic. Em Admin Credentials, preencha:
  • Tenant URL — a URL do endpoint SCIM no ClickHouse Cloud Console (a URL .../scim).
  • Secret Token — suas credenciais SCIM separadas por dois-pontos, no formato <scim-key>:<scim-secret>. O Entra ID envia isso no header Authorization: Bearer.
Clique em Test Connection. O Entra ID fará uma chamada de teste ao endpoint SCIM; você deverá ver uma notificação de sucesso. Se falhar, acesse Troubleshooting.Clique em Save.
3

Configure os mapeamentos de atributos

Após salvar as credenciais, expanda a seção Mappings. O Entra ID exibe dois conjuntos de mapeamentos:
  • Provision Microsoft Entra ID Users
  • Provision Microsoft Entra ID Groups
Abra Provision Microsoft Entra ID Users e confirme que os mapeamentos de atributos correspondem ao que o ClickHouse Cloud espera.Por padrão, o Entra ID mapeia userName a partir de userPrincipalName. O importante é que userName venha do atributo que contém o mesmo endereço de e-mail usado pelo SAML SSO para autenticar os usuários — e não de um nome de atributo específico. Em alguns tenants, userPrincipalName já contém esse e-mail e nenhuma alteração é necessária; em outros, o e-mail está em mail, portanto você deve editar o mapeamento para que userName venha de mail. Para alterar a origem, clique na linha userName, defina o Source attribute como o atributo correto e salve.Defina a Matching precedence para que userName seja o principal atributo de correspondência. Você pode remover mapeamentos sem suporte; tudo que estiver fora do conjunto padrão do SCIM será ignorado pelo ClickHouse Cloud.
Use o mesmo e-mail do SAML SSOO valor atribuído a userName deve corresponder ao endereço de e-mail usado por cada usuário para fazer login via SAML SSO. O SCIM cria a conta, e o SAML a autentica. Portanto, se o userName do SCIM e o e-mail da asserção SAML não corresponderem, o SAML criará, no login, um novo usuário separado que não será gerenciado pelo SCIM — resultando em uma conta duplicada e não gerenciada. Mapeie userName a partir do atributo (userPrincipalName, mail ou outro) que contém o mesmo e-mail enviado pela sua configuração SAML.
As linhas restantes já vêm mapeadas por padrão — verifique se todas estão configuradas:Abra Provision Microsoft Entra ID Groups e confirme que displayName é mapeado para displayName e members para members — o nome de exibição do grupo é o que se vincula à Role do ClickHouse Cloud.
A capitalização de e-mails é importanteVerifique se o valor atribuído a userName e o valor do e-mail principal usam a mesma capitalização. O ClickHouse Cloud normaliza os e-mails para letras minúsculas; divergências entre os dois campos podem causar falhas de Provisioning.
4

Defina o escopo de provisionamento

Expanda a seção Settings:
  • Defina Scope como Sync only assigned users and groups. Isso limita o provisionamento aos usuários e grupos que você atribuir explicitamente ao aplicativo na próxima etapa.
  • Por enquanto, mantenha Provisioning Status como Off — você o ativará após atribuir os usuários de teste.
Clique em Save.
5

Atribuir grupos e usuários

É aqui que as funções são atribuídas automaticamente.Crie grupos no Entra ID. Para cada mapeamento de função configurado anteriormente, crie ou identifique um grupo do Entra ID com o exato mesmo nome de exibição. Por exemplo, se o mapeamento indicar ClickHouse-Admins → Admin, crie no Entra ID um grupo chamado ClickHouse-Admins.Atribua grupos ao aplicativo. No aplicativo empresarial, acesse Users and groups → Add user/group, selecione o grupo de função e atribua-o. Repita o processo para cada grupo de função. Como o escopo de Provisioning do aplicativo está definido como usuários e grupos atribuídos, apenas esses grupos (e seus membros) são provisionados.
O Provisioning de grupos exige a licença adequada do Entra IDO Provisioning de grupos (e não apenas de seus membros) exige o Microsoft Entra ID P1 ou superior. Com o Provisioning de grupos, o próprio grupo é criado no ClickHouse Cloud e vinculado à função correspondente pelo nome de exibição.
Atribua usuários. Você tem duas opções:
  • Por grupos (recomendado). Adicione usuários aos grupos do Entra ID atribuídos ao aplicativo. Eles serão provisionados no ClickHouse Cloud e receberão automaticamente a função correspondente.
  • Diretamente. Atribua usuários individuais ao aplicativo em Users and groups. Eles serão provisionados com a função padrão, a menos que também pertençam a um grupo atribuído.
A atribuição por grupos simplifica o gerenciamento contínuo — quando a função de alguém muda, basta atualizar a associação ao grupo.
6

Ativar o Provisioning

Volte para Provisioning, defina Provisioning Status como On e clique em Save.O Entra ID executa o provisionamento em intervalos regulares (aproximadamente a cada 40 minutos). Para provisionar imediatamente um usuário específico — o que é útil para testes — use Provisioning → Provision on demand, pesquise o usuário e execute uma única operação de provisionamento.

​
Teste a integração

Depois que o Provisioning estiver ativado, use Provisionar sob demanda para enviar imediatamente um ou dois usuários de teste, em vez de esperar pelo próximo ciclo. Em seguida, volte para Settings → Users and roles no ClickHouse Cloud Console para confirmar que os usuários sincronizados foram adicionados com as funções esperadas. Execute este breve plano de teste com um ou dois usuários de teste antes de atribuir toda a equipe. Se uma etapa não surtir efeito, use Provisionar sob demanda para forçar uma sincronização e consulte a seção Troubleshooting. Se alguma etapa falhar, corrija o problema subjacente antes de continuar — os sintomas geralmente se agravam.
Onde procurar erros de SCIM no Entra IDOs erros de SCIM aparecem na tela Provisioning → View provisioning logs do aplicativo (também disponível em Identity → Monitoring & health → Provisioning logs). Cada entrada mostra a solicitação, o destino e o erro retornado pelo ClickHouse Cloud literalmente — comece por ali.

​
Práticas recomendadas para produção

​
Faça a rotação de tokens regularmente

Defina um lembrete no calendário para a rotação do token SCIM. Cadência recomendada: a cada 12 meses ou imediatamente se um administrador que conhecia o token deixar a empresa. O ClickHouse Cloud permite dois tokens ativos por organização justamente para que você possa fazer a rotação sem interromper o provisionamento — gere o novo token, atualize o Token Secreto no Entra ID, confirme com Testar Conexão e, em seguida, revogue o token antigo.

​
Use grupos, não atribuições diretas

A atribuição direta de usuários ao aplicativo funciona, mas logo se torna difícil de auditar. Ao gerenciar atribuições por meio de grupos do Entra ID, as revisões de acesso e as alterações de função são feitas em um único lugar.

​
Consulte o log de auditoria

Todas as ações de SCIM — criação de usuário, desativação de usuário e atualização de perfil — são registradas no log de auditoria do ClickHouse Cloud. Consulte Registro de auditoria. Verifique o log periodicamente, especialmente após grandes picos de provisionamento.

​
Defina uma função padrão adequada

Se um usuário do Entra ID for atribuído ao aplicativo, mas não pertencer a nenhum grupo atribuído, ele será criado com a função padrão. Escolha a função mais restritiva que ainda permita que o usuário faça algo, para que configurações incorretas falhem de forma segura.

​
Evite usar SCIM e convites manuais ao mesmo tempo

Quando o SCIM estiver ativado, gerencie os membros pelo Entra ID — não envie também convites manuais aos mesmos usuários. Misturar as duas abordagens gera dúvidas sobre qual é a fonte de verdade e pode resultar em duplicidades.

​
Considere o ciclo de Provisioning

O Entra ID sincroniza em ciclos recorrentes (aproximadamente a cada 40 minutos), portanto, alterações rotineiras não são aplicadas instantaneamente. Use Provisionar sob demanda quando precisar aplicar uma alteração imediatamente e monitore os logs de Provisioning em busca de falhas persistentes.

​
Solução de problemas

  • Confirme que o SCIM está habilitado no ClickHouse Cloud Console.
  • Confirme que a URL do locatário no Entra ID corresponde exatamente à URL do endpoint SCIM exibida no Cloud Console — o ID da organização deve estar correto.
  • Confirme que o Token secreto está no formato <scim-key>:<scim-secret> — a chave (que começa com scim_), dois-pontos e, em seguida, o segredo. Não inclua espaços em branco no início ou no fim, nem o prefixo Bearer (o Entra ID o adiciona automaticamente).
  • Se você fez a rotação dos tokens, certifique-se de usar a nova chave e o novo segredo, e não o par anterior.
  • Verifique se você adicionou uma linha em Mapear funções em “Usuários e funções” para a função esperada.
  • Verifique se o nome do grupo do Entra ID corresponde exatamente ao nome do grupo SCIM no mapeamento, incluindo maiúsculas, minúsculas e hífens.
  • Se sua configuração provisiona intencionalmente alguns usuários sem grupo, confirme que a função padrão está definida.
  • Confirme que o Status de provisionamento está como On.
  • Confirme que o Escopo está definido como Sincronizar apenas usuários e grupos atribuídos e que os usuários/grupos estão realmente atribuídos ao aplicativo em Usuários e grupos.
  • Lembre-se de que o ciclo é executado aproximadamente a cada 40 minutos — use Provisionar sob demanda para testar um único usuário imediatamente.
  • O provisionamento de grupos (e não apenas de seus membros) requer o Microsoft Entra ID P1 ou superior.
Geralmente, isso é causado por diferenças de maiúsculas e minúsculas no e-mail entre o Entra ID e um convite manual anterior. Remova o usuário duplicado da lista de Membros e, em seguida, desatribua e reatribua o usuário no Entra ID (ou execute novamente Provisionar sob demanda) para provisioná-lo novamente.
O nome de exibição do grupo no Entra ID não corresponde a um mapeamento configurado no ClickHouse Cloud. Renomeie o grupo do Entra ID ou adicione um mapeamento em Mapear funções em “Usuários e funções” no painel SCIM Configuration (ou em Usuários e funções → Funções).
A desativação é propagada no próximo ciclo de provisionamento. Para forçá-la imediatamente, use Provisionar sob demanda para esse usuário. Se o usuário ainda aparecer como membro depois disso, verifique Provisionamento → Ver logs de provisionamento em busca de um erro na operação de desativação.
Verifique se você atualizou o Token secreto no aplicativo empresarial correto no Entra ID, no formato <scim-key>:<scim-secret>. Após atualizar, clique em Test Connection para confirmar. Quando o provisionamento voltar a funcionar normalmente, revogue o token antigo no ClickHouse Cloud Console.
Os tokens não podem ser recuperados. Em Configurações da organização → Configurações de SAML e SCIM → SCIM Configuration no ClickHouse Cloud Console, revogue o token perdido, gere um novo e atualize o Token secreto no Entra ID.

​
Perguntas frequentes

Sim. O SCIM cria as contas de usuário, mas o ClickHouse Cloud as autentica por meio do SAML. Configure primeiro o SAML SSO.
Sim. Com o SSO baseado em SAML, um único aplicativo empresarial do Entra ID gerencia tanto o single sign-on quanto o provisionamento SCIM.
O Entra ID autentica enviando o Secret Token no cabeçalho Authorization: Bearer. O endpoint SCIM do ClickHouse Cloud espera que o valor do bearer seja a chave e o Secret do token, unidos por dois-pontos.
O Entra ID realiza o provisionamento em ciclos recorrentes de aproximadamente 40 minutos. Para uma atualização imediata, use Provisionar sob demanda para o usuário específico.
Abra um ticket de suporte no ClickHouse Cloud Console (Ajuda → Entrar em contato com o suporte) e inclua:
  • o ID da sua organização,
  • o nome (e o ID do objeto) do seu aplicativo empresarial do Entra ID e
  • uma captura de tela da entrada com falha em Provisioning → View provisioning logs.
Última modificação em 14 de agosto de 2026