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.
Le flux d’authentification fonctionne comme suit :
- 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).
- ClickHouse valide la signature du jeton.
- Les claims obligatoires (
exp, iat, iss, sub, aud) sont vérifiés.
- 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.
- Lorsque le jeton expire, une tâche de garbage collection en arrière-plan supprime l’utilisateur.
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. |
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 RSAAlors 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.
| 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é. |
| 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
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>
<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é.
Les droits d’accès effectifs sont calculés comme suit :
effective_rights = permission_limit ∩ (token_grants ∪ token_roles)
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.
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
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
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.
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
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.
Passer directement un jeton
--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.
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
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
--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 |
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
- 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.
