CREATE TOKEN

Documentação sobre Token

Cria um token para o usuário atual: o servidor gera um Secret aleatório, adiciona-o ao usuário atual como um método de autenticação adicional e o retorna como resultado da consulta. O Secret é exibido somente por esta consulta — ele é armazenado com hash, portanto não pode ser recuperado posteriormente.

Sintaxe:

CREATE TOKEN
    [{VALID UNTIL datetime | VALID FOR interval}]
    [GRANTS (privilege ON object [,...])]

Esta é uma forma abreviada de ALTER USER <current user> ADD IDENTIFIED WITH sha256_password BY '<random secret>' com as mesmas cláusulas VALID UNTIL e GRANTS, de modo que um token se comporta como uma senha comum do usuário atual:

• está vinculado ao usuário — é exibido em system.query_log e system.processes como o usuário, deixa de funcionar quando o usuário é excluído e perde os direitos de acesso quando o usuário os perde;
• pode ser limitado no tempo com VALID UNTIL ou VALID FOR, e nos privilégios com GRANTS;
• pode ser usado com qualquer mecanismo de autenticação que aceite uma senha, por exemplo, o parâmetro password da interface HTTP ou a opção --password do clickhouse-client.

Criar um token exige o privilégio CREATE TOKEN ou o privilégio ALTER USER sobre o usuário atual. Trata-se de um privilégio separado porque um token reduz o nível de segurança da conta à qual pertence: um usuário autenticado com uma chave de hardware ou um certificado pode usá-lo para criar uma senha de longa duração para essa mesma conta. O mesmo privilégio autoriza a instrução equivalente ALTER USER <current user> ADD IDENTIFIED ....

​

Resultado

A consulta retorna uma linha com duas colunas:

Coluna	Tipo	Descrição
token	String	O Secret gerado.
valid_until	DateTime64(0)	Quando o token expira. 0 significa que ele nunca expira, seguindo a mesma codificação da coluna valid_until de system.users.

Para obter o Secret sem qualquer formatação, selecione-o com FORMAT TSVRaw:

CREATE TOKEN VALID FOR INTERVAL 30 DAY GRANTS (SELECT ON db.*) FORMAT TSVRaw

O Secret tem 32 caracteres e é gerado a partir de uma fonte aleatória criptograficamente segura, portanto não precisa ser (e não é) validado contra as regras de complexidade de senha — elas existem para restringir senhas escolhidas por pessoas.

​

Cláusulas VALID UNTIL e VALID FOR

Limitam o ciclo de vida do token. Funcionam exatamente como as cláusulas correspondentes de um método de autenticação de CREATE USER: VALID UNTIL recebe uma data e hora absolutas; VALID FOR recebe um interval que é somado ao horário atual no momento em que a consulta é executada.

Sem nenhuma dessas cláusulas, o token permanece válido por create_token_default_ttl_seconds, que é de 30 minutos por padrão; ou seja, um token para o qual não se solicita uma duração maior tem vida curta. Defina essa configuração como 0 ou escreva VALID UNTIL 'infinity' para criar um token que nunca expira.

Exemplos:

• CREATE TOKEN VALID UNTIL '2026-12-31'
• CREATE TOKEN VALID FOR INTERVAL 30 DAY
• CREATE TOKEN VALID UNTIL 'infinity'

​

Cláusula GRANTS

Limita os direitos de acesso das sessões autenticadas com o token à interseção com os privilégios listados. Funciona exatamente como a cláusula GRANTS de CREATE USER, incluindo suas limitações — notadamente, o limite é aplicado no nó que recebe a consulta e não é propagado para os demais nós de um cluster. A cláusula nunca adiciona direitos de acesso: um privilégio que não tenha sido concedido ao usuário permanece indisponível para o token. Sem a cláusula, o token possui todos os direitos de acesso do usuário.

Exemplos:

• CREATE TOKEN GRANTS (SELECT ON db.table)
• CREATE TOKEN VALID FOR INTERVAL 90 DAY GRANTS (SELECT ON db.table, INSERT ON db.table)

Nem esse limite nem o limite de tempo se aplicam ao que as sessões do token deixam para trás — consulte Considerações de segurança.

​

Gerenciando tokens

Um token é um método de autenticação do usuário, portanto é listado por SHOW CREATE USER (com suas cláusulas VALID UNTIL e GRANTS, mas sem o Secret) e nas colunas auth_type, auth_params e auth_grants da tabela system.users.

Não há nenhuma instrução que remova um único token. Para revogar todos os tokens de um usuário, substitua seus métodos de autenticação, por exemplo com ALTER USER <name> IDENTIFIED WITH ..., ou use ALTER USER <name> RESET AUTHENTICATION METHODS TO NEW para manter apenas o mais recente. O número de métodos de autenticação que um usuário pode ter ao mesmo tempo é limitado pela configuração do servidor max_authentication_methods_per_user.

O Secret é gerado e armazenado pela própria consulta; assim, um CREATE TOKEN cujo resultado nunca chega ao cliente — uma conexão perdida enquanto a linha está sendo enviada, ou um INTO OUTFILE que o cliente não consegue abrir — deixa para trás um método de autenticação que ninguém pode usar e que, mesmo assim, conta para esse limite. Ninguém detém esse Secret: ele existe apenas enquanto a consulta é executada. Já uma consulta rejeitada antes de ser executada, inclusive aquela cuja cláusula FORMAT indica um format que não pode ser usado, não adiciona nada.

CREATE TOKEN não oferece suporte à cláusula ON CLUSTER. Use um armazenamento de acesso replicado (ou execute a consulta em cada nó com a instrução equivalente ALTER USER ... ADD IDENTIFIED WITH sha256_hash) para que um token funcione em um cluster cujas access entities são armazenadas localmente.

​

Considerações de segurança

VALID UNTIL e GRANTS restringem as sessões que se autenticam com o token. Eles não restringem o que essas sessões deixam para trás:

• O prazo é verificado no momento em que uma sessão se autentica com o token. Uma sessão já aberta, e uma consulta já em execução, não são interrompidas quando o token expira.
• Tudo o que uma sessão cria sobrevive ao token, e um objeto que executa trabalho por conta própria continua executando-o: uma view materializada atualizável continua se atualizando, uma visão materializada anexada a um motor de tabela de streaming como Kafka, RabbitMQ, NATS ou S3Queue continua consumindo, e um dicionário com LIFETIME continua recarregando, muito depois de o token ter expirado. Uma visão realiza esse trabalho com os direitos de seu DEFINER, que por padrão é o usuário que criou a visão — todos os direitos do usuário, e não apenas os direitos a que a cláusula GRANTS do token o limitou.

Um token com permissão para criar tabelas, visões ou dicionários pode, portanto, ampliar na prática os seus dois limites: ele pode deixar para trás uma tarefa persistente que continua em execução após o prazo e faz, com os direitos do usuário, aquilo que o próprio token não tinha permissão para fazer. Conceda a um token apenas o que a aplicação precisa — geralmente SELECT e INSERT em tabelas nomeadas — e mantenha CREATE TABLE, CREATE VIEW, CREATE DICTIONARY e os privilégios ACCESS MANAGEMENT fora de sua cláusula GRANTS sempre que os limites precisarem valer de fato.

Uma sessão autenticada com um token que possui uma cláusula GRANTS não pode emitir tokens de forma alguma: adicionar um método de autenticação a um usuário existente é negado para esse tipo de sessão. A cláusula GRANTS de um novo método de autenticação é cruzada, no login, com os direitos de acesso do usuário, e não com os da sessão que criou o método; caso contrário, isso seria uma forma de ampliar o limite.