Authentification JWT

Guide de l’authentification par JWT et des utilisateurs éphémères dans ClickHouse Cloud

ClickHouse peut authentifier les utilisateurs à l’aide de JSON Web Tokens (JWT). Contrairement à d’autres mécanismes d’authentification externes, comme LDAP ou Kerberos, l’authentification JWT ne vérifie pas l’identité d’utilisateurs déjà existants. Elle crée à la place dynamiquement des utilisateurs éphémères à partir des claims intégrés à chaque jeton. Ces utilisateurs n’existent qu’en mémoire, reçoivent des droits d’accès dérivés des claims du jeton et sont automatiquement supprimés à l’expiration du jeton.

L’authentification JWT se distingue donc fondamentalement des méthodes basées sur un mot de passe ou un certificat : il n’existe pas d’instruction CREATE USER ... IDENTIFIED WITH jwt, et toute tentative en ce sens provoque une exception. Les utilisateurs JWT sont entièrement gérés par le cycle de vie du jeton.

​

Vue d’ensemble

Le flux d’authentification fonctionne comme suit :

1. Un client présente un JWT signé via l’un des mécanismes de transport pris en charge (en-tête HTTP Authorization: Bearer, protocole natif TCP ou champ gRPC jwt).
2. ClickHouse valide la signature du jeton.
3. Les claims obligatoires (exp, iat, iss, sub, aud) sont vérifiés.
4. Un utilisateur éphémère est créé en mémoire avec des droits d’accès dérivés des claims de jeton clickhouse:grants et clickhouse:roles, recoupés avec une limite d’autorisations.
5. Lorsque le jeton expire, une tâche de garbage collection en arrière-plan supprime l’utilisateur.

​

Claim du jeton

​

Claims obligatoires

Chaque JWT présenté à ClickHouse doit contenir les claims suivants :

Claim	Description
alg	Algorithme de signature (claim d’en-tête). Valeurs prises en charge : HS256, RS256, ES256.
exp	Heure d’expiration. Définit le valid_until de l’utilisateur éphémère.
iat	Heure d’émission. Utilisée pour empêcher la réutilisation d’anciens jetons pour la même identité.
iss	Émetteur. Comparé à l’émetteur attendu du fournisseur.
sub	Sujet. Devient une partie du nom d’utilisateur généré.
aud	Audience. Comparée à l’audience attendue du fournisseur.

Le claim d’en-tête kid (ID de clé) est également requis lorsque la résolution de clés basée sur JWKS est utilisée.

Le mode JWKS prend uniquement en charge les clés RSA

Alors que les fournisseurs à clé statique acceptent HS256, RS256 ou ES256, les fournisseurs basés sur JWKS n’acceptent que les JWK dont le kty est RSA (c.-à-d. les jetons signés avec RS256). Les jetons signés avec des clés HMAC (HS256) ou EC (ES256) ne peuvent pas être vérifiés via un endpoint JWKS et seront rejetés.

​

Autres claims reconnues

Claim	Description
nbf	Instant « not before ». Ce claim n’est pas obligatoire, mais s’il est présent, les jetons sont rejetés avant cet instant.
jti	Réservé. Accepté dans les jetons, mais n’est actuellement ni validé ni utilisé.

​

Claims facultatifs

Claim	Nom par défaut	Description
Privilèges	clickhouse:grants	Un tableau JSON de fragments SQL GRANT, par exemple ["SELECT ON db.*", "INSERT ON db.table1"]. Chaque élément est interprété comme le corps d’une instruction GRANT.
Rôles	clickhouse:roles	Un tableau JSON de noms de rôles à attribuer, par exemple ["analyst", "reader"].
Les noms de claim par défaut peuvent être redéfinis avec des noms de claim personnalisés si votre fournisseur d’identité utilise des conventions de nommage différentes.

​

Exemple de jeton, d’en-tête et de charge utile

{
  "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"]
}

​

Comportement des utilisateurs éphémères

Les utilisateurs JWT se distinguent des utilisateurs ClickHouse classiques à plusieurs égards importants.

​

Identité et nommage

