Configuración de autenticación con JWT

ClickHouse Cloud permite autenticar las conexiones a un servicio mediante JSON Web Tokens (JWT) validados con sus propios endpoints de JSON Web Key Set (JWKS). En lugar de gestionar credenciales de base de datos, su proveedor de identidad emite tokens de corta duración que ClickHouse verifica con las claves públicas publicadas en una URL de JWKS que usted configure.

Puede configurar estos proveedores de JWKS para cada servicio desde Configuración → Seguridad en la consola de ClickHouse Cloud.

Para configurar proveedores de JWT para un servicio, necesita:

• Una organización con el plan Enterprise.
• Un servicio que ejecute ClickHouse versión 26.4 o posterior.
• Un rol con el permiso control-plane:service:manage en el servicio (por ejemplo, Admin o Service admin). Los miembros que no cuenten con él verán la sección en modo de solo lectura.
• Una URL de JWKS HTTPS accesible públicamente que publique al menos una clave RSA (RS256) o, para servicios con versión 26.8 o posterior, una clave EC (ES256, ES384, ES512).

El Client (su proveedor de identidad o aplicación) genera un JWT y lo firma con su clave privada. El token debe seguir el formato de token previsto. A continuación, ClickHouse lo verifica con las claves públicas publicadas en su URL de JWKS:

1. ClickHouse lee el encabezado kid (ID de clave) del token y selecciona la clave correspondiente de su documento JWKS.
2. Verifica la firma del token con esa clave pública y comprueba las claims iss (emisor) y aud (audiencia) con la configuración de su proveedor.
3. Si la verificación se realiza correctamente, la conexión se establece como un usuario efímero cuyos derechos de acceso proceden de las claims clickhouse:grants y clickhouse:roles del token, limitados por el límite de permisos (el usuario default). Consulte Derechos de acceso para obtener más información.

ClickHouse valida y obtiene la URL de JWKS al añadir o actualizar un proveedor, por lo que las URL mal configuradas o inaccesibles se rechazan de inmediato.

Abra la configuración de seguridad del servicio

Vaya a su servicio, abra Settings y desplácese hasta la sección Security. Localice la tarjeta autenticación con JWT.

Abra el panel de proveedores

Seleccione Set up JWT providers (o Manage JWT providers si ya tiene alguno). Se abrirá un panel con un formulario para añadir un nuevo proveedor.

Complete los datos del proveedor

Complete el formulario del proveedor y seleccione Save.

Campo	Descripción
Name	Un nombre único para este proveedor en el servicio. No se puede modificar después de crearlo.
Issuer	El claim iss esperado de los tokens entrantes.
Audience	El claim aud esperado de los tokens entrantes.
URL de JWKS	La URL HTTPS pública que publica las claves públicas utilizadas para verificar las firmas de los tokens.
Roles claim (opcional)	El claim del token del que se leen los roles de ClickHouse. Déjelo en blanco para usar el nombre de claim predeterminado clickhouse:roles. Los roles indicados en el token deben existir previamente en el servicio.

Añada más proveedores si es necesario

Use Add another provider para configurar proveedores adicionales. Un servicio puede tener un máximo de cinco proveedores de JWT.

• Se permite un máximo de cinco proveedores de JWT por servicio.
• Los proveedores de JWKS aceptan claves RSA (RS256) y, a partir de la versión 26.8, claves EC (ES256, ES384, ES512).
• La URL de JWKS debe ser un endpoint HTTPS público. Se rechazan las direcciones privadas, internas o de enlace local.

• Autenticación con JWT — claims de token, usuarios efímeros y uso del Client.