Pular para o conteúdo principal
A seção users do arquivo de configuração users.xml contém as configurações dos usuários.
O ClickHouse também oferece suporte ao fluxo de trabalho orientado por SQL para gerenciar usuários. Recomendamos usá-lo.
Estrutura da seção users: 
<users>
    <!-- Se o nome de usuário não for especificado, o usuário 'default' será utilizado. -->
    <user_name>
        <!-- Exatamente um método de autenticação pode ser especificado no nível users.user_name. Por exemplo: -->
        <password></password>
        <!-- Ou (exclusivo) -->
        <password_sha256_hex></password_sha256_hex>
 
        <!-- Ou (exclusivo) (N.B. múltiplas chaves SSH são permitidas para compatibilidade com versões 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>

        <!-- Ou (exclusivo) para múltiplos métodos de autenticação: -->
        <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>
    <!-- Configurações dos demais usuários -->
</users>

​
user_name/password

A senha pode ser especificada em texto simples ou em SHA256 (formato hexadecimal).
  • Para definir uma senha em texto simples (não recomendado), coloque-a em um elemento password. Por exemplo, <password>qwerty</password>. A senha pode ser deixada em branco.
  • Para definir uma senha usando seu hash SHA256, coloque-a em um elemento password_sha256_hex. Por exemplo, <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>. Exemplo de como gerar uma senha no shell: 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
    A primeira linha do resultado é a senha. A segunda linha é o hash SHA256 correspondente.
  • Para compatibilidade com clientes MySQL, a senha pode ser especificada como um hash double SHA1. Coloque-a em um elemento password_double_sha1_hex. Por exemplo, <password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>. Exemplo de como gerar uma senha no shell: 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
    A primeira linha do resultado é a senha. A segunda linha é o hash double SHA1 correspondente.

​
Configuração da autenticação TOTP

A senha de uso único baseada em tempo (TOTP) pode ser usada para autenticar usuários do ClickHouse, gerando códigos de acesso temporários válidos por um período limitado. Esse método de autenticação TOTP está em conformidade com os padrões da RFC 6238, o que o torna compatível com aplicativos TOTP populares, como Google Authenticator, 1Password e ferramentas semelhantes. Ele pode ser configurado por meio do arquivo de configuração users.xml, além da autenticação baseada em senha. Esse recurso ainda não tem suporte no controle de acesso orientado por SQL. Para autenticar usando TOTP, os usuários devem fornecer uma senha primária junto com uma senha de uso único gerada pelo aplicativo TOTP, por meio da opção de linha de comando --one-time-password ou concatenada à senha principal com o caractere ’+’. Por exemplo, se a senha primária for some_password e o código TOTP gerado for 345123, o usuário pode especificar --password some_password+345123 ou --password some_password --one-time-password 345123 ao se conectar ao ClickHouse. Se nenhuma senha for especificada, o clickhouse-client solicitará a senha interativamente. Para habilitar a autenticação TOTP para um usuário, configure a seção time_based_one_time_password em users.xml. Essa seção define as configurações de TOTP, como Secret, período de validade, número de dígitos e algoritmo de hash. Exemplo 
<clickhouse>
    <!-- ... -->
    <users>
        <my_user>
            <!-- Autenticação primária baseada em senha: -->
            <password>some_password</password>
            <password_sha256_hex>1464acd6765f91fccd3f5bf4f14ebb7ca69f53af91b0a5790c2bba9d8819417b</password_sha256_hex>
            <!-- ... ou qualquer outro método de autenticação suportado ... -->

            <!-- Configuração de autenticação TOTP -->
            <time_based_one_time_password>
                <secret>JBSWY3DPEHPK3PXP</secret>      <!-- Segredo TOTP codificado em Base32 -->
                <period>30</period>                    <!-- Opcional: período de validade do OTP em segundos -->
                <digits>6</digits>                     <!-- Opcional: número de dígitos no OTP -->
                <algorithm>SHA1</algorithm>            <!-- Opcional: algoritmo de hash: SHA1, SHA256, SHA512 -->
            </time_based_one_time_password>
        </my_user>
    </users>
</clickhouse>

Parâmetros:

- secret - (Obrigatório) A chave secreta codificada em base32 utilizada para gerar códigos TOTP.
- period - Opcional. Define o período de validade de cada OTP em segundos. Deve ser um número positivo não superior a 120. O valor padrão é 30.
- digits - Opcional. Especifica o número de dígitos em cada OTP. Deve estar entre 4 e 10. O valor padrão é 6.
- algorithm - Opcional. Define o algoritmo de hash para geração de OTPs. Os valores suportados são SHA1, SHA256 e SHA512. O valor padrão é SHA1.

Gerando um Secret TOTP

Para gerar um secret compatível com TOTP para uso com o ClickHouse, execute o seguinte comando no terminal:

```bash
$ base32 -w32 < /dev/urandom | head -1
Este comando produzirá um segredo codificado em base32 que pode ser adicionado ao campo secret em users.xml. Para habilitar o TOTP para um usuário específico, adicione a qualquer campo existente baseado em senha (como password ou password_sha256_hex) outra seção time_based_one_time_password. A ferramenta qrencode pode ser usada para gerar um código QR para o segredo do TOTP. 
$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'
Após configurar o TOTP para um usuário, uma senha de uso único pode ser utilizada como parte do processo de autenticação, conforme descrito acima.

​
username/ssh-key

Essa configuração permite a autenticação com chaves SSH. Dada uma chave SSH (como a gerada pelo ssh-keygen), como 
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj john@example.com
Espera-se que o elemento ssh_key seja 
<ssh_key>
     <type>ssh-ed25519</type>
     <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
 </ssh_key>
Substitua ssh-ed25519 por ssh-rsa ou ecdsa-sha2-nistp256 no caso dos outros algoritmos compatíveis.

​
Múltiplos métodos de autenticação

Um único usuário pode ser configurado com vários métodos de autenticação usando o elemento <auth_methods>. Isso permite que o usuário se autentique com qualquer um dos métodos listados — por exemplo, ele pode ter tanto uma senha quanto uma credencial LDAP, e o login com qualquer uma delas será bem-sucedido. Cada elemento filho de <auth_methods> é um contêiner com nome arbitrário que contém exatamente um tipo de autenticação. O nome desse contêiner (por exemplo, <method1>, <primary>, <a1>) não importa; apenas o elemento interno de autenticação é considerado. Exemplo: várias senhas 
<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>
Exemplo: tipos de autenticação mistos 
<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>
Os seguintes tipos de autenticação são suportados em <auth_methods>:
  • password — senha em texto simples
  • password_sha256_hex — hash de senha SHA256
  • password_scram_sha256_hex — hash de senha SCRAM-SHA-256
  • password_double_sha1_hex — hash de senha double SHA1
  • ldap — autenticação de servidor LDAP
  • kerberos — autenticação Kerberos
  • ssl_certificates — autenticação por certificado SSL
  • ssh_keys — autenticação por chave SSH
  • http_authentication — autenticação HTTP
Regras e restrições:
  • <auth_methods> não pode ser usado junto com métodos de autenticação especificados no nível do usuário. Use um estilo ou outro, não os dois.
  • <auth_methods> deve conter pelo menos um método de autenticação.
  • Cada elemento wrapper em <auth_methods> deve conter exatamente um tipo de autenticação (com exceção de <ssh_keys>, que pode conter vários, para compatibilidade com versões anteriores).
  • TOTP (<time_based_one_time_password>) é especificado no nível do usuário (fora de <auth_methods>) e se aplica a todos os métodos baseados em senha da lista. Pelo menos um método baseado em senha é necessário quando o TOTP está habilitado.
Exemplo: auth_methods com 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>
Neste exemplo, a verificação TOTP é aplicada ao método baseado em senha (<password>), enquanto o método LDAP faz a autenticação no servidor externo de forma independente.

​
access_management

Esta configuração habilita ou desabilita o uso do controle de acesso e gerenciamento de contas baseado em SQL para o usuário. Valores possíveis:
  • 0 — Desabilitado.
  • 1 — Habilitado.
Valor padrão: 0.

​
grants

Esta configuração permite conceder quaisquer privilégios ao usuário selecionado. Cada elemento da lista deve ser uma consulta GRANT sem especificar nenhum beneficiário. Exemplo: 
<user1>
    <grants>
        <query>GRANT SHOW ON *.*</query>
        <query>GRANT CREATE ON *.* WITH GRANT OPTION</query>
        <query>GRANT SELECT ON system.*</query>
    </grants>
</user1>
Essa configuração não pode ser especificada ao mesmo tempo que as configurações dictionaries, access_management, named_collection_control, show_named_collections_secrets e allow_databases.

​
user_name/networks

Lista de redes a partir das quais o usuário pode se conectar ao servidor do ClickHouse. Cada elemento da lista pode ter uma das seguintes formas:
  • <ip> — Endereço IP ou máscara de rede. Exemplos: 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> — Nome do host. Exemplo: example01.host.ru. Para verificar o acesso, é feita uma consulta DNS, e todos os endereços IP retornados são comparados com o endereço remoto.
  • <host_regexp> — Expressão regular para nomes de host. Exemplo: ^example\d\d-\d\d-\d\.host\.ru$ Para verificar o acesso, é feita uma consulta DNS PTR para o endereço remoto e, em seguida, a regexp especificada é aplicada. Depois, é feita outra consulta DNS para os resultados da consulta PTR, e todos os endereços recebidos são comparados com o endereço remoto. Recomendamos fortemente que a regexp termine com $.
Todos os resultados das consultas DNS são armazenados em cache até que o servidor seja reiniciado. Exemplos Para liberar o acesso do usuário a partir de qualquer rede, especifique: 
<ip>::/0</ip>
Não é seguro abrir o acesso a partir de qualquer rede, a menos que você tenha um firewall configurado corretamente ou que o servidor não esteja conectado diretamente à Internet.
Para abrir o acesso apenas a partir de localhost, especifique: 
<ip>::1</ip>
<ip>127.0.0.1</ip>

​
user_name/profile

Você pode atribuir um perfil de configurações ao usuário. Os perfis de configurações são definidos em uma seção separada do arquivo users.xml. Para mais informações, consulte Perfis de configurações.

​
user_name/quota

As quotas permitem acompanhar ou limitar o uso de recursos ao longo de um período. As quotas são configuradas na seção quotas do arquivo de configuração users.xml. Você pode atribuir um conjunto de quotas ao usuário. Para uma descrição detalhada da configuração de quotas, consulte Quotas.

​
user_name/databases

Nesta seção, você pode limitar as linhas retornadas pelo ClickHouse em consultas SELECT feitas pelo usuário atual, implementando assim segurança básica em nível de linha. Exemplo A configuração a seguir faz com que o usuário user1 só possa ver as linhas de table1 retornadas por consultas SELECT nas quais o valor do campo id é 1000. 
<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>
O filter pode ser qualquer expressão que resulte em um valor do tipo UInt8. Em geral, ele contém comparações e operadores lógicos. As linhas de database_name.table1 para as quais o filter resulta em 0 não são retornadas para este usuário. A filtragem é incompatível com operações PREWHERE e desativa a otimização WHERE→PREWHERE.

​
Funções

Você pode criar qualquer uma das funções predefinidas usando a seção roles do arquivo de configuração user.xml. Estrutura da seção 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>
Essas funções também podem ser concedidas aos usuários na seção users: 
<users>
    <user_name>
        ...
        <grants>
            <query>GRANT test_role</query>
        </grants>
    </user_name>
<users>
Última modificação em 10 de junho de 2026