CREATE TOKEN

Documentation pour Token

Crée un token pour l’utilisateur courant : le serveur génère un secret aléatoire, l’ajoute à l’utilisateur courant en tant que méthode d’authentification supplémentaire, puis le renvoie comme résultat de la requête. Ce secret n’est affiché que par cette requête — il est stocké sous forme hachée et ne peut donc pas être récupéré par la suite.

Syntaxe :

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

Il s’agit d’un raccourci pour ALTER USER <current user> ADD IDENTIFIED WITH sha256_password BY '<random secret>' avec les mêmes clauses VALID UNTIL et GRANTS : un token se comporte donc comme un mot de passe ordinaire de l’utilisateur courant :

• il est lié à l’utilisateur — il apparaît dans system.query_log et system.processes sous le nom de l’utilisateur, il cesse de fonctionner lorsque l’utilisateur est supprimé, et il perd les droits d’accès que l’utilisateur perd ;
• il peut être limité dans le temps avec VALID UNTIL ou VALID FOR, et en privilèges avec GRANTS ;
• il peut être utilisé avec tout mécanisme d’authentification acceptant un mot de passe, par exemple le paramètre password de l’interface HTTP ou l’option --password de clickhouse-client.

La création d’un token requiert le privilège CREATE TOKEN, ou le privilège ALTER USER sur l’utilisateur courant. Il s’agit d’un privilège distinct car un token abaisse le niveau de sécurité du compte auquel il appartient : un utilisateur authentifié par une clé matérielle ou un certificat peut s’en servir pour créer un mot de passe de longue durée pour ce même compte. Ce même privilège autorise le statement équivalent ALTER USER <current user> ADD IDENTIFIED ....

​

Résultat

La requête renvoie une ligne comportant deux colonnes :

Colonne	Type	Description
token	String	Le secret généré.
valid_until	DateTime64(0)	Date d’expiration du token. 0 signifie qu’il n’expire jamais, selon le même encodage que la colonne valid_until de system.users.

Pour obtenir le secret sans aucun formatage, sélectionnez-le avec FORMAT TSVRaw :

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

Le secret comporte 32 caractères et est généré à partir d’une source aléatoire cryptographiquement sûre ; il n’a donc pas besoin d’être (et n’est pas) confronté aux règles de complexité des mots de passe — celles-ci existent pour encadrer les mots de passe choisis par des humains.

​

Clauses VALID UNTIL et VALID FOR

Elles limitent la durée de vie du token. Elles fonctionnent exactement comme les clauses correspondantes d’une méthode d’authentification de CREATE USER : VALID UNTIL attend une date et une heure absolues, VALID FOR attend un interval qui est ajouté à l’heure courante au moment de l’exécution de la query.

En l’absence de ces deux clauses, la durée de vie du token est déterminée par create_token_default_ttl_seconds, soit 30 minutes par défaut : un token pour lequel aucune durée plus longue n’est demandée est donc éphémère. Définissez ce paramètre à 0, ou écrivez VALID UNTIL 'infinity', pour créer un token qui n’expire jamais.

Exemples :

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

​

Clause GRANTS

Limite les droits d’accès des sessions authentifiées par le token à l’intersection avec les privilèges listés. Cette clause fonctionne exactement comme la clause GRANTS de CREATE USER, avec les mêmes limitations — en particulier, la restriction est appliquée sur le nœud qui reçoit la requête et n’est pas propagée aux autres nœuds d’un cluster. La clause n’ajoute jamais de droits d’accès : un privilège qui n’est pas accordé à l’utilisateur reste indisponible pour le token. Sans cette clause, le token dispose de l’intégralité des droits d’accès de l’utilisateur.

Exemples :

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

Ni cette restriction ni la limite temporelle ne s’appliquent à ce que les sessions du token laissent derrière elles — voir Considérations de sécurité.

​

Gestion des tokens

Un token est une méthode d’authentification de l’utilisateur ; il est donc répertorié par SHOW CREATE USER (avec ses clauses VALID UNTIL et GRANTS, mais sans le secret) ainsi que dans les colonnes auth_type, auth_params et auth_grants de la table system.users.

Il n’existe aucune instruction permettant de supprimer un token isolé. Pour révoquer tous les tokens d’un utilisateur, remplacez ses méthodes d’authentification, par exemple avec ALTER USER <name> IDENTIFIED WITH ..., ou utilisez ALTER USER <name> RESET AUTHENTICATION METHODS TO NEW pour ne conserver que la plus récemment ajoutée. Le nombre de méthodes d’authentification qu’un utilisateur peut posséder simultanément est limité par le paramètre serveur max_authentication_methods_per_user.

Le secret est généré et stocké par la requête elle-même : ainsi, un CREATE TOKEN dont le résultat n’atteint jamais le client — une connexion perdue pendant l’envoi de la ligne, ou un INTO OUTFILE que le client ne peut pas ouvrir — laisse derrière lui une méthode d’authentification que personne ne peut utiliser et qui est malgré tout décomptée de cette limite. Personne ne détient un tel secret : il n’existe que pendant l’exécution de la requête. Une requête rejetée avant son exécution, y compris lorsque sa clause FORMAT désigne un format inutilisable, n’ajoute rien.

CREATE TOKEN ne prend pas en charge la clause ON CLUSTER. Utilisez un stockage des accès replicated (ou exécutez la requête sur chaque nœud avec l’instruction équivalente ALTER USER ... ADD IDENTIFIED WITH sha256_hash) pour qu’un token fonctionne sur l’ensemble d’un cluster dont les entités d’accès sont stockées localement.

​

Considérations de sécurité

VALID UNTIL et GRANTS restreignent les sessions qui s’authentifient avec le token. Ils ne restreignent pas ce que ces sessions laissent derrière elles :

• L’échéance est vérifiée lorsqu’une session s’authentifie avec le token. Une session déjà ouverte, ou une query déjà en cours d’exécution, ne sont pas interrompues à l’expiration du token.
• Tout ce qu’une session crée survit au token, et un objet qui travaille de manière autonome poursuit son activité : une refreshable materialized view continue de se rafraîchir, une materialized view attachée à un streaming table engine tel que Kafka, RabbitMQ, NATS ou S3Queue continue de consommer, et un dictionary doté d’un LIFETIME continue de se recharger, bien après l’expiration du token. Une view effectue ce travail avec les droits de son DEFINER, qui est par défaut l’utilisateur ayant créé la view — soit les droits complets de cet utilisateur, et non ceux que la clause GRANTS du token lui avait laissés.

Un token autorisé à créer des tables, des views ou des dictionaries peut donc, en pratique, repousser ses deux limites : il peut laisser derrière lui une tâche persistante qui continue de s’exécuter après l’échéance et qui fait, avec les droits de l’utilisateur, ce que le token lui-même n’avait pas le droit de faire. N’accordez à un token que ce dont l’application a besoin — généralement SELECT et INSERT sur des tables nommées — et excluez CREATE TABLE, CREATE VIEW, CREATE DICTIONARY ainsi que les privilèges ACCESS MANAGEMENT de sa clause GRANTS lorsque ces limites doivent réellement tenir.

Une session qui s’est authentifiée avec un token comportant une clause GRANTS ne peut émettre aucun token : l’ajout d’une méthode d’authentification à un utilisateur existant lui est refusé. La clause GRANTS d’une nouvelle méthode d’authentification est croisée, à la connexion, avec les droits d’accès de l’utilisateur, et non avec ceux de la session qui a créé la method ; ce serait sinon un moyen d’élargir la limite.