Chaque utilisateur JWT se voit attribuer un UUID déterministe calculé à partir des claims iss, sub et aud. Cet UUID est stable d’une connexion à l’autre. Un utilisateur qui se connecte plusieurs fois avec des jetons différents (mais avec le même émetteur, le même sujet et la même audience) obtient toujours le même UUID.

Le username, en revanche, est volatile. Il est construit comme suit :

JWT::<issuer>::<audience>::<subject>::<claims_hash>

La partie <claims_hash> change chaque fois que les claims clickhouse:roles ou clickhouse:grants changent. Cela signifie que des tokens avec des ensembles de rôles ou de grants différents produisent des noms d’utilisateur différents, même pour la même identité.

​

Droits d’accès

Les droits d’accès effectifs sont calculés comme suit :

effective_rights = permission_limit ∩ (token_grants ∪ token_roles)

Ici, permission_limit correspond à l’ensemble des droits d’accès détenus par un rôle ou un utilisateur de référence, configuré comme limite supérieure. Les droits demandés par le jeton qui dépassent cette limite sont silencieusement supprimés.

​

Fraîcheur du jeton

ClickHouse suit la claim iat (issued-at) du jeton authentifié le plus récemment pour chaque identité stable. Si un jeton dont le iat est identique à la valeur enregistrée ou lui est antérieur est présenté, le serveur réutilise l’utilisateur éphémère existant sans réévaluer les claims. Cela empêche d’anciens jetons de réduire les autorisations d’un utilisateur.

​

Durée de vie et garbage collection

Les utilisateurs éphémères sont créés lorsqu’un jeton est authentifié pour la première fois, puis supprimés par une tâche de garbage collection exécutée en arrière-plan une fois valid_until (dérivé de exp) dépassé. L’intervalle du GC est défini par le paramètre gc_interval (par défaut : 5 minutes).

Entre deux exécutions du GC, les utilisateurs expirés peuvent encore apparaître dans system.users, mais ne peuvent plus s’authentifier.

​

Attributions d’accès persistantes

Comme l’UUID est stable, vous pouvez attribuer des profils de paramètres, des quotas, des politiques d’accès aux lignes et des politiques de masquage des colonnes à un utilisateur JWT à l’aide d’instructions SQL. Ces attributions sont conservées dans le stockage du contrôle d’accès (sur disque ou dans ZooKeeper) et restent valides après l’expiration du jeton et une nouvelle authentification.

Identifiez l’utilisateur par son nom d’utilisateur actuel :

ALTER SETTINGS PROFILE my_profile ADD TO 'JWT::ClickHouse::my-service-id::jane.doe::<claims-hash>';

Le nom d’utilisateur et l’UUID d’une identité donnée se trouvent dans les colonnes name et id de system.users tant que l’utilisateur est actif.

Notez que ALTER USER ne fonctionne pas directement sur les utilisateurs JWT, car ils sont en lecture seule. Pour attribuer des profils de paramètres, des quotas ou des politiques, utilisez les instructions ALTER SETTINGS PROFILE, ALTER QUOTA ou ALTER ROW POLICY comme indiqué ci-dessus.

​

Différences avec les utilisateurs classiques

Fonctionnalité	Utilisateurs JWT	Utilisateurs classiques
Création	Automatique à partir des claims du jeton	Instruction CREATE USER
Stockage	En mémoire uniquement (éphémère)	Disque, ZooKeeper ou fichier de configuration
CREATE USER ... IDENTIFIED WITH jwt	Non pris en charge (génère une exception)	Tous les autres types d’authentification sont pris en charge
ALTER USER / DROP USER	Non pris en charge	Pris en charge
Sauvegarde et restauration	Non incluses	Incluses
Nom d’utilisateur	Généré automatiquement, volatil	Défini par l’administrateur, fixe
UUID	Déterministe à partir de iss+sub+aud	Aléatoire au moment de la création
Durée de vie	Limitée par le exp du jeton	Jusqu’à suppression explicite
Droits d’accès	Dérivés des claims du jeton, plafonnés par la limite de permissions	Accordés explicitement via GRANT
Restrictions d’hôte	Configuration réseau propre au fournisseur	Clause HOST par utilisateur
Profils de paramètres	Attribuables par UUID (persistants)	Configurables directement
Quotas et politiques de lignes	Attribuables par UUID (persistants)	Configurables directement
Rôles par défaut	Non configurables	Configurables

