Configuração da 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.

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

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.

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.

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.

Preencha os detalhes do provedor

Preencha o formulário do provedor e selecione Save.

Campo	Descrição
Name	Um nome único para este provedor no serviço. Não pode ser alterado após a criação.
Issuer	A claim iss esperada nos tokens recebidos.
Audience	A claim aud esperada nos tokens recebidos.
JWKS URL	A URL HTTPS pública que disponibiliza as chaves públicas usadas para verificar assinaturas de tokens.
Roles claim (opcional)	A claim do token da qual as funções do ClickHouse serão lidas. Deixe em branco para usar o nome de claim padrão clickhouse:roles. As funções especificadas no token já devem existir no serviço.

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.

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

• Autenticação JWT — claims de tokens, usuários efêmeros e uso do cliente.