Autenticación con JWT

ClickHouse puede autenticar usuarios mediante JSON Web Tokens (JWT). A diferencia de otros autenticadores externos, como LDAP o Kerberos, la autenticación con JWT no verifica la identidad de usuarios preexistentes. En su lugar, crea dinámicamente usuarios efímeros a partir de los claims incluidos en cada token. Estos usuarios existen solo en memoria, reciben derechos de acceso derivados de los claims del token y se eliminan automáticamente cuando el token caduca.

Esto hace que la autenticación con JWT sea fundamentalmente distinta de los métodos basados en contraseñas o certificados: no existe ninguna sentencia CREATE USER ... IDENTIFIED WITH jwt, e intentar hacerlo genera una excepción. Los usuarios JWT se gestionan por completo a través del ciclo de vida del token.

El flujo de autenticación funciona de la siguiente manera:

1. Un cliente presenta un JWT firmado a través de uno de los mecanismos de transporte compatibles (el encabezado HTTP Authorization: Bearer, el protocolo nativo TCP o el campo jwt de gRPC).
2. ClickHouse valida la firma del token.
3. Se verifican las claims obligatorias (exp, iat, iss, sub, aud).
4. Se crea en memoria un usuario efímero con derechos de acceso derivados de las claims del token clickhouse:grants y clickhouse:roles, acotados por un límite de permisos.
5. Cuando el token caduca, una tarea de recolección de basura en segundo plano elimina al usuario.

Todo JWT presentado a ClickHouse debe contener los siguientes claims:

El claim kid (ID de clave) del encabezado también es obligatorio cuando se usa la resolución de claves basada en JWKS.

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

Los usuarios JWT se diferencian de los usuarios habituales de ClickHouse en varios aspectos importantes.

Cada usuario JWT recibe un UUID determinista calculado a partir de las claims iss, sub y aud. Este UUID es estable entre inicios de sesión. Un usuario que inicia sesión varias veces con distintos tokens (pero con el mismo emisor, sujeto y audiencia) siempre obtiene el mismo UUID.

Sin embargo, el nombre de usuario es volátil. Se construye así:

JWT::<subject>::<claims_hash>

El <claims_hash> es un hash derivado de las claims iss, sub y aud, junto con las claims clickhouse:roles y clickhouse:grants. Las claims iss y aud participan solo a través de este hash; ya no se incorporan directamente en el prefijo visible del nombre de usuario. Esto mantiene el nombre compacto y legible cuando iss/aud son URL de IdP largas y opacas (por ejemplo, Microsoft Entra u Okta), al tiempo que sigue garantizando que las tuplas (iss, sub, aud) distintas y los conjuntos distintos de clickhouse:roles / clickhouse:grants se asignen a nombres distintos y estables. Las claims que no intervienen en el hash (por ejemplo iat, exp, nbf o claims personalizadas no relacionadas) no cambian el nombre de usuario.

La parte <claims_hash> cambia cada vez que cambian las claims clickhouse:roles o clickhouse:grants. Esto significa que los tokens con distintos conjuntos de roles o permisos generan nombres de usuario diferentes incluso para la misma identidad.

Los permisos de acceso efectivos se calculan así:

effective_rights = permission_limit ∩ (token_grants ∪ token_roles)

donde permission_limit es el conjunto de derechos de acceso de un rol o usuario de referencia configurado como límite superior. Los derechos solicitados por el token que superen ese límite se descartan silenciosamente.

ClickHouse registra la claim iat (issued-at) del token autenticado más reciente para cada identidad estable. Si se presenta un token con un iat igual o anterior al valor almacenado, el server reutiliza el usuario efímero existente sin volver a evaluar las claims. Esto evita que tokens más antiguos reduzcan los permisos de un usuario.

Los usuarios efímeros se crean cuando un token se autentica por primera vez y una tarea de recolección de basura en segundo plano los elimina una vez transcurrido valid_until (derivado de exp). El intervalo de GC se controla mediante el parámetro gc_interval (valor predeterminado: 5 minutos).

Entre una ejecución de GC y la siguiente, es posible que los usuarios expirados sigan apareciendo en system.users, pero ya no podrán autenticarse.

