Pular para o conteúdo principal
O provisionamento SCIM está em prévia privada.
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 Organization settings → SAML and SCIM settings → SCIM Configuration.Clique 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.Uma 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ção. Recomendamos 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.
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.O aplicativo agora exibe uma guia Provisioning.
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.
Clique em Test Connector Configuration. Você deverá ver uma confirmação em verde. Se falhar, vá para Solução de problemas.Clique 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:Clique em Save e, em seguida, volte para as abas Sign On / Provisioning do aplicativo para confirmar que as configurações foram aplicadas.
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 importam. Certifique-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.Abra o grupo que você acabou de criar e clique em Assign people para adicionar um membro.Em seguida, associe o aplicativo SCIM ao mesmo grupo para que a associação à função e o acesso ao aplicativo permaneçam sincronizados.Envie 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.Atribua 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 → Usuários e funções no Console do ClickHouse Cloud para confirmar que os usuários sincronizados apareceram com as funções esperadas. 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 Okta. Os 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 rotaçã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

​
”Test connector configuration” falha no Okta

  • Confirme se o SCIM está habilitado no Console do ClickHouse Cloud.
  • Confirme se a URL base no Okta corresponde exatamente ao URL do endpoint SCIM exibido no Console do ClickHouse Cloud — 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 os tokens, certifique-se de que está usando a nova chave e o novo segredo, não o par anterior.

​
Os usuários são criados, mas não têm permissões

  • Verifique se você adicionou uma linha em Map roles in “Users and roles” para a role 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 a sua configuração provisiona intencionalmente alguns usuários sem grupo, confirme se a Default role está definida.

​
Usuário duplicado na lista de membros

Geralmente isso é causado por inconsistência no uso de maiúsculas e minúsculas no e-mail entre o Okta e um convite manual anterior. Remova o usuário duplicado da lista de Membros e, em seguida, cancele a atribuição e atribua novamente o usuário no Okta para provisioná-lo do zero.

​
O envio do grupo falha com “displayName not recognised”

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 Mapear funções em “Users and roles” no painel de Configuração SCIM (ou em Users and roles → Roles).

​
Usuários desativados ainda aparecem como membros

O Okta pode levar até um minuto para processar a 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.

​
Fiz a rotação do token SCIM e agora o Okta está falhando

Verifique se você atualizou as credenciais no mesmo aplicativo SCIM no Okta. Após a atualização, clique em Test Connector Configuration para confirmar. Quando o Provisioning voltar a ficar verde, revogue o token antigo no ClickHouse Cloud Console.

​
Perdi o token do SCIM

Não é possível recuperar tokens. No ClickHouse Cloud Console, em Configurações da organização → Configurações de SAML e SCIM → Configuração do SCIM, revogue o token perdido e gere um novo. Em seguida, atualize as credenciais no Okta.

​
Perguntas frequentes

Preciso de SAML SSO para poder usar o SCIM? 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. O SCIM funciona com Microsoft Entra ID, OneLogin ou outros IdPs SCIM 2.0? 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. Em quanto tempo as alterações no Okta aparecem no ClickHouse Cloud? 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. Posso provisionar várias organizações do ClickHouse Cloud a partir de um único tenant do Okta? Sim — instale o aplicativo uma vez por organização, cada uma com seu próprio endpoint URL do SCIM e token. Envie os mesmos grupos do Okta para cada aplicativo, conforme necessário. Onde obtenho ajuda se não conseguir avançar? 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 12 de junho de 2026