Skip to main content
O ClickHouse Cloud oferece suporte a SCIM 2.0 (System for Cross-domain Identity Management) para automatizar o gerenciamento do ciclo de vida de usuários e grupos. Depois de se conectar ao seu provedor de identidade, cada usuário que você atribuir ao aplicativo ClickHouse Cloud é criado automaticamente na sua organização com a função correta, as atualizações de perfil são propagadas automaticamente e, ao remover um usuário do seu IdP, o acesso dele é revogado — sem convites manuais, sem contas órfãs. Este guia mostra como configurar o provisionamento SCIM de ponta a ponta com o Okta. O endpoint SCIM do ClickHouse Cloud segue o SCIM 2.0 (RFC 7644), mas a autenticação só tem suporte via Basic Auth, e o Okta é o único provedor de identidade com o qual testamos. Outros IdPs SCIM 2.0 podem funcionar se conseguirem se autenticar usando Basic Auth, mas no momento não têm suporte oficial.

​
Antes de começar

Você precisará de:
  • A função Admin na sua organização do ClickHouse Cloud.
  • SAML SSO já configurado entre seu IdP e o ClickHouse Cloud. O SCIM cria as contas de usuário; essas contas fazem login por SAML, então o SSO precisa estar funcionando antes.
  • Acesso de superadministrador ao seu tenant do Okta, com permissão para instalar aplicativos e configurar o provisionamento.
  • Uma lista das funções que você quer atribuir por meio do SCIM (por exemplo: Admins, Developers, Read-only). Defina isso com antecedência — você criará grupos correspondentes no Okta.

​
Como o SCIM funciona com o ClickHouse Cloud

  1. Um administrador no Okta atribui um usuário — diretamente ou por meio de um grupo — ao aplicativo ClickHouse Cloud.
  2. O Okta faz uma chamada ao endpoint SCIM do ClickHouse Cloud via HTTPS, autenticada com um 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 Okta.
  4. O usuário acessa o ClickHouse Cloud por meio do seu fluxo SAML SSO existente.
  5. Alterações de profile, mudanças de grupo e desativação no Okta são propagadas automaticamente para o ClickHouse Cloud.

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

1

Ative o SCIM

Faça login no ClickHouse Cloud Console como administrador da organização e abra Configurações da organização → SAML and SCIM settings → SCIM Configuration.Acesse a guia de configuração do SCIM em Configurações da organizaçãoClique em Enable SCIM. O SCIM é liberado assim que o SAML SSO é conectado — se a opção estiver desabilitada, conclua primeiro a configuração do SAML.Ative Enable SCIMUma URL do endpoint do SCIM é gerada, no formato:
Copie-a — você vai colá-la no Okta depois.
2

Gere um token de acesso do SCIM

Localize a seção Create an API 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 ao mesmo tempo, para que você possa fazer a rotação sem interrupção: gere o novo token, atualize o Okta para usá-lo, confirme que o provisionamento continua funcionando e então revogue o token antigo.
Clique em Generate key. O token é exibido uma única vez, como uma chave (com prefixo scim_) e um segredo. Copie ambos imediatamente e armazene-os em um gerenciador de segredos seguro — eles não poderão ser recuperados depois. Se você os perder, revogue o token e gere um novo.Gere uma nova chave de API do SCIM
3

Defina 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 do SCIM são associados às funções do ClickHouse Cloud pelo nome, com algumas regras importantes:
  • Você não pode mapear um grupo SCIM para uma função predefinida do sistema. Os mapeamentos do SCIM se aplicam apenas a funções personalizadas. Se você precisar expor uma capacidade em nível de sistema por meio do SCIM, crie uma função personalizada que reúna 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 fará a vinculação automaticamente — não é 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, em seguida, defina o campo SCIM group com o nome do grupo SCIM ao qual ela deve se associar.
  • Grupos não mapeados criam novas funções. Se o Okta 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 aplicativo ClickHouse Cloud no Okta

1

Abra o aplicativo do ClickHouse Cloud no Okta

No Okta Admin Console, vá para Applications → Applications e procure o aplicativo que você criou ao configurar o SAML SSO para o ClickHouse Cloud. Abra-o.Se você ainda não criou o aplicativo SAML, siga primeiro o guia de configuração do SAML SSO — o provisionamento SCIM é configurado no mesmo aplicativo.Na guia General, localize a seção App Settings e clique em Edit. Em Provisioning, selecione SCIM e clique em Save.Defina o modo de provisionamento como SCIM nas configurações do aplicativo no OktaO aplicativo agora exibe uma guia Provisioning.A guia Provisioning agora aparece no aplicativo
2

Conecte o Okta ao endpoint SCIM

