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

# Configuração de SAML SSO

> Como configurar o SAML SSO no 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>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<EnterprisePlanFeatureBadge feature="SAML SSO" />

O ClickHouse Cloud oferece suporte a single sign-on (SSO) via Security Assertion Markup Language (SAML). Isso permite que você faça login com segurança na sua organização do ClickHouse Cloud autenticando-se com seu provedor de identidade (IdP).

Oferecemos suporte a SSO iniciado pelo provedor de serviço, várias organizações usando conexões separadas e provisionamento just-in-time. Também oferecemos suporte ao [provisionamento SCIM](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/scim-setup) em prévia privada, com suporte para Okta. Ainda não oferecemos suporte a mapeamento de atributos.

Os clientes que habilitam integrações SAML também podem definir a função padrão que será atribuída a novos usuários e ajustar as configurações de tempo limite da sessão.

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

Você precisará de permissões de administrador no seu IdP, da capacidade de adicionar um registro TXT às configurações de DNS do seu domínio e da função **Admin** na sua organização no ClickHouse Cloud. Recomendamos configurar um **link direto para a sua organização** além da sua conexão SAML para simplificar o processo de login. Cada IdP lida com isso de forma diferente. Continue lendo para saber como fazer isso no seu IdP.

<div id="how-it-works">
  ## Como funciona
</div>

Depois que o SAML SSO estiver configurado, os usuários farão login por meio de um fluxo iniciado pelo provedor de serviço:

1. O usuário acessa `https://console.clickhouse.cloud` e informa seu endereço de email (ou usa o link direto da sua organização).
2. O ClickHouse Cloud o redireciona para seu provedor de identidade para autenticação.
3. Se a autenticação for bem-sucedida, o provedor de identidade o redireciona de volta ao ClickHouse Cloud.
4. O ClickHouse Cloud faz login do usuário, provisionando a conta just-in-time no primeiro acesso e atribuindo a função padrão configurada.

O restante deste guia aborda a configuração única.

<div id="how-to-configure-your-idp">
  ## Como configurar seu IdP
</div>