Como el UUID es estable, puede asignar perfiles de configuración, cuotas, políticas de fila y políticas de enmascaramiento de columnas a un usuario JWT mediante sentencias SQL. Estas asignaciones se conservan en el almacenamiento de control de acceso (en disco o en ZooKeeper) y persisten tras el vencimiento del token y la nueva autenticación.

Haga referencia al usuario mediante su nombre de usuario actual:

ALTER SETTINGS PROFILE my_profile ADD TO 'JWT::jane.doe::<claims_hash>';

Ten en cuenta que ALTER USER no funciona directamente con los usuarios JWT, ya que son de solo lectura. Para asignar perfiles de configuración, cuotas o políticas, usa las sentencias ALTER SETTINGS PROFILE, ALTER QUOTA o ALTER ROW POLICY, como se muestra arriba.

Cuando un usuario JWT efímero crea una vista con SQL SECURITY DEFINER, el servidor crea automáticamente una copia persistente de sombra del usuario para que actúe como definidor de la vista. Este usuario de sombra:

• Tiene el nombre <original_jwt_username>:definer
• Tiene NO_AUTHENTICATION (no se puede usar para iniciar sesión)
• Conserva los mismos derechos de acceso que el usuario JWT original en el momento en que se creó la vista

Esto garantiza que la vista siga funcionando después de que expire el token del usuario efímero y de que el usuario original sea eliminado automáticamente.

Use la opción --jwt con clickhouse-client para autenticarse con un token obtenido previamente:

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

Envía el token como token Bearer en la cabecera Authorization:

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

clickhouse-client admite un flujo interactivo de código de dispositivo de OAuth2 mediante la opción --login. En los endpoints de ClickHouse Cloud, el cliente realiza automáticamente el intercambio de tokens para obtener un JWT específico de ClickHouse. Los tokens se renuevan de forma transparente durante la sesión. Cuando se obtiene un token nuevo, el cliente se reconecta automáticamente.

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

Cada servicio de ClickHouse Cloud incluye un autenticador JWT predefinido que usan SQL Console y el flujo --login de clickhouse-client. Este autenticador está configurado con:

El autenticador integrado tiene como límite de permisos el rol default_role y el usuario default. Esto significa que los permisos efectivos de cualquier usuario JWT quedan limitados a la intersección de los grants de esas dos entidades, por lo que un token nunca puede elevar privilegios más allá de lo que default_role y default tienen permitido hacer.

No necesitas configurar nada para usar este autenticador. Se aprovisiona automáticamente cuando se crea el servicio.

Además del autenticador JWT predefinido, puede configurar su servicio de ClickHouse Cloud para que acepte JWT emitidos por su propio proveedor de identidad (por ejemplo, Microsoft Entra u Okta). Esta función beta está disponible en el plan Enterprise para servicios que ejecutan ClickHouse versión 26.4 o posterior. Puede configurarla usted mismo desde la consola de Cloud en Configuración → Seguridad → Autenticación con JWT; consulte Configuración de la autenticación con JWT para obtener instrucciones paso a paso. Cada proveedor se define mediante lo siguiente:

Cuando una consulta se reenvía a otro segmento o réplica, el token JWT se incluye en el protocolo interservidor. El nodo remoto vuelve a autenticar el token de forma independiente, creando su propio usuario efímero.

• No se han concedido permisos de acceso: Es posible que el rol o usuario al que se hace referencia no tenga los grants necesarios. Asegúrese de que los roles mencionados en clickhouse:roles existan e incluyan los grants adecuados.
• Token rechazado: Verifique que iss, aud y el algoritmo de firma de su token coincidan con lo que espera el proveedor de JWT. Si se usa JWKS, asegúrese de que el kid del token coincida con una clave del conjunto de claves del proveedor.
• El usuario desaparece entre consultas: Los usuarios efímeros se eliminan cuando vence el token. Use un cliente que admita la renovación del token (por ejemplo, el modo --login) para sesiones de larga duración.
• CREATE USER ... IDENTIFIED WITH jwt falla: Esto es normal. Los usuarios JWT no pueden crearse mediante DDL. Su gestión depende por completo del ciclo de vida del token.