Skip to main content
Este guia aborda a configuração de provedores JWKS no Cloud Console. Para saber como gerar um JWT e como é sua estrutura — as claims obrigatórias, as claims de funções e grants e o funcionamento dos usuários efêmeros — consulte a referência sobre Autenticação JWT.
O ClickHouse Cloud permite autenticar conexões com um serviço usando JSON Web Tokens (JWTs) validados nos seus próprios endpoints de JSON Web Key Set (JWKS). Em vez de gerenciar credenciais de banco de dados, seu provedor de identidade emite tokens de curta duração que o ClickHouse verifica com base nas chaves públicas publicadas em um URL JWKS configurado por você. Você pode configurar esses provedores JWKS para cada serviço em Settings → Security no Cloud Console do ClickHouse.

​
Antes de começar

Para configurar provedores JWT para um serviço, você precisa de:
  • Uma organização no plano Enterprise.
  • Um serviço executando o ClickHouse versão 26.4 ou posterior.
  • Uma função com a permissão control-plane:service:manage no serviço (por exemplo, Admin ou Service admin). Os membros sem essa permissão veem a seção como somente leitura.
  • Uma URL JWKS HTTPS acessível publicamente que publique pelo menos uma chave RSA (RS256) ou, para serviços na versão 26.8 ou posterior, uma chave EC (ES256, ES384, ES512).
Provedores baseados em JWKS aceitam chaves RSA e, a partir da versão 26.8, chaves EC nas curvas P-256, P-384 e P-521. Um documento JWKS pode conter outros tipos de chave, mas deve haver pelo menos uma chave utilizável.

​
Como funciona

O cliente (seu provedor de identidade ou aplicação) gera um JWT e o assina com sua chave privada. O token deve seguir o formato de token esperado. Em seguida, o ClickHouse o verifica usando as chaves públicas publicadas no URL do seu JWKS:
  1. O ClickHouse lê o cabeçalho kid (ID da chave) do token e seleciona a chave correspondente no documento JWKS.
  2. Ele verifica a assinatura do token usando essa chave pública e valida as claims iss (emissor) e aud (audiência) em relação à configuração do seu provedor.
  3. Em caso de sucesso, a conexão é estabelecida como um usuário efêmero, cujos direitos de acesso são derivados das claims clickhouse:grants e clickhouse:roles do token, limitados pelo limite de permissões (o usuário default). Consulte Direitos de acesso para obter detalhes.
O ClickHouse valida e busca o URL JWKS quando você adiciona ou atualiza um provedor. Assim, um URL configurado incorretamente ou inacessível é rejeitado imediatamente.

​
Adicionar um provedor JWT

1

Abra as configurações de segurança do serviço

Acesse o serviço, abra Settings e role até a seção Security. Localize o cartão JWT authentication.
2

Abra o painel de provedores

Selecione Set up JWT providers (ou Manage JWT providers, caso já tenha algum configurado). O painel será aberto com um formulário para um novo provedor pronto para preenchimento.
3

Preencha os detalhes do provedor

Preencha o formulário do provedor e selecione Save.
4

Adicione mais provedores, se necessário

Use Add another provider para configurar provedores adicionais. Um serviço pode ter no máximo cinco provedores JWT.
Excluir um provedor JWT interrompe imediatamente a aceitação de tokens emitidos por ele, e quaisquer workloads que ainda se autentiquem com esses tokens deixarão de funcionar.

​
Limites

  • No máximo cinco provedores JWT por serviço.
  • Provedores JWKS aceitam chaves RSA (RS256) e, a partir da versão 26.8, chaves EC (ES256, ES384, ES512).
  • A URL JWKS deve ser um endpoint HTTPS público. Endereços privados, internos ou de link local são rejeitados.
Última modificação em 26 de agosto de 2026