Provisionamento SCIM com o Microsoft Entra ID

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:

https://api.clickhouse.cloud/v1/organizations/<your-org-id>/scim

Copie-a — você a inserirá posteriormente no Entra ID como a Tenant URL.

Localize a seção Generate new key e escolha uma data de expiração.

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:

<scim-key>:<scim-secret>

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.

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.

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.

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.

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.

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.

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.

É 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.

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.

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.