> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Provisionamento SCIM com o Microsoft Entra ID

> Como configurar o provisionamento SCIM entre o Microsoft Entra ID e o ClickHouse Cloud

export const EnterprisePlanFeatureBadge = ({feature = 'Este recurso', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Recurso do plano Enterprise
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'estão disponíveis' : 'está disponível'} no plano Enterprise. {support ? `Entre em contato com o suporte para habilitar este recurso.` : 'Para fazer o upgrade, acesse a página de planos no Cloud Console.'}</p>
            </div>
        </div>;
};

<EnterprisePlanFeatureBadge feature="SCIM" />

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.

<Tip>
  **Usa o Okta?**

  Se o seu provedor de identidade for o Okta, siga o guia [Provisionamento SCIM com Okta](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/scim-setup). O lado do ClickHouse Cloud é idêntico; apenas a configuração do IdP é diferente.
</Tip>

<div id="before-you-begin">
  ## Antes de começar
</div>

Você precisará de:

* A role **Admin** na sua organização do ClickHouse Cloud.
* [SAML SSO](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/saml-sso-setup) 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.

<div id="how-scim-works">
  ## Como o SCIM funciona com o ClickHouse Cloud
</div>

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.

<div id="configure-clickhouse-cloud">
  ## Configure o SCIM na sua organização do ClickHouse Cloud
</div>

<Steps>
  <Step title="Habilitar SCIM" id="enable-scim-provisioning">
    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:

    ```plaintext theme={null}
    https://api.clickhouse.cloud/v1/organizations/<your-org-id>/scim
    ```

    Copie-a — você a inserirá posteriormente no Entra ID como a **Tenant URL**.
  </Step>

  <Step title="Gerar um token de acesso SCIM" id="generate-scim-token">
    Localize a seção `Generate new key` e escolha uma data de expiração.

    <Tip>
      **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 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.
    </Tip>

    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:

    ```plaintext theme={null}
    <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.
  </Step>

  <Step title="Definir o mapeamento de função" id="define-role-mapping">
    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.
  </Step>
</Steps>

<div id="configure-entra">
  ## Configure o provisioning no Microsoft Entra ID
</div>

<Steps>
  <Step title="Abra seu aplicativo Enterprise do ClickHouse Cloud" id="open-clickhouse-cloud-app">
    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](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/saml-sso-setup#azure-enterprise-app) — com SSO baseado em SAML, a mesma aplicação empresarial é usada tanto para single sign-on quanto para provisionamento SCIM.
  </Step>

  <Step title="Defina o modo de Provisioning e as credenciais" id="connect-entra-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](#troubleshooting).

    Clique em `Save`.
  </Step>

  <Step title="Configure os mapeamentos de atributos" id="map-user-attributes">
    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.

    <Warning>
      **Use o mesmo e-mail do SAML SSO**

      O 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.
    </Warning>

    As linhas restantes já vêm mapeadas por padrão — verifique se todas estão configuradas:

    | Atributo do Microsoft Entra ID | Atributo do ClickHouse Cloud (SCIM) | Obrigatório                                  |
    | ------------------------------ | ----------------------------------- | -------------------------------------------- |
    | `mail`                         | `emails[type eq "work"].value`      | **Sim** — deve corresponder a `userName`     |
    | `givenName`                    | `name.givenName`                    | Recomendado                                  |
    | `surname`                      | `name.familyName`                   | Recomendado                                  |
    | `displayName`                  | `displayName`                       | Recomendado — exibido na ClickHouse Cloud UI |
    | `Switch([IsSoftDeleted], ...)` | `active`                            | **Sim** — controla a desativação             |

    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.

    <Warning>
      **A capitalização de e-mails é importante**

      Verifique 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.
    </Warning>
  </Step>

  <Step title="Defina o escopo de provisionamento" id="configure-provisioning-behavior">
    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`.
  </Step>

  <Step title="Atribuir grupos e usuários" id="push-groups-and-assign-users">
    É 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.

    <Note>
      **O Provisioning de grupos exige a licença adequada do Entra ID**

      O 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.
    </Note>

    **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.
  </Step>

  <Step title="Ativar o Provisioning" id="turn-on-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.
  </Step>
</Steps>

