Configuração de 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 com Okta e Microsoft Entra ID. 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.

Antes de começar

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.

Como funciona

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

O usuário acessa https://console.clickhouse.cloud e informa seu endereço de email (ou usa o link direto da sua organização).
O ClickHouse Cloud o redireciona para seu provedor de identidade para autenticação.
Se a autenticação for bem-sucedida, o provedor de identidade o redireciona de volta ao ClickHouse Cloud.
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.

Como configurar seu IdP

Acesse as configurações da organização

Clique no nome da sua organização no canto inferior esquerdo e selecione Detalhes da organização.

Ative o logon único SAML

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.

Crie um aplicativo no seu provedor de identidade

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
Google
Azure (Microsoft)
Duo

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.

Adicione a URL de metadados à sua configuração SAML

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.

Obtenha o código de verificação do domínio

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.

Verifique seu domínio

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.

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.

Atualizar a função padrão e o tempo limite da sessão

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.

Configure o seu usuário Admin

Os usuários configurados com um método de authentication diferente serão mantidos até que um Admin da sua organização os remova.

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

Saia do ClickHouse Cloud.
No seu provedor de identidade, atribua o usuário Admin aos aplicativos do ClickHouse.
Peça ao usuário para fazer login em 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.
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)

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

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

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.

Remover outros métodos de autenticação

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.

Configure o seu provedor de identidade

Okta
Google
Azure (Microsoft)
Duo

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

Faça login na sua instância do Okta como Administrator.
Selecione Groups à esquerda.
Clique em Add group.
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.
Clique em Save.
Clique no nome do grupo que você criou.
Clique em Assign people para atribuir os usuários que você deseja que tenham acesso a esta organização do ClickHouse.

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

Crie um app SAML para habilitar a conexão

Selecione Applications à esquerda e, em seguida, selecione o subtítulo Applications.
Clique em Create App Integration.
Selecione SAML 2.0 e clique em Next.
Insira um nome para seu aplicativo, marque a caixa ao lado de Don’t display application icon to users e clique em Next.

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

Insira a seguinte Attribute Statement.
Name Name format Value
email Basic user.email
Clique em Next.
Insira as informações solicitadas na tela Feedback e clique em Finish.
Vá para a aba Assignments e adicione o grupo que você criou acima.
Na aba Sign On do seu novo app, clique no botão Copy metadata URL.
Retorne para Add the metadata URL to your SAML configuration para continuar o processo.

Name	Name format	Value
email	Basic	user.email

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

Acesse o console do Google Admin (admin.google.com).
Clique em Apps e, em seguida, em Web and mobile apps à esquerda.
Clique em Add app no menu superior e selecione Add custom SAML app.
Insira um nome para o app e clique em Continue.
Copie a URL de metadados e salve-a em algum lugar.
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
Marque a caixa Signed response.
Selecione EMAIL para o formato de Name ID e deixe o Name ID como Basic Information > Primary email.
Clique em Continue.
Insira o seguinte mapeamento de atributos:
Campo Valor
Informações básicas Email principal
Atributos do app email
Clique em Finish.
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.
Volte para Adicionar a URL de metadados à sua configuração de SAML para continuar o processo.

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

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

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.

Entre no centro de administração do Microsoft Entra.
Navegue até Applications > Enterprise applications no menu à esquerda.
Clique em New application no menu superior.
Clique em Create your own application no menu superior.
Insira um nome e selecione Integrate any other application you don’t find in the gallery (Non-gallery); em seguida, clique em Create.
Clique em Users and groups à esquerda e atribua os usuários.
Clique em Single sign-on à esquerda.
Clique em SAML.

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

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
Copie a metadata URL e volte para Adicionar a metadata URL à sua configuração SAML para continuar o processo.

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

Crie um provedor de serviço SAML genérico para o Duo

Siga as instruções em Duo Single Sign-On for Generic SAML Service Providers.
Use o seguinte mapeamento de atributos do Bridge:
Bridge Attribute ClickHouse Attribute
Endereço de email email

Bridge Attribute	ClickHouse Attribute
Endereço de email	email

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}`

Copie a metadata URL e volte para Adicionar a metadata URL à sua configuração de SAML para continuar o processo.

Solução de problemas

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.

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.

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.

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.

Perguntas frequentes

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.

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.Seu primeiro login em cada organização deve usar o link direto correspondente (https://console.clickhouse.cloud/?connection={organizationId}). Esse primeiro login provisiona sua conta nessa organização. Se sua organização tiver SCIM habilitado, você poderá pular esta etapa, pois sua conta já estará provisionada.Nos logins subsequentes, faça login em qualquer uma das suas organizações SAML. Suas outras organizações SAML ficam disponíveis no seletor de organizações na barra lateral do console, e selecionar uma delas faz login nessa organização por meio do SSO dela.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.

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.

Próximos passos

Manage cloud users — gerencie permissões e restrinja o acesso apenas a conexões SAML.
Provisionamento SCIM — automatize o provisionamento de usuários e grupos com Okta ou Microsoft Entra ID.
Console roles and permissions — os funções que você pode atribuir como função SAML padrão.

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

Antes de começar

Como funciona

Como configurar seu IdP

Configure o seu provedor de identidade

Crie um grupo para gerenciar o acesso

Crie um app SAML para habilitar a conexão

Criar um app da web do Google

Crie uma aplicação empresarial do Azure

Crie um provedor de serviço SAML genérico para o Duo

Solução de problemas

Perguntas frequentes

Próximos passos

​Antes de começar

​Como funciona

​Como configurar seu IdP

​Configure o seu provedor de identidade

​Crie um grupo para gerenciar o acesso

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

​Crie um app SAML para habilitar a conexão

​Criar um app da web do Google

​Crie uma aplicação empresarial do Azure

​Crie um provedor de serviço SAML genérico para o Duo

​Solução de problemas

​Perguntas frequentes

​Próximos passos

Antes de começar

Como funciona

Como configurar seu IdP

Configure o seu provedor de identidade

Crie um grupo para gerenciar o acesso

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

Crie um app SAML para habilitar a conexão

Criar um app da web do Google

Crie uma aplicação empresarial do Azure

Crie um provedor de serviço SAML genérico para o Duo

Solução de problemas

Perguntas frequentes

Próximos passos