Saltar al contenido principal
La sección users del archivo de configuración users.xml contiene la configuración de los usuarios.
ClickHouse también admite el flujo de trabajo basado en SQL para administrar usuarios. Recomendamos utilizarlo.
Estructura de la sección users: 
<users>
    <!-- Si no se especificó el nombre de usuario, se utiliza el usuario 'default'. -->
    <user_name>
        <!-- Solo se puede especificar un método de autenticación en el nivel users.user_name. Por ejemplo: -->
        <password></password>
        <!-- O (exclusivo) -->
        <password_sha256_hex></password_sha256_hex>
 
        <!-- O (exclusivo) (N.B. se permiten múltiples claves SSH por compatibilidad con versiones anteriores) -->
        <ssh_keys>
            <ssh_key>
                <type>ssh-ed25519</type>
                <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
            </ssh_key>
            <ssh_key>
                <type>ecdsa-sha2-nistp256</type>
                <base64_key>AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNxeV2uN5UY6CUbCzTA1rXfYimKQA5ivNIqxdax4bcMXz4D0nSk2l5E1TkR5mG8EBWtmExSPbcEPJ8V7lyWWbA8=</base64_key>
            </ssh_key>
            <ssh_key>
                <type>ssh-rsa</type>
                <base64_key>AAAAB3NzaC1yc2EAAAADAQABAAABgQCpgqL1SHhPVBOTFlOm0pu+cYBbADzC2jL41sPMawYCJHDyHuq7t+htaVVh2fRgpAPmSEnLEC2d4BEIKMtPK3bfR8plJqVXlLt6Q8t4b1oUlnjb3VPA9P6iGcW7CV1FBkZQEVx8ckOfJ3F+kI5VsrRlEDgiecm/C1VPl0/9M2llW/mPUMaD65cM9nlZgM/hUeBrfxOEqM11gDYxEZm1aRSbZoY4dfdm3vzvpSQ6lrCrkjn3X2aSmaCLcOWJhfBWMovNDB8uiPuw54g3ioZ++qEQMlfxVsqXDGYhXCrsArOVuW/5RbReO79BvXqdssiYShfwo+GhQ0+aLWMIW/jgBkkqx/n7uKLzCMX7b2F+aebRYFh+/QXEj7SnihdVfr9ud6NN3MWzZ1ltfIczlEcFLrLJ1Yq57wW6wXtviWh59WvTWFiPejGjeSjjJyqqB49tKdFVFuBnIU5u/bch2DXVgiAEdQwUrIp1ACoYPq22HFFAYUJrL32y7RxX3PGzuAv3LOc=</base64_key>
            </ssh_key>
        </ssh_keys>

        <!-- O (exclusivo) para múltiples métodos de autenticación: -->
        <auth_methods>
            <method1>
                <password></password>
            </method1>
            <method2>
                <password_sha256_hex></password_sha256_hex>
            </method2>
            <!-- ... -->
            <methodN>
                <!-- ... -->
            </methodN>
        </auth_methods>

        <access_management>0|1</access_management>

        <networks incl="networks" replace="replace">
        </networks>

        <profile>profile_name</profile>

        <quota>default</quota>
        <default_database>default</default_database>
        <databases>
            <database_name>
                <table_name>
                    <filter>expression</filter>
                </table_name>
            </database_name>
        </databases>

        <grants>
            <query>GRANT SELECT ON system.*</query>
        </grants>
    </user_name>
    <!-- Configuración de otros usuarios -->
</users>

​
user_name/password

La contraseña se puede especificar en texto plano o en SHA256 (formato hex).
  • Para asignar una contraseña en texto plano (no recomendado), colóquela en un elemento password. Por ejemplo, <password>qwerty</password>. La contraseña puede dejarse en blanco.
  • Para asignar una contraseña mediante su hash SHA256, colóquela en un elemento password_sha256_hex. Por ejemplo, <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>. Ejemplo de cómo generar una contraseña desde la shell: 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
    La primera línea del resultado es la contraseña. La segunda línea es el hash SHA256 correspondiente.
  • Para mantener la compatibilidad con los clientes MySQL, la contraseña se puede especificar como hash double SHA1. Colóquela en el elemento password_double_sha1_hex. Por ejemplo, <password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>. Ejemplo de cómo generar una contraseña desde la shell: 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
    La primera línea del resultado es la contraseña. La segunda línea es el hash double SHA1 correspondiente.