​

Vues avec SQL SECURITY DEFINER

Lorsqu’un utilisateur JWT éphémère crée une vue avec SQL SECURITY DEFINER, le serveur crée automatiquement une copie fantôme permanente de l’utilisateur pour faire office de définisseur de la vue. Cet utilisateur fantôme :

• A pour nom <original_jwt_username>:definer
• A NO_AUTHENTICATION (ne peut pas être utilisé pour se connecter)
• Conserve les mêmes droits d’accès que l’utilisateur JWT d’origine au moment de la création de la vue

Cela garantit que la vue continue de fonctionner après l’expiration du jeton de l’utilisateur éphémère et la suppression de l’utilisateur d’origine par le garbage collector.

​

Utilisation du client

​

Passer directement un jeton

Utilisez le flag --jwt avec clickhouse-client pour vous authentifier à l’aide d’un jeton obtenu au préalable :

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

Les options --jwt et --user sont mutuellement exclusives. Lorsque --jwt est spécifié, le nom d’utilisateur est déduit du jeton.

​

Interface HTTP

Envoyez le jeton sous forme de Bearer token dans l’en-tête Authorization :

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

Envoyez toujours les JWT via HTTPS. Un Bearer token envoyé sur une connexion HTTP non chiffrée est exposé à toute personne présente sur le trajet réseau et revient à divulguer ce secret d’authentification.

​

Connexion OAuth2 par code d’appareil

Le clickhouse-client prend en charge un flux interactif de code d’appareil OAuth2 via l’option --login. Pour les endpoints ClickHouse Cloud, le client effectue automatiquement un échange de jeton afin d’obtenir un JWT spécifique à ClickHouse. Les jetons sont renouvelés de manière transparente pendant la session. Lorsqu’un nouveau jeton est obtenu, le client se reconnecte automatiquement.

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

​

Authentificateur JWT intégré à ClickHouse Cloud

Chaque service ClickHouse Cloud inclut un authentificateur JWT prédéfini, utilisé par la SQL Console et le flux --login de clickhouse-client. Cet authentificateur est configuré comme suit :

Paramètre	Valeur
iss (émetteur)	ClickHouse
aud (audience)	L’UUID du service (visible dans l’URL de la Cloud Console)
sub (sujet)	L’adresse e-mail de votre compte ClickHouse Cloud

L’authentificateur intégré a une limite d’autorisations définie sur le rôle default_role et l’utilisateur default. Cela signifie que les droits effectifs de tout utilisateur JWT résultent de l’intersection avec les grants accordés à ces deux entités : un token ne peut donc jamais obtenir plus de privilèges que ce que default_role et default sont autorisés à faire.

Vous n’avez rien à configurer pour utiliser cet authentificateur. Il est provisionné automatiquement lors de la création du service.

​

Communication interserveur

Lorsqu’une requête est redirigée vers un autre segment ou une autre réplique, le jeton JWT est inclus dans le protocole de communication interserveur. Le nœud distant réauthentifie le jeton de manière autonome, en créant son propre utilisateur éphémère.

​

Dépannage

• Aucun droit d’accès accordé : Le rôle ou l’utilisateur référencé peut ne pas avoir les grants requis. Assurez-vous que les rôles référencés dans clickhouse:roles existent et incluent les grants appropriés.
• Jeton rejeté : Vérifiez que iss, aud et l’algorithme de signature de votre jeton correspondent à ce qu’attend le fournisseur JWT. Si JWKS est utilisé, assurez-vous que le kid du jeton correspond à une clé du jeu de clés du fournisseur.
• L’utilisateur disparaît entre les requêtes : Les utilisateurs éphémères sont supprimés après l’expiration du jeton. Utilisez un client prenant en charge le renouvellement du jeton (par exemple, le mode --login) pour les sessions de longue durée.
• CREATE USER ... IDENTIFIED WITH jwt échoue : C’est normal. Les utilisateurs JWT ne peuvent pas être créés via DDL. Leur gestion repose entièrement sur le cycle de vie du jeton.