Authentification JWT

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 :

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.

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

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.

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

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

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 nom d’utilisateur, en revanche, est volatile. Il est construit comme suit :

JWT::<subject>::<claims_hash>

Le <claims_hash> est un hash dérivé des claims iss, sub et aud, ainsi que des claims clickhouse:roles et clickhouse:grants. Les claims iss et aud n’interviennent que via ce hash ; ils ne sont plus intégrés directement dans le préfixe visible du nom d’utilisateur. Cela permet de conserver un nom compact et lisible lorsque iss/aud sont de longues URL opaques d’IdP (par exemple, Microsoft Entra ou Okta), tout en garantissant que des tuples (iss, sub, aud) distincts et des ensembles clickhouse:roles / clickhouse:grants distincts correspondent à des noms distincts et stables. Les claims qui n’entrent pas dans le calcul du hash (par exemple iat, exp, nbf ou des claims personnalisés sans rapport) ne modifient pas le nom d’utilisateur.

La partie <claims_hash> change chaque fois que les claims clickhouse:roles ou clickhouse:grants changent. Cela signifie que des jetons 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)

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.

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.

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.

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::jane.doe::<claims_hash>';

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.

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.

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>'

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()'

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

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 :

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.

En plus de l’authentificateur intégré, vous pouvez configurer votre service ClickHouse Cloud pour accepter les JWT émis par votre propre fournisseur d’identité (par exemple, Microsoft Entra ou Okta). Cette fonctionnalité bêta est disponible avec le plan Enterprise pour les services exécutant ClickHouse version 26.4 ou ultérieure. Vous pouvez la configurer vous-même depuis la Cloud Console, sous Settings → Security → JWT authentication — consultez Configuration de l’authentification JWT pour obtenir des instructions étape par étape. Chaque fournisseur est défini par les éléments suivants :

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.

• 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.