<div id="test-the-integration">
  ## Teste a integração
</div>

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](#troubleshooting).

| # | Ação no Entra ID                                                                                | Resultado esperado no ClickHouse Cloud                                |
| - | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 1 | Adicione um usuário de teste ao grupo `ClickHouse-Admins` e execute **Provisionar sob demanda** | O usuário aparece em **Settings → Members** com a função **Admin**    |
| 2 | O usuário de teste faz login no ClickHouse Cloud via SSO                                        | Ele acessa o dashboard com permissões de administrador                |
| 3 | Atualize o nome do usuário no Entra ID e reprovisione                                           | O nome atualizado aparece em **Members**                              |
| 4 | Mova o usuário de `ClickHouse-Admins` para `ClickHouse-Read-only` e reprovisione                | A função do usuário muda para **Read-only**                           |
| 5 | Remova a atribuição do usuário ao aplicativo (ou desative a conta no Entra ID)                  | O usuário é removido da organização; novas tentativas de login falham |

Se alguma etapa falhar, corrija o problema subjacente antes de continuar — os sintomas geralmente se agravam.

<Tip>
  **Onde procurar erros de SCIM no Entra ID**

  Os 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.
</Tip>

<div id="best-practices">
  ## Práticas recomendadas para produção
</div>

<div id="rotate-tokens">
  ### Faça a rotação de tokens regularmente
</div>

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.

<div id="use-groups">
  ### Use grupos, não atribuições diretas
</div>

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.

<div id="review-audit-log">
  ### Consulte o log de auditoria
</div>

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](/docs/pt-BR/products/cloud/reference/security/audit-logging). Verifique o log periodicamente, especialmente após grandes picos de provisionamento.

<div id="default-role">
  ### Defina uma função padrão adequada
</div>

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.

<div id="avoid-manual-invites">
  ### Evite usar SCIM e convites manuais ao mesmo tempo
</div>

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.

<div id="account-for-provisioning-cycle">
  ### Considere o ciclo de Provisioning
</div>

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.

<div id="troubleshooting">
  ## Solução de problemas
</div>

<AccordionGroup>
  <Accordion title="&#x22;Testar conexão&#x22; falha no Entra ID" id="test-credentials-fails">
    * 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.
  </Accordion>

  <Accordion title="Os usuários são criados, mas não têm permissões" id="users-no-permissions">
    * 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.
  </Accordion>

  <Accordion title="Usuários ou grupos não estão sendo provisionados" id="nothing-provisioning">
    * 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.
  </Accordion>

  <Accordion title="Usuário duplicado na lista de membros" id="duplicate-user">
    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.
  </Accordion>

  <Accordion title="O provisionamento de grupo falha devido a uma incompatibilidade de nome" id="group-display-name">
    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**).
  </Accordion>

  <Accordion title="Usuários desativados ainda aparecem como membros" id="deactivated-users-remaining">
    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.
  </Accordion>

  <Accordion title="Fiz a rotação do token SCIM e agora o Entra ID está falhando" id="token-rotation-issue">
    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.
  </Accordion>

  <Accordion title="Perdi o token SCIM" id="lost-token">
    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.
  </Accordion>
</AccordionGroup>

<div id="faq">
  ## Perguntas frequentes
</div>

<AccordionGroup>
  <Accordion title="Preciso configurar o SAML SSO antes de usar o SCIM?">
    Sim. O SCIM cria as contas de usuário, mas o ClickHouse Cloud as autentica por meio do SAML. Configure primeiro o [SAML SSO](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/saml-sso-setup).
  </Accordion>

  <Accordion title="Posso usar o mesmo aplicativo empresarial para SAML e SCIM?">
    Sim. Com o SSO baseado em SAML, um único aplicativo empresarial do Entra ID gerencia tanto o single sign-on quanto o provisionamento SCIM.
  </Accordion>

  <Accordion title="Por que o Secret Token é formatado como key:secret?">
    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.
  </Accordion>

  <Accordion title="Em quanto tempo as alterações no Entra ID aparecem no ClickHouse Cloud?">
    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.
  </Accordion>

  <Accordion title="Onde posso obter ajuda se tiver dificuldades?">
    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**.
  </Accordion>
</AccordionGroup>