<Steps>
  <Step title="Acesse as configurações da organização" id="access-organization-settings">
    Clique no nome da sua organização no canto inferior esquerdo e selecione Detalhes da organização.
  </Step>

  <Step title="Ative o logon único SAML" id="enable-saml-sso">
    Clique no botão de alternância ao lado de `Enable SAML single sign-on`. Deixe esta tela aberta, pois você precisará consultá-la várias vezes durante o processo de configuração.

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-1.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=37bc32dd8c704500899a452bc388adcc" size="lg" alt="Iniciar a configuração do SAML" force width="2136" height="1334" data-path="images/cloud/security/saml-self-serve-1.webp" />
  </Step>

  <Step title="Crie um aplicativo no seu provedor de identidade" id="create-idp-application">
    Crie um aplicativo no seu provedor de identidade e copie os valores da tela `Enable SAML single sign-on` para a configuração do seu provedor de identidade. Para mais informações sobre esta etapa, consulte abaixo as instruções do seu provedor de identidade específico.

    * [Okta](#okta)
    * [Google](#google)
    * [Azure (Microsoft)](#azure)
    * [Duo](#duo)

    <Tip>
      O ClickHouse não oferece suporte a login iniciado pelo provedor de identidade. Para facilitar o acesso dos seus usuários ao ClickHouse Cloud, crie um favorito para eles usando este formato de URL de login: `https://console.clickhouse.cloud/?connection={orgId}`, em que `{orgId}` é o Organization ID na página de detalhes da organização.
    </Tip>

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-2.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=b7667eb8cf23219747842818880e3007" size="lg" alt="Criar aplicativo no provedor de identidade" force width="2952" height="1744" data-path="images/cloud/security/saml-self-serve-2.webp" />
  </Step>

  <Step title="Adicione a URL de metadados à sua configuração SAML" id="add-metadata-url">
    Obtenha a `Metadata URL` do seu provedor SAML. Volte ao ClickHouse Cloud, clique em `Next: Provide metadata URL` e cole a URL na caixa de texto.

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-3.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=b6e65734eba7b75333347dcee2e56498" size="lg" alt="Adicionar URL de metadados" force width="2962" height="1536" data-path="images/cloud/security/saml-self-serve-3.webp" />
  </Step>

  <Step title="Obtenha o código de verificação do domínio" id="get-domain-verification-code">
    Clique em `Next: Verify your domains`. Insira seu domínio na caixa de texto e clique em `Check domain`. O sistema gerará um código de verificação aleatório para adicionar a um registro TXT no seu provedor de DNS.

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-4.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=5c698b22fd991c2af8cae28135f58092" size="lg" alt="Adicionar domínio para verificar" force width="2954" height="1530" data-path="images/cloud/security/saml-self-serve-4.webp" />
  </Step>

  <Step title="Verifique seu domínio" id="verify-your-domain">
    Crie um registro TXT no seu provedor de DNS. Copie `TXT record name` para o campo Nome do registro TXT no seu provedor de DNS. Copie `Value` para o campo Conteúdo no seu provedor de DNS. Clique em `Verify and Finish` para concluir o processo.

    <Note>
      Pode levar alguns minutos para que o registro DNS seja atualizado e validado. Você pode sair da página de configuração e voltar mais tarde para concluir o processo sem precisar recomeçar. O valor de verificação é válido por 48 horas a partir do momento em que é gerado pela primeira vez.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-self-serve-5.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=9ef00f036771c1f1f2d7647b39c7c391" size="lg" alt="Verifique seu domínio" force width="2962" height="1594" data-path="images/cloud/security/saml-self-serve-5.webp" />
  </Step>

  <Step title="Atualizar a função padrão e o tempo limite da sessão" id="update-defaults">
    Quando a configuração do SAML estiver concluída, você poderá definir quais funções padrão serão atribuídas a todos os usuários ao fazer login e também ajustar as configurações de tempo limite da sessão. Para ver uma lista das funções de sistema disponíveis que podem ser atribuídas, consulte [Funções e permissões do Console](/docs/pt-BR/products/cloud/reference/security/console-roles).
  </Step>

  <Step title="Configure o seu usuário Admin" id="configure-your-admin-user">
    <Note>
      Os usuários configurados com um método de authentication diferente serão mantidos até que um Admin da sua organização os remova.
    </Note>

    Para atribuir o seu primeiro usuário Admin via SAML:

    1. Saia do [ClickHouse Cloud](https://console.clickhouse.cloud).
    2. No seu provedor de identidade, atribua o usuário Admin aos aplicativos do ClickHouse.
    3. Peça ao usuário para fazer login em [https://console.clickhouse.cloud/?connection=\{orgId}](https://console.clickhouse.cloud/?connection=\{orgId}) (URL de atalho). Isso pode ser feito por meio de um favorito que você criou nas etapas anteriores. O usuário não aparecerá no ClickHouse Cloud até fazer o primeiro login.
    4. Se a função SAML padrão for diferente de Admin, talvez o usuário precise sair e entrar novamente com o método de authentication original para atualizar a função do novo usuário SAML.
       * Para contas de e-mail + senha, use `https://console.clickhouse.cloud/?with=email`.
       * Para logins sociais, clique no botão apropriado (**Continuar com Google** ou **Continuar com Microsoft**)

    <Note>
      `email` em `?with=email` acima é o valor literal do parâmetro, não um espaço reservado
    </Note>

    5. Saia mais uma vez e entre novamente pela URL de atalho para concluir a última etapa abaixo.

    <Tip>
      Para reduzir o número de etapas, você pode definir inicialmente a sua função SAML padrão como `Admin`. Quando o Admin for atribuído no seu provedor de identidade e fizer login pela primeira vez, ele poderá alterar a função padrão para outro valor.
    </Tip>
  </Step>

  <Step title="Remover outros métodos de autenticação" id="remove-other-auth-methods">
    Remova todos os usuários que estejam usando um método que não seja SAML para concluir a integração e restrinja o acesso apenas aos usuários provenientes da conexão com seu provedor de identidade.
  </Step>
</Steps>

<div id="configure-idp">
  ### Configure o seu provedor de identidade
</div>

<Tabs>
  <Tab title="Okta" id="okta">
    Você configurará duas App Integrations no Okta para cada organização do ClickHouse: um app SAML e um bookmark para o seu link direto.

    #### Crie um grupo para gerenciar o acesso

    1. Faça login na sua instância do Okta como **Administrator**.
    2. Selecione **Groups** à esquerda.
    3. Clique em **Add group**.
    4. Insira um nome e uma descrição para o grupo. Esse grupo será usado para manter os usuários sincronizados entre o app SAML e o app de bookmark relacionado.
    5. Clique em **Save**.
    6. Clique no nome do grupo que você criou.
    7. Clique em **Assign people** para atribuir os usuários que você deseja que tenham acesso a esta organização do ClickHouse.

    #### Crie um app de bookmark para permitir que os usuários façam login de forma transparente

    1. Selecione **Applications** à esquerda e, em seguida, selecione o subtítulo **Applications**.
    2. Clique em **Browse App Catalog**.
    3. Pesquise por **Bookmark App** e selecione-o.
    4. Clique em **Add integration**.
    5. Escolha um rótulo para o app.
    6. Insira a URL como `https://console.clickhouse.cloud/?connection={organizationid}`
    7. Vá para a aba **Assignments** e adicione o grupo que você criou acima.

    #### Crie um app SAML para habilitar a conexão

    1. Selecione **Applications** à esquerda e, em seguida, selecione o subtítulo **Applications**.

    2. Clique em **Create App Integration**.

    3. Selecione SAML 2.0 e clique em Next.

    4. Insira um nome para seu aplicativo, marque a caixa ao lado de **Don't display application icon to users** e clique em **Next**.

    5. Use os valores a seguir para preencher a tela de configurações de SAML.

       | Campo                          | Valor                                         |
       | ------------------------------ | --------------------------------------------- |
       | Single Sign On URL             | Copie a Single Sign-On URL do console         |
       | Audience URI (SP Entity ID)    | Copie o Service Provider Entity ID do console |
       | Default RelayState             | Deixe em branco                               |
       | Name ID format                 | Unspecified                                   |
       | Application username           | Email                                         |
       | Update application username on | Create and update                             |

    6. Insira a seguinte Attribute Statement.

       | Name  | Name format | Value      |
       | ----- | ----------- | ---------- |
       | email | Basic       | user.email |

    7. Clique em **Next**.

    8. Insira as informações solicitadas na tela Feedback e clique em **Finish**.

    9. Vá para a aba **Assignments** e adicione o grupo que você criou acima.

    10. Na aba **Sign On** do seu novo app, clique no botão **Copy metadata URL**.

    11. Retorne para [Add the metadata URL to your SAML configuration](#add-metadata-url) para continuar o processo.
  </Tab>

  <Tab title="Google" id="google">
    Você configurará um app SAML no Google para cada organização e deverá fornecer aos usuários o link direto (`https://console.clickhouse.cloud/?connection={organizationId}`) para que o adicionem aos favoritos ao usar multi-org SSO.

    #### Criar um app da web do Google

    1. Acesse o console do Google Admin (admin.google.com).

           <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-google-app.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=85e5ddbddb3a53903268e8bb4595863d" size="md" alt="App SAML do Google" force width="1224" height="608" data-path="images/cloud/security/saml-google-app.webp" />

    2. Clique em **Apps** e, em seguida, em **Web and mobile apps** à esquerda.

    3. Clique em **Add app** no menu superior e selecione **Add custom SAML app**.

    4. Insira um nome para o app e clique em **Continue**.

    5. Copie a URL de metadados e salve-a em algum lugar.

    6. Insira a ACS URL e o Entity ID abaixo.

       | Campo     | Valor                                         |
       | --------- | --------------------------------------------- |
       | ACS URL   | Copie a Single Sign-On URL do console         |
       | Entity ID | Copie o Service Provider Entity ID do console |

    7. Marque a caixa **Signed response**.

    8. Selecione **EMAIL** para o formato de Name ID e deixe o Name ID como **Basic Information > Primary email.**

    9. Clique em **Continue**.

    10. Insira o seguinte mapeamento de atributos:

        | Campo               | Valor           |
        | ------------------- | --------------- |
        | Informações básicas | Email principal |
        | Atributos do app    | email           |

    11. Clique em **Finish**.

    12. Para habilitar o app, clique em **OFF** para todos e altere a configuração para **ON** para todos. O acesso também pode ser limitado a grupos ou unidades organizacionais selecionando opções no lado esquerdo da tela.

    13. Volte para [Adicionar a URL de metadados à sua configuração de SAML](#add-metadata-url) para continuar o processo.
  </Tab>

  <Tab title="Azure (Microsoft)" id="azure">
    O SAML do Azure (Microsoft) também pode ser chamado de Azure Active Directory (AD) ou Microsoft Entra.

    #### Crie uma aplicação empresarial do Azure

    Você configurará uma integração de aplicação com uma URL de login separada para cada organização.

    1. Entre no centro de administração do Microsoft Entra.

    2. Navegue até **Applications > Enterprise applications** no menu à esquerda.

    3. Clique em **New application** no menu superior.

    4. Clique em **Create your own application** no menu superior.

    5. Insira um nome e selecione **Integrate any other application you don't find in the gallery (Non-gallery)**; em seguida, clique em **Create**.

           <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-azure-app.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=2b17a3cd8cc1fb3c8b4612fb0a4e4f14" size="md" alt="Aplicativo do Azure fora da galeria" force width="980" height="624" data-path="images/cloud/security/saml-azure-app.webp" />

    6. Clique em **Users and groups** à esquerda e atribua os usuários.

    7. Clique em **Single sign-on** à esquerda.

    8. Clique em **SAML**.

    9. Use as configurações a seguir para preencher a tela Basic SAML Configuration.

       | Field                                      | Value                                                           |
       | ------------------------------------------ | --------------------------------------------------------------- |
       | Identifier (Entity ID)                     | Copie o Service Provider Entity ID do console                   |
       | Reply URL (Assertion Consumer Service URL) | Copie a Single Sign-On URL do console                           |
       | Sign on URL                                | `https://console.clickhouse.cloud/?connection={organizationid}` |
       | Relay State                                | Em branco                                                       |
       | Logout URL                                 | Em branco                                                       |

    10. Adicione (A) ou atualize (U) o seguinte em Attributes & Claims:

        | Claim name                           | Format        | Source attribute |
        | ------------------------------------ | ------------- | ---------------- |
        | (U) Unique User Identifier (Name ID) | Email address | user.mail        |
        | (A) email                            | Basic         | user.mail        |
        | (U) /identity/claims/name            | Omitted       | user.mail        |

            <Image img="https://mintcdn.com/private-7c7dfe99/7KTNIE_ER4ouwRNt/images/cloud/security/saml-azure-claims.webp?fit=max&auto=format&n=7KTNIE_ER4ouwRNt&q=85&s=639d6890c29c84209f474ad82c130d68" size="md" alt="Atributos e declarações" force width="1242" height="816" data-path="images/cloud/security/saml-azure-claims.webp" />

    11. Copie a metadata URL e volte para [Adicionar a metadata URL à sua configuração SAML](#add-metadata-url) para continuar o processo.
  </Tab>

  <Tab title="Duo" id="duo">
    #### Crie um provedor de serviço SAML genérico para o Duo

    1. Siga as instruções em [Duo Single Sign-On for Generic SAML Service Providers](https://duo.com/docs/sso-generic).

    2. Use o seguinte mapeamento de atributos do Bridge:

       | Bridge Attribute  | ClickHouse Attribute |
       | :---------------- | :------------------- |
       | Endereço de email | email                |

    3. Use os seguintes valores para atualizar seu Cloud Application no Duo:

       | Field                                   | Value                                                           |
       | :-------------------------------------- | :-------------------------------------------------------------- |
       | ID da entidade                          | Copie o Service Provider Entity ID do console                   |
       | URL do Assertion Consumer Service (ACS) | Copie a Single Sign-On URL do console                           |
       | URL de login do provedor de serviço     | `https://console.clickhouse.cloud/?connection={organizationid}` |

    4. Copie a metadata URL e volte para [Adicionar a metadata URL à sua configuração de SAML](#add-metadata-url) para continuar o processo.
  </Tab>
</Tabs>

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

<AccordionGroup>
  <Accordion title="Pode haver uma configuração incorreta no sistema ou uma indisponibilidade do serviço">
    **Causa:** login iniciado pelo provedor de identidade, o que não tem suporte.

    **Correção:** use o link direto `https://console.clickhouse.cloud/?connection={organizationid}`. Siga as instruções do seu provedor de identidade acima para tornar esse o método de login padrão para seus usuários.
  </Accordion>

  <Accordion title="Você é redirecionado ao seu provedor de identidade e depois de volta para a página de login">
    **Causa:** o provedor de identidade não tem o mapeamento do atributo de email.

    **Correção:** siga as instruções do seu provedor de identidade acima para configurar o atributo de email do usuário e depois faça login novamente.
  </Accordion>

  <Accordion title="O usuário não está atribuído a este aplicativo">
    **Causa:** o usuário não foi atribuído ao aplicativo ClickHouse no provedor de identidade.

    **Correção:** atribua o usuário ao aplicativo no provedor de identidade e faça login novamente.
  </Accordion>

  <Accordion title="Você sempre cai na mesma organização com várias organizações SAML">
    **Causa:** você ainda está conectado à primeira organização.

    **Correção:** saia e depois faça login na outra organização.
  </Accordion>

  <Accordion title="A URL exibe brevemente acesso negado">
    **Causa:** seu domínio de email não corresponde ao domínio configurado.

    **Correção:** entre em contato com o suporte para obter ajuda na resolução desse erro.
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="O ClickHouse Cloud oferece suporte a login iniciado pelo provedor de identidade?">
    Não — apenas fluxos iniciados pelo provedor de serviço. Os usuários acessam `https://console.clickhouse.cloud` e informam seu e-mail para serem redirecionados ao seu provedor de identidade. Configure um favorito ou link direto (`https://console.clickhouse.cloud/?connection={organizationid}`) para que os usuários não precisem memorizar a URL.
  </Accordion>

  <Accordion title="Como usar SAML SSO com várias organizações?">
    O ClickHouse Cloud oferece suporte a SSO com várias organizações, com uma conexão separada para cada organização. Use o link direto (`https://console.clickhouse.cloud/?connection={organizationid}`) para fazer login em cada uma delas e saia de uma organização antes de entrar em outra. Se você não quiser que os usuários do seu domínio sejam encaminhados automaticamente para uma organização ao informarem o e-mail em `https://console.clickhouse.cloud`, abra um ticket de suporte para desativar esse comportamento.
  </Accordion>

  <Accordion title="Por que vejo várias contas para o mesmo usuário?">
    O ClickHouse Cloud não vincula automaticamente contas com SSO e sem SSO, então um usuário que tenha feito login das duas formas pode aparecer mais de uma vez na sua lista de usuários, mesmo com o mesmo endereço de e-mail.
  </Accordion>
</AccordionGroup>

<div id="next-steps">
  ## Próximos passos
</div>

* [Manage cloud users](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/manage-cloud-users) — gerencie permissões e restrinja o acesso apenas a conexões SAML.
* [Provisionamento SCIM](/docs/pt-BR/products/cloud/guides/security/cloud-access-management/scim-setup) — automatize o provisionamento de usuários e grupos (prévia privada).
* [Console roles and permissions](/docs/pt-BR/products/cloud/reference/security/console-roles) — os funções que você pode atribuir como função SAML padrão.