Autenticação JWT

O ClickHouse pode autenticar usuários usando JSON Web Tokens (JWTs). Diferentemente de outros autenticadores externos, como LDAP ou Kerberos, a autenticação por JWT não verifica a identidade de usuários já existentes. Em vez disso, ela cria dinamicamente usuários efêmeros a partir das claims contidas em cada token. Esses usuários existem apenas na memória, recebem direitos de acesso derivados das claims do token e são removidos automaticamente quando o token expira.

Isso torna a autenticação por JWT fundamentalmente diferente de métodos baseados em senha ou em certificado: não existe uma instrução CREATE USER ... IDENTIFIED WITH jwt, e tentar executá-la gera uma exceção. Os usuários JWT são totalmente gerenciados pelo ciclo de vida do token.

O fluxo de autenticação funciona da seguinte forma:

1. Um cliente apresenta um JWT assinado por meio de um dos mecanismos de transporte compatíveis (cabeçalho HTTP Authorization: Bearer, o protocolo nativo TCP ou o campo gRPC jwt).
2. O ClickHouse valida a assinatura do token.
3. As claims obrigatórias (exp, iat, iss, sub, aud) são verificadas.
4. Um usuário efêmero é criado na memória com direitos de acesso derivados das claims do token clickhouse:grants e clickhouse:roles, em interseção com um limite de permissões.
5. Quando o token expira, uma tarefa de coleta de lixo em segundo plano remove o usuário.

Todo JWT apresentado ao ClickHouse deve conter as seguintes claims:

A claim kid (ID da chave) do cabeçalho também é obrigatória quando a resolução de chaves baseada em JWKS é usada.

{
  "alg": "RS256",
  "kid": "my-key-id"
}

{
  "iss": "https://idp.example.com",
  "sub": "jane.doe",
  "aud": "my-clickhouse-cluster",
  "exp": 1719504000,
  "iat": 1719500400,
  "clickhouse:grants": ["SELECT ON analytics.*", "INSERT ON analytics.events"],
  "clickhouse:roles": ["analyst"]
}

Os usuários JWT diferem dos usuários regulares do ClickHouse em vários aspectos importantes.

Cada usuário JWT recebe um UUID determinístico calculado a partir das claims iss, sub e aud. Esse UUID é estável entre logins. Um usuário que faz login várias vezes com tokens diferentes (mas com o mesmo emissor, sujeito e audiência) sempre recebe o mesmo UUID.

O nome de usuário, no entanto, é volátil. Ele é construído da seguinte forma:

JWT::<subject>::<claims_hash>

O <claims_hash> é um hash derivado das claims iss, sub e aud, em conjunto com as claims clickhouse:roles e clickhouse:grants. As claims iss e aud participam apenas por meio desse hash; elas não são mais incorporadas diretamente ao prefixo visível do nome de usuário. Isso mantém o nome compacto e legível quando iss/aud são URLs longas e opacas do IdP (por exemplo, Microsoft Entra ou Okta), ao mesmo tempo em que garante que tuplas distintas de (iss, sub, aud) e conjuntos distintos de clickhouse:roles / clickhouse:grants sejam mapeados para nomes distintos e estáveis. Claims que não entram no hash (por exemplo, iat, exp, nbf ou claims personalizadas não relacionadas) não alteram o nome de usuário.

A parte <claims_hash> muda sempre que as claims clickhouse:roles ou clickhouse:grants são alteradas. Isso significa que tokens com diferentes conjuntos de roles ou grants geram nomes de usuário diferentes, mesmo quando a identidade é a mesma.

Os direitos de acesso efetivos são calculados da seguinte forma:

effective_rights = permission_limit ∩ (token_grants ∪ token_roles)

Em que permission_limit representa o conjunto de direitos de acesso de uma role ou usuário de referência configurado como limite superior. Os direitos solicitados pelo token que excederem esse limite são descartados silenciosamente.

O ClickHouse rastreia a claim iat (issued-at) do token autenticado mais recentemente para cada identidade estável. Se for apresentado um token com iat igual ou anterior ao valor armazenado, o servidor reutiliza o usuário efêmero existente sem reavaliar as claims. Isso impede que tokens mais antigos reduzam as permissões do usuário.

Usuários efêmeros são criados quando um token é autenticado pela primeira vez e removidos por uma tarefa de coleta de lixo em segundo plano após valid_until (derivado de exp) expirar. O intervalo de GC é controlado pelo parâmetro gc_interval (padrão: 5 minutos).