​
Configuración de autenticación TOTP

La contraseña de un solo uso basada en el tiempo (TOTP) puede utilizarse para autenticar a los usuarios de ClickHouse mediante la generación de códigos de acceso temporales válidos durante un tiempo limitado. Este método de autenticación TOTP cumple con los estándares de RFC 6238, lo que lo hace compatible con aplicaciones TOTP populares como Google Authenticator, 1Password y herramientas similares. Puede configurarse mediante el archivo de configuración users.xml, además de la autenticación basada en contraseña. Aún no es compatible con el control de acceso basado en SQL. Para autenticarse mediante TOTP, los usuarios deben proporcionar una contraseña principal junto con una contraseña de un solo uso generada por su aplicación TOTP mediante la opción de línea de comandos --one-time-password o concatenada a la contraseña principal con el carácter ’+’. Por ejemplo, si la contraseña principal es some_password y el código TOTP generado es 345123, el usuario puede especificar --password some_password+345123 o --password some_password --one-time-password 345123 al conectarse a ClickHouse. Si no se especifica ninguna contraseña, clickhouse-client la solicitará de forma interactiva. Para habilitar la autenticación TOTP para un usuario, configure la sección time_based_one_time_password en users.xml. Esta sección define la configuración de TOTP, como el secreto, el período de validez, la cantidad de dígitos y el algoritmo hash. Ejemplo 
<clickhouse>
    <!-- ... -->
    <users>
        <my_user>
            <!-- Autenticación primaria basada en contraseña: -->
            <password>some_password</password>
            <password_sha256_hex>1464acd6765f91fccd3f5bf4f14ebb7ca69f53af91b0a5790c2bba9d8819417b</password_sha256_hex>
            <!-- ... o cualquier otro método de autenticación compatible ... -->

            <!-- Configuración de autenticación TOTP -->
            <time_based_one_time_password>
                <secret>JBSWY3DPEHPK3PXP</secret>      <!-- Secreto TOTP codificado en Base32 -->
                <period>30</period>                    <!-- Opcional: período de validez del OTP en segundos -->
                <digits>6</digits>                     <!-- Opcional: número de dígitos del OTP -->
                <algorithm>SHA1</algorithm>            <!-- Opcional: algoritmo hash: SHA1, SHA256, SHA512 -->
            </time_based_one_time_password>
        </my_user>
    </users>
</clickhouse>

Parámetros:

- secret - (Obligatorio) La clave secreta codificada en base32 utilizada para generar códigos TOTP.
- period - Opcional. Establece el período de validez de cada OTP en segundos. Debe ser un número positivo que no supere 120. El valor predeterminado es 30.
- digits - Opcional. Especifica el número de dígitos de cada OTP. Debe estar entre 4 y 10. El valor predeterminado es 6.
- algorithm - Opcional. Define el algoritmo hash para generar los OTP. Los valores admitidos son SHA1, SHA256 y SHA512. El valor predeterminado es SHA1.

Generación de un secreto TOTP

Para generar un secreto compatible con TOTP para usarlo con ClickHouse, ejecute el siguiente comando en la terminal:

