Skip to main content
Crea un token para el usuario actual: el server genera un secreto aleatorio, lo añade al usuario actual como un método de autenticación adicional y lo devuelve como resultado de la consulta. El secreto solo se muestra en esta consulta: se almacena hasheado, por lo que no puede recuperarse posteriormente. Sintaxis:
Esta es una forma abreviada de ALTER USER <current user> ADD IDENTIFIED WITH sha256_password BY '<random secret>' con las mismas cláusulas VALID UNTIL y GRANTS, por lo que un token se comporta como una contraseña normal del usuario actual:
  • está vinculado al usuario: aparece en system.query_log y system.processes como el usuario, deja de funcionar cuando se elimina el usuario y pierde los derechos de acceso cuando el usuario los pierde;
  • puede limitarse en el tiempo con VALID UNTIL o VALID FOR, y en privilegios con GRANTS;
  • puede utilizarse con cualquier mecanismo de autenticación que acepte una contraseña, por ejemplo, el parámetro password de la interfaz HTTP o la opción --password de clickhouse-client.
Crear un token requiere el privilegio CREATE TOKEN o el privilegio ALTER USER sobre el usuario actual. Es un privilegio independiente porque un token reduce el nivel de seguridad de la cuenta a la que pertenece: un usuario autenticado con una clave de hardware o un certificado puede usarlo para crear una contraseña de larga duración para esa misma cuenta. Ese mismo privilegio autoriza la sentencia equivalente ALTER USER <current user> ADD IDENTIFIED ....

​
Resultado

La consulta devuelve una fila con dos columnas: Para obtener el secreto sin ningún formato, selecciónelo con FORMAT TSVRaw:
El secreto tiene 32 caracteres de longitud y se genera a partir de una fuente aleatoria criptográficamente segura, por lo que no es necesario validarlo (ni se valida) frente a las reglas de complejidad de contraseñas: estas existen para limitar las contraseñas elegidas por personas.

​
Cláusulas VALID UNTIL y VALID FOR

Limitan el tiempo de vida del token. Funcionan exactamente igual que las cláusulas correspondientes de un método de autenticación de CREATE USER: VALID UNTIL recibe una fecha y hora absolutas, mientras que VALID FOR recibe un interval que se suma a la hora actual en el momento de ejecutar la consulta. Si no se especifica ninguna de las dos cláusulas, el token vive el tiempo indicado por create_token_default_ttl_seconds, que de forma predeterminada es de 30 minutos, por lo que un token para el que no se solicita una duración mayor es efímero. Establezca ese setting en 0, o escriba VALID UNTIL 'infinity', para crear un token que nunca expire. Ejemplos:
  • CREATE TOKEN VALID UNTIL '2026-12-31'
  • CREATE TOKEN VALID FOR INTERVAL 30 DAY
  • CREATE TOKEN VALID UNTIL 'infinity'

​
Cláusula GRANTS

Limita los derechos de acceso de las sesiones autenticadas con el token a la intersección con los privilegios enumerados. Funciona exactamente igual que la cláusula GRANTS de CREATE USER, incluidas sus limitaciones: en particular, el límite se aplica en el nodo que recibe la consulta y no se propaga a los demás nodos de un cluster. La cláusula nunca añade derechos de acceso: un privilegio que no se haya concedido al usuario sigue sin estar disponible para el token. Sin la cláusula, el token tiene todos los derechos de acceso del usuario. Ejemplos:
  • CREATE TOKEN GRANTS (SELECT ON db.table)
  • CREATE TOKEN VALID FOR INTERVAL 90 DAY GRANTS (SELECT ON db.table, INSERT ON db.table)
Ni este límite ni el límite de tiempo se aplican a lo que dejan tras de sí las sesiones del token: consulte Consideraciones de seguridad.

​
Gestión de tokens

Un token es un método de autenticación del usuario, por lo que aparece en SHOW CREATE USER (con sus cláusulas VALID UNTIL y GRANTS, pero sin el secreto) y en las columnas auth_type, auth_params y auth_grants de la tabla system.users. No existe ninguna sentencia que elimine un único token. Para revocar todos los tokens de un usuario, reemplace sus métodos de autenticación, por ejemplo con ALTER USER <name> IDENTIFIED WITH ..., o utilice ALTER USER <name> RESET AUTHENTICATION METHODS TO NEW para conservar solo el añadido más recientemente. El número de métodos de autenticación que un usuario puede tener a la vez está limitado por el server setting max_authentication_methods_per_user. El secreto lo genera y lo almacena la propia consulta, de modo que un CREATE TOKEN cuyo resultado nunca llega al client —una connection perdida mientras se envía la fila, o un INTO OUTFILE que el client no puede abrir— deja tras de sí un método de autenticación que nadie puede usar y que sigue contando para ese límite. Nadie posee ese secreto: existe únicamente mientras se ejecuta la consulta. Una consulta rechazada antes de ejecutarse, incluida aquella cuya FORMAT cláusula indique un format que no puede utilizarse, no añade nada. CREATE TOKEN no admite la ON CLUSTER cláusula. Utilice un almacenamiento de acceso replicado (o ejecute la consulta en cada nodo con la sentencia equivalente ALTER USER ... ADD IDENTIFIED WITH sha256_hash) para que un token funcione en un cluster cuyas access entities se almacenan localmente.

​
Consideraciones de seguridad

VALID UNTIL y GRANTS limitan las sesiones que se autentican con el token, pero no limitan lo que esas sesiones dejan tras de sí:
  • El plazo se comprueba cuando una sesión se autentica con el token. Una sesión que ya está abierta, o una consulta que ya se está ejecutando, no se interrumpen cuando el token caduca.
  • Todo lo que crea una sesión sobrevive al token, y un objeto que trabaja por su cuenta sigue haciéndolo: una vista materializada actualizable sigue actualizándose, una vista materializada asociada a un motor de tabla de streaming como Kafka, RabbitMQ, NATS o S3Queue sigue consumiendo, y un diccionario con un LIFETIME sigue recargándose, mucho después de que el token haya expirado. Una vista realiza ese trabajo con los derechos de su DEFINER, que por defecto es el usuario que creó la vista: con todos los derechos de ese usuario, no con los que le dejó la cláusula GRANTS del token.
Por tanto, un token con permiso para crear tablas, vistas o diccionarios puede ampliar en la práctica ambos límites: puede dejar tras de sí un trabajo persistente que sigue ejecutándose una vez vencido el plazo y que hace, con los derechos del usuario, aquello que al propio token no se le permitía. Concede a un token únicamente lo que la aplicación necesita —normalmente SELECT e INSERT sobre tablas concretas— y deja CREATE TABLE, CREATE VIEW, CREATE DICTIONARY y los privilegios de ACCESS MANAGEMENT fuera de su cláusula GRANTS cuando los límites deban mantenerse. Una sesión autenticada con un token que tiene una cláusula GRANTS no puede emitir tokens en absoluto: a una sesión así se le deniega añadir un método de autenticación a un usuario existente. La cláusula GRANTS de un nuevo método de autenticación se intersecta al iniciar sesión con los derechos de acceso del usuario, no con los de la sesión que creó el método, ya que de lo contrario sería una manera de ampliar el límite.
Última modificación el 26 de septiembre de 2026