Entre as execuções do GC, usuários expirados ainda podem aparecer em system.users, mas não podem mais se autenticar.

Como o UUID é estável, você pode atribuir perfis de configuração, cotas, políticas de linha e políticas de mascaramento de coluna a um usuário JWT usando instruções SQL. Essas atribuições permanecem no armazenamento de controle de acesso (em disco ou no ZooKeeper) e persistem após a expiração do token e uma nova autenticação.

Faça referência ao usuário pelo nome de usuário atual:

ALTER SETTINGS PROFILE my_profile ADD TO 'JWT::jane.doe::<claims_hash>';

Observe que ALTER USER não funciona diretamente com usuários JWT, pois eles são somente leitura. Para atribuir perfis de configuração, cotas ou políticas, use as instruções ALTER SETTINGS PROFILE, ALTER QUOTA ou ALTER ROW POLICY, como mostrado acima.

Quando um usuário JWT efêmero cria uma view com SQL SECURITY DEFINER, o servidor cria automaticamente uma cópia sombra persistente desse usuário para servir como definidor da view. Esse usuário sombra:

• Tem o nome <original_jwt_username>:definer
• Tem NO_AUTHENTICATION (não pode ser usado para fazer login)
• Mantém os mesmos direitos de acesso do usuário JWT original no momento em que a view foi criada

Isso garante que a view continue funcionando depois que o token do usuário efêmero expirar e o usuário original for removido pelo coletor de lixo.

Use a flag --jwt com o clickhouse-client para autenticar usando um token obtido previamente:

clickhouse-client --host your-instance.clickhouse.cloud --secure --jwt '<your_jwt_token>'

Envie o token como token Bearer no cabeçalho Authorization:

curl -H 'Authorization: Bearer <your_jwt_token>' \
    'https://your-instance.clickhouse.cloud:8443/?query=SELECT+currentUser()'

O clickhouse-client oferece suporte a um fluxo interativo de código do dispositivo OAuth2 por meio da flag --login. Para endpoints do ClickHouse Cloud, o cliente faz automaticamente a troca de token para obter um JWT específico do ClickHouse. Os tokens são atualizados de forma transparente durante a sessão. Quando um novo token é obtido, o cliente se reconecta automaticamente.

clickhouse-client --host your-instance.clickhouse.cloud --login

Todo ClickHouse Cloud service vem com um autenticador JWT predefinido usado pelo SQL Console e pelo fluxo --login do clickhouse-client. Esse autenticador é configurado com:

O autenticador integrado tem um limite de permissões definido para a role default_role e para o usuário default. Isso significa que as permissões efetivas de qualquer usuário JWT ficam restritas à interseção com os grants dessas duas entidades, portanto um token nunca pode elevar privilégios além do que default_role e default têm permissão para fazer.

Você não precisa configurar nada para usar esse autenticador. Ele é provisionado automaticamente quando o serviço é criado.

Além do autenticador integrado, você pode configurar seu serviço ClickHouse Cloud para aceitar JWTs emitidos pelo seu próprio provedor de identidade (por exemplo, Microsoft Entra ou Okta). Este é um recurso beta, disponível no plano Enterprise para serviços que executam o ClickHouse versão 26.4 ou posterior. Você pode configurá-lo por conta própria no Cloud Console em Settings → Security → JWT authentication — consulte Configuração da autenticação JWT para obter instruções passo a passo. Cada provedor é definido pelos seguintes itens:

Quando uma consulta é encaminhada para outro shard ou réplica, o token JWT é incluído no protocolo de comunicação entre servidores. O nó remoto reautentica o token de forma independente, criando seu próprio usuário efêmero.

• Nenhum direito de acesso concedido: A role ou o usuário referenciado pode não ter os privilégios necessários. Verifique se as roles referenciadas em clickhouse:roles existem e incluem os privilégios apropriados.
• Token rejeitado: Verifique se iss, aud e o algoritmo de assinatura do seu token correspondem ao que o provedor JWT espera. Se JWKS estiver em uso, verifique se o kid do token corresponde a uma chave no conjunto de chaves do provedor.
• O usuário desaparece entre queries: Usuários efêmeros são removidos após a expiração do token. Use um cliente com suporte à renovação do token (por exemplo, no modo --login) para sessões de longa duração.
• CREATE USER ... IDENTIFIED WITH jwt falha: Isso é esperado. Usuários JWT não podem ser criados via DDL. Eles são gerenciados inteiramente pelo ciclo de vida do token.