Abra a aba Provisioning do aplicativo e clique em Edit. Preencha o formulário:
  • URL base do conector SCIM — a URL do endpoint SCIM mencionada anteriormente.
  • Campo de identificador exclusivo para usuários — userName.
  • Ações de provisionamento compatíveis — selecione todas as opções a seguir:
    • Importar novos usuários e atualizações de perfil
    • Enviar novos usuários
    • Enviar atualizações de perfil
    • Enviar grupos
    • Importar grupos
  • Modo de autenticação — Basic Auth.
    • Nome de usuário — a chave do token SCIM (ela começa com scim_).
    • Senha — o segredo do token SCIM. Insira a URL do conector SCIM e defina o identificador exclusivo como userName Insira as credenciais da API para autenticação SCIM
Clique em Test Connector Configuration. Você deverá ver uma confirmação em verde. Se falhar, vá para Solução de problemas.Teste a conexão SCIMClique em Save.
3

Configurar o comportamento do Provisioning

Ainda na aba Provisioning, clique em To App na barra lateral esquerda. Clique em Edit e ative:Ative as ações de Provisioning do SCIM para usuáriosClique em Save e, em seguida, volte para as abas Sign On / Provisioning do aplicativo para confirmar que as configurações foram aplicadas.Salve as configurações de Provisioning e volte para a aba Sign On
4

Mapear atributos do usuário

O Okta e o ClickHouse Cloud precisam estar alinhados sobre como os campos do usuário são mapeados. Na aba Provisioning, clique em To App e revise os Attribute Mappings da sua aplicação. Os padrões da aplicação SAML do Okta geralmente são suficientes — confira a tabela abaixo:Você pode adicionar atributos opcionais, como departamento, gerente e localidade — o ClickHouse Cloud os armazena no perfil do usuário, mas atualmente não os usa para permissões. Tudo o que estiver fora do conjunto padrão do SCIM é ignorado pelo ClickHouse Cloud.
Maiúsculas e minúsculas no e-mail importamCertifique-se de que userName e email no Okta usem a mesma capitalização. O ClickHouse Cloud normaliza os e-mails para minúsculas; divergências entre os dois campos podem causar falhas nos testes.
5

Enviar grupos e atribuir usuários

É aqui que as funções são aplicadas automaticamente.Crie grupos no Okta. Para cada mapeamento de função que você configurou anteriormente, crie ou identifique um grupo no Okta com o mesmo nome de exibição exato. Por exemplo, se o seu mapeamento diz ClickHouse-Admins → Admin, crie um grupo chamado ClickHouse-Admins no Okta.Crie um novo grupo no OktaAbra o grupo que você acabou de criar e clique em Assign people para adicionar um membro.Clique em Assign people no grupoAtribua o usuário ao grupoEm seguida, associe o aplicativo SCIM ao mesmo grupo para que a associação à função e o acesso ao aplicativo permaneçam sincronizados.Atribua o aplicativo ao grupoEnvie os grupos. Na guia Provisioning do aplicativo, clique em Push Groups → Find groups by name, procure seu grupo e clique em Save. Repita o processo para cada grupo de função. Cada um deverá exibir Push Status como Active (Pushed) depois de provisionado.Configure o Group Push por nome na guia Push Groups do aplicativoAtribua usuários. Você tem duas opções:
  • Via grupos (recomendado). Adicione usuários aos grupos do Okta que você acabou de enviar. Eles serão provisionados no ClickHouse Cloud e receberão automaticamente a função correspondente.
  • Diretamente. Na guia Assignments do aplicativo, clique em Assign → Assign to People e selecione usuários individuais. Eles serão provisionados com a função padrão, a menos que também estejam em um grupo enviado.
A atribuição baseada em grupos é mais adequada para o gerenciamento contínuo — quando a função de alguém muda, basta atualizar a associação ao grupo.

​
Teste a integração

Depois que o Provisioning estiver configurado, volte para Configurações → Users and roles no ClickHouse Cloud Console para confirmar que os usuários sincronizados apareceram com as funções esperadas. Verifique a sincronização de usuários em Users and roles Siga este breve plano de teste com um ou dois usuários de teste antes de atribuir o acesso à equipe inteira. Cada etapa deve ser concluída em poucos segundos; se isso não acontecer, verifique a fila de tarefas do Okta e a seção de Solução de problemas. Se alguma etapa falhar, corrija o problema subjacente antes de continuar — os sintomas normalmente se acumulam.
Onde procurar erros de SCIM no OktaOs erros de SCIM aparecem em Relatórios → Log do sistema, filtrados pelo seu aplicativo, e na tela Provisioning → View Logs do aplicativo. A mensagem de erro retornada pelo ClickHouse Cloud é exibida exatamente como foi retornada — comece por ela.

​
Boas práticas para produção

​
Faça a roação dos tokens regularmente

Defina um lembrete no calendário para a rotação do token SCIM. Cadência recomendada: a cada 12 meses ou imediatamente sempre que um administrador que conhecia o token sair da empresa. O ClickHouse Cloud permite dois tokens ativos por organização justamente para que você possa fazer a rotação sem interromper o provisionamento.

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