```bash
$ base32 -w32 < /dev/urandom | head -1
Este comando generará un secreto codificado en base32 que se puede añadir al campo secret de users.xml. Para habilitar TOTP para un usuario específico, añada a cualquier campo existente basado en contraseña (como password o password_sha256_hex) otra sección time_based_one_time_password. La herramienta qrencode puede utilizarse para generar un código QR para el secreto de TOTP. 
$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'
Después de configurar TOTP para un usuario, se puede usar una contraseña de un solo uso como parte del proceso de autenticación, tal como se describe más arriba.

​
nombre de usuario/clave SSH

Esta configuración permite autenticarse con claves SSH. Dada una clave SSH (como la generada con ssh-keygen), por ejemplo 
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj john@example.com
Se espera que el elemento ssh_key sea 
<ssh_key>
     <type>ssh-ed25519</type>
     <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
 </ssh_key>
Sustituya ssh-ed25519 por ssh-rsa o ecdsa-sha2-nistp256 en el caso de los otros algoritmos compatibles.

​
Múltiples métodos de autenticación

Se puede configurar un mismo usuario con varios métodos de autenticación mediante el elemento <auth_methods>. Esto permite que un usuario se autentique con cualquiera de los métodos indicados; por ejemplo, un usuario podría tener tanto una contraseña como una credencial LDAP, y el inicio de sesión con cualquiera de ellas se realizaría correctamente. Cada elemento hijo de <auth_methods> es un contenedor con un nombre arbitrario que incluye exactamente un tipo de autenticación. El nombre del contenedor (p. ej., <method1>, <primary>, <a1>) no importa; solo se utiliza el elemento interno de autenticación. Ejemplo: varias contraseñas 
<users>
    <my_user>
        <auth_methods>
            <primary>
                <password>password_one</password>
            </primary>
            <secondary>
                <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>
            </secondary>
        </auth_methods>
    </my_user>
</users>
Ejemplo: tipos de autenticación mixtos 
<users>
    <my_user>
        <auth_methods>
            <a1>
                <password>plaintext_pass</password>
            </a1>
            <a2>
                <password_sha256_hex>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</password_sha256_hex>
            </a2>
            <a3>
                <ldap>
                    <server>my_ldap_server</server>
                </ldap>
            </a3>
        </auth_methods>
    </my_user>
</users>
Se admiten los siguientes tipos de autenticación dentro de <auth_methods>:
  • password — contraseña en texto plano
  • password_sha256_hex — hash de contraseña SHA256
  • password_scram_sha256_hex — hash de contraseña SCRAM-SHA-256
  • password_double_sha1_hex — hash de contraseña double SHA1
  • ldap — autenticación del servidor LDAP
  • kerberos — autenticación Kerberos
  • ssl_certificates — autenticación mediante certificado SSL
  • ssh_keys — autenticación mediante claves SSH
  • http_authentication — autenticación HTTP
Reglas y restricciones:
  • <auth_methods> no puede usarse junto con métodos de autenticación especificados a nivel del usuario. Use un estilo u otro, no ambos.
  • <auth_methods> debe contener al menos un método de autenticación.
  • Cada elemento contenedor dentro de <auth_methods> debe contener exactamente un tipo de autenticación (con la excepción de <ssh_keys>, que puede contener varios por compatibilidad con versiones anteriores).
  • TOTP (<time_based_one_time_password>) se especifica a nivel del usuario (fuera de <auth_methods>) y se aplica a todos los métodos basados en contraseña de la lista. Se requiere al menos un método basado en contraseña cuando TOTP está habilitado.
Ejemplo: auth_methods con TOTP 
<users>
    <my_user>
        <auth_methods>
            <a1>
                <password>my_password</password>
            </a1>
            <a2>
                <ldap>
                    <server>ldap_server_1</server>
                </ldap>
            </a2>
        </auth_methods>
        <time_based_one_time_password>
            <secret>JBSWY3DPEHPK3PXP</secret>
        </time_based_one_time_password>
    </my_user>
</users>
En este ejemplo, la verificación TOTP se aplica al método basado en contraseña (<password>), mientras que el método LDAP se autentica de forma independiente frente al servidor externo.

​
access_management

Esta configuración habilita o deshabilita el uso del control de acceso y la administración de cuentas basado en SQL para el usuario. Valores posibles:
  • 0 — Deshabilitado.
  • 1 — Habilitado.
Valor predeterminado: 0.

​
grants

Esta configuración permite otorgar cualquier privilegio al usuario seleccionado. Cada elemento de la lista debe ser una consulta GRANT sin beneficiarios especificados. Ejemplo: 
<user1>
    <grants>
        <query>GRANT SHOW ON *.*</query>
        <query>GRANT CREATE ON *.* WITH GRANT OPTION</query>
        <query>GRANT SELECT ON system.*</query>
    </grants>
</user1>
Esta configuración no puede especificarse al mismo tiempo que las opciones dictionaries, access_management, named_collection_control, show_named_collections_secrets y allow_databases.

​
user_name/networks

Lista de redes desde las que el usuario puede conectarse al servidor de ClickHouse. Cada elemento de la lista puede tener una de las siguientes formas:
  • <ip> — Dirección IP o máscara de red. Ejemplos: 213.180.204.3, 10.0.0.1/8, 10.0.0.1/255.255.255.0, 2a02:6b8::3, 2a02:6b8::3/64, 2a02:6b8::3/ffff:ffff:ffff:ffff::.
  • <host> — Nombre de host. Ejemplo: example01.host.ru. Para comprobar el acceso, se realiza una consulta DNS y todas las direcciones IP devueltas se comparan con la dirección remota.
  • <host_regexp> — Expresión regular para nombres de host. Ejemplo: ^example\d\d-\d\d-\d\.host\.ru$ Para comprobar el acceso, se realiza una consulta DNS PTR para la dirección remota y luego se aplica la expresión regular especificada. Después, se realiza otra consulta DNS para los resultados de la consulta PTR y todas las direcciones recibidas se comparan con la dirección remota. Recomendamos encarecidamente que la expresión regular termine con $.
Todos los resultados de las consultas DNS se almacenan en caché hasta que el servidor se reinicie. Ejemplos Para permitir el acceso del usuario desde cualquier red, especifique: 
<ip>::/0</ip>
No es seguro permitir el acceso desde cualquier red, a menos que haya un firewall configurado correctamente o que el servidor no esté conectado directamente a Internet.
Para permitir el acceso solo desde localhost, especifique: 
<ip>::1</ip>
<ip>127.0.0.1</ip>

​
user_name/profile

Puede asignar un perfil de configuración al usuario. Los perfiles de configuración se configuran en una sección independiente del archivo users.xml. Para obtener más información, consulte Perfiles de configuración.

​
user_name/quota

Las cuotas permiten realizar un seguimiento o limitar el uso de recursos durante un período de tiempo. Las cuotas se configuran en la sección quotas del archivo de configuración users.xml. Puede asignar un conjunto de cuotas al usuario. Para obtener una descripción detallada de la configuración de las cuotas, consulte Cuotas.

​
user_name/databases

En esta sección, puede limitar las filas que ClickHouse devuelve para las consultas SELECT realizadas por el usuario actual, implementando así una seguridad básica a nivel de fila. Ejemplo La siguiente configuración hace que el usuario user1 solo pueda ver, como resultado de las consultas SELECT, las filas de table1 en las que el valor del campo id es 1000. 
<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>
El filter puede ser cualquier expresión que produzca un valor de tipo UInt8. Normalmente contiene comparaciones y operadores lógicos. Las filas de database_name.table1 para las que filter da como resultado 0 no se devuelven a este usuario. El filtrado es incompatible con las operaciones PREWHERE y desactiva la optimización WHERE→PREWHERE.

​
Roles

Puede crear cualquiera de los roles predefinidos mediante la sección roles del archivo de configuración user.xml. Estructura de la sección roles: 
<roles>
    <test_role>
        <grants>
            <query>GRANT SHOW ON *.*</query>
            <query>REVOKE SHOW ON system.*</query>
            <query>GRANT CREATE ON *.* WITH GRANT OPTION</query>
        </grants>
    </test_role>
</roles>
Estos roles también se pueden asignar a los usuarios desde la sección users: 
<users>
    <user_name>
        ...
        <grants>
            <query>GRANT test_role</query>
        </grants>
    </user_name>
<users>
Última modificación el 10 de junio de 2026