Saltar al contenido principal
Esta página no se aplica a ClickHouse Cloud. La funcionalidad documentada aquí no está disponible en los servicios de ClickHouse Cloud. Consulta la guía de ClickHouse sobre compatibilidad con Cloud para obtener más información.
Esta guía proporciona una configuración sencilla y mínima para configurar la autenticación con certificados SSL de usuario. Este tutorial se basa en la guía de Configuring TLS.
La autenticación de usuarios mediante SSL es compatible cuando se utilizan las interfaces https, native, mysql y postgresql.Los nodos de ClickHouse deben tener configurado <verificationMode>strict</verificationMode> para una autenticación segura (aunque relaxed funcionará con fines de prueba).Si utiliza AWS NLB con la interfaz MySQL, debe solicitar al soporte de AWS que habilite la siguiente opción no documentada:
Me gustaría poder configurar el protocolo proxy v2 de nuestro NLB como se indica a continuación: proxy_protocol_v2.client_to_server.header_placement,Value=on_first_ack.

​
1. Crear certificados de usuario SSL

Este ejemplo usa certificados autofirmados con una CA autofirmada. Para entornos de producción, cree una CSR y envíela a su equipo de PKI o a su proveedor de certificados para obtener un certificado válido.
  1. Genere una Certificate Signing Request (CSR) y una clave. El formato básico es el siguiente: 
    openssl req -newkey rsa:2048 -nodes -subj "/CN=<my_host>:<my_user>"  -keyout <my_cert_name>.key -out <my_cert_name>.csr
    En este ejemplo, usaremos estos valores para el dominio y el usuario que se utilizarán en este entorno de ejemplo: 
    openssl req -newkey rsa:2048 -nodes -subj "/CN=chnode1.marsnet.local:cert_user"  -keyout chnode1_cert_user.key -out chnode1_cert_user.csr
El CN es arbitrario y puede usarse cualquier cadena como identificador del certificado. Se utiliza al crear el usuario en los pasos siguientes.
  1. Genere y firme el nuevo certificado de usuario que se utilizará para la autenticación. El formato básico es el siguiente: 
    openssl x509 -req -in <my_cert_name>.csr -out <my_cert_name>.crt -CA <my_ca_cert>.crt -CAkey <my_ca_cert>.key -days 365
    En este ejemplo, usaremos estos valores para el dominio y el usuario que se utilizarán en este entorno de ejemplo: 
    openssl x509 -req -in chnode1_cert_user.csr -out chnode1_cert_user.crt -CA marsnet_ca.crt -CAkey marsnet_ca.key -days 365

​
2. Crear un usuario SQL y otorgar permisos

Para obtener más información sobre cómo habilitar usuarios SQL y establecer roles, consulta la guía Definición de usuarios y roles SQL.
  1. Crea un usuario SQL configurado para usar autenticación mediante certificado: 
    CREATE USER cert_user IDENTIFIED WITH ssl_certificate CN 'chnode1.marsnet.local:cert_user';
  2. Otorga privilegios al nuevo usuario con certificado: 
    GRANT ALL ON *.* TO cert_user WITH GRANT OPTION;
En este ejercicio, al usuario se le otorgan privilegios administrativos completos únicamente con fines de demostración. Consulta la documentación de RBAC de ClickHouse para ver la configuración de permisos.
Recomendamos usar SQL para definir usuarios y roles. Sin embargo, si actualmente defines usuarios y roles en archivos de configuración, la definición del usuario sería así:
<users>
    <cert_user>
        <ssl_certificates>
            <common_name>chnode1.marsnet.local:cert_user</common_name>
        </ssl_certificates>
        <networks>
            <ip>::/0</ip>
        </networks>
        <profile>default</profile>
        <access_management>1</access_management>
        {/* opciones adicionales*/}
    </cert_user>
</users>

​
3. Pruebas

  1. Copie el certificado del usuario, la clave del usuario y el certificado de la CA a un nodo remoto.
  2. Configure OpenSSL en la configuración del cliente de ClickHouse con el certificado y las rutas correspondientes. 
    <openSSL>
    <client>
        <certificateFile>my_cert_name.crt</certificateFile>
        <privateKeyFile>my_cert_name.key</privateKeyFile>
        <caConfig>my_ca_cert.crt</caConfig>
    </client>
</openSSL>
  3. Ejecute clickhouse-client. 
    clickhouse-client --user <my_user> --query 'SHOW TABLES'
Tenga en cuenta que la contraseña proporcionada a clickhouse-client se ignora cuando se especifica un certificado en la configuración.

​
4. Prueba de HTTP

  1. Copie el certificado de usuario, la clave de usuario y el certificado de la CA en un nodo remoto.
  2. Use curl para probar un comando SQL de Example. El formato básico es: 
    echo 'SHOW TABLES' | curl 'https://<clickhouse_node>:8443' --cert <my_cert_name>.crt --key <my_cert_name>.key --cacert <my_ca_cert>.crt -H "X-ClickHouse-SSL-Certificate-Auth: on" -H "X-ClickHouse-User: <my_user>" --data-binary @-
    Por ejemplo: 
    echo 'SHOW TABLES' | curl 'https://chnode1:8443' --cert chnode1_cert_user.crt --key chnode1_cert_user.key --cacert marsnet_ca.crt -H "X-ClickHouse-SSL-Certificate-Auth: on" -H "X-ClickHouse-User: cert_user" --data-binary @-
    El resultado será similar al siguiente: 
    INFORMATION_SCHEMA
default
information_schema
system
Tenga en cuenta que no se especificó ninguna contraseña; el certificado se utiliza en lugar de una contraseña y así es como ClickHouse autenticará al usuario.

​
Resumen

Este artículo presentó los conceptos básicos para crear y configurar un usuario para la autenticación mediante certificado SSL. Este método puede utilizarse con clickhouse-client o con cualquier cliente compatible con la interfaz https y en el que se puedan establecer encabezados HTTP. El certificado y la clave generados deben mantenerse privados y con acceso restringido, ya que el certificado se utiliza para autenticar y autorizar al usuario a realizar operaciones en la base de datos de ClickHouse. Trate el certificado y la clave como si fueran contraseñas.
Última modificación el 10 de junio de 2026