A atribuição direta de usuários ao aplicativo funciona, mas rapidamente fica difícil de auditar. Fazer a atribuição por meio de grupos do Okta significa que as revisões de acesso e as mudanças de função acontecem em um só lugar.

​
Revise o log de auditoria

Toda ação do SCIM — usuário criado, usuário desativado, perfil atualizado — é registrada no log de auditoria do ClickHouse Cloud. Consulte Audit logging. Verifique o log periodicamente, especialmente após grandes ondas de provisionamento.

​
Defina uma função padrão adequada

Se um usuário do Okta for atribuído ao aplicativo, mas não estiver em nenhum grupo sincronizado, ele será criado com a Função padrão. Escolha a função mais restritiva que ainda permita que o usuário faça alguma coisa, para que erros de configuração falhem de forma segura.

​
Evite usar SCIM e convites manuais ao mesmo tempo

Depois que o SCIM estiver ativado, gerencie a associação pelo Okta — não envie também convites manuais para os mesmos usuários. Misturar os dois caminhos gera confusão sobre qual é a fonte oficial e pode produzir duplicatas.

​
Monitore tarefas de provisionamento com falha

O Okta tenta novamente chamadas de provisionamento com falha, mas acaba movendo-as para a fila Tasks. Adicione essa fila aos dashboards que sua equipe de TI já monitora ou use o webhook do Okta ou alertas por e-mail para sinalizar falhas persistentes.

​
Solução de problemas

  • Confirme se o SCIM está ativado no ClickHouse Cloud Console.
  • Confirme se a base URL no Okta corresponde exatamente à URL do endpoint do SCIM mostrada no Cloud Console — o ID da organização deve estar correto.
  • Confirme se a chave e o segredo do token foram colados sem espaços em branco no início ou no fim.
  • Se você rotacionou tokens, verifique se está usando a nova chave e o novo segredo, e não o par anterior.
  • Verifique se você adicionou uma linha em Map roles in “Users and roles” para a função esperada.
  • Verifique se o nome do grupo no Okta corresponde exatamente ao nome do grupo SCIM no mapeamento, incluindo maiúsculas, minúsculas e hífens.
  • Se, por design, alguns usuários forem provisionados intencionalmente sem grupo, confirme se a função padrão está definida.
Isso geralmente é causado por diferenças entre maiúsculas e minúsculas no email entre o Okta e um convite manual anterior. Remova a duplicata da lista Membro e, em seguida, desassocie e reassocie o usuário no Okta para provisioná-lo novamente.
O nome do grupo no Okta não corresponde a um mapeamento configurado no ClickHouse Cloud. Renomeie o grupo no Okta ou adicione um mapeamento em Map roles in “Users and roles” no painel SCIM Configuration (ou em Users and roles → Roles).
O Okta pode levar até um minuto para propagar uma desativação. Se o usuário ainda aparecer como membro após vários minutos, verifique em Provisioning → View Logs no Okta se há algum erro na tarefa de desativação.
Verifique se você atualizou as credenciais na mesma aplicação SCIM no Okta. Depois da atualização, clique em Test Connector Configuration para confirmar. Quando o provisionamento voltar a ficar verde, revogue o token antigo no ClickHouse Cloud Console.
Os tokens não podem ser recuperados. Em Organization settings → SAML and SCIM settings → SCIM Configuration no ClickHouse Cloud Console, revogue o token perdido, gere um novo e depois atualize as credenciais no Okta.

​
Perguntas frequentes

Sim. O SCIM cria as contas de usuário, mas o ClickHouse Cloud faz a autenticação delas por meio do SAML. Configure primeiro o SAML SSO.
Oficialmente, não — o Okta é o único IdP que testamos e ao qual damos suporte hoje. O endpoint segue o SCIM 2.0 (RFC 7644), mas a autenticação é restrita a Basic Auth, então qualquer IdP que não consiga se autenticar via Basic Auth não funcionará. Outros IdPs SCIM 2.0 compatíveis com Basic Auth podem funcionar na prática, mas não oferecemos nenhuma garantia.
A maioria das operações é propagada em poucos segundos. Alterações em massa (envio de grupos grandes) podem levar mais tempo, dependendo do tamanho, mas o Okta tenta novamente automaticamente em caso de erros transitórios.
Sim — instale o aplicativo uma vez por organização, cada uma com seu próprio URL do endpoint do SCIM e token. Envie os mesmos grupos do Okta para cada aplicativo, conforme necessário.
Abra um ticket de suporte no ClickHouse Cloud Console (Help → Contact support) e inclua:
  • o ID da sua organização,
  • o ID do seu aplicativo no Okta, e
  • uma captura de tela da task ou do teste que falhou nos logs do Okta.
Última modificação em 24 de julho de 2026