Перейти к основному содержанию
Эта страница не применима к ClickHouse Cloud. Описанная здесь возможность недоступна в сервисах ClickHouse Cloud. Дополнительные сведения см. в руководстве ClickHouse Cloud Compatibility.
В этом руководстве приведены простые минимальные настройки для аутентификации с помощью пользовательских SSL-сертификатов. Оно основано на руководстве «Настройка TLS».
Аутентификация пользователей по SSL поддерживается при использовании интерфейсов https, native, mysql и postgresql.Для безопасной аутентификации на узлах ClickHouse должен быть задан параметр <verificationMode>strict</verificationMode> (хотя для тестирования подойдет и relaxed).Если вы используете AWS NLB с интерфейсом MySQL, обратитесь в поддержку AWS, чтобы включить следующую недокументированную опцию:
Я хочу иметь возможность настроить proxy protocol v2 для NLB следующим образом: proxy_protocol_v2.client_to_server.header_placement,Value=on_first_ack.

​
1. Создайте SSL-сертификаты пользователя

В этом примере используются самоподписанные сертификаты с самоподписанным CA. Для рабочей среды создайте CSR и отправьте его вашей команде PKI или поставщику сертификатов, чтобы получить корректный сертификат.
  1. Сгенерируйте запрос на подпись сертификата (CSR) и ключ. Базовый формат выглядит следующим образом: 
    openssl req -newkey rsa:2048 -nodes -subj "/CN=<my_host>:<my_user>"  -keyout <my_cert_name>.key -out <my_cert_name>.csr
    В этом примере мы используем следующие домен и пользователя для этой тестовой среды: 
    openssl req -newkey rsa:2048 -nodes -subj "/CN=chnode1.marsnet.local:cert_user"  -keyout chnode1_cert_user.key -out chnode1_cert_user.csr
Значение CN произвольно, и в качестве идентификатора сертификата можно использовать любую строку. Оно используется при создании пользователя на следующих шагах.
  1. Сгенерируйте и подпишите новый сертификат пользователя, который будет использоваться для аутентификации. Базовый формат выглядит следующим образом: 
    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
    В этом примере мы используем следующие домен и пользователя для этой тестовой среды: 
    openssl x509 -req -in chnode1_cert_user.csr -out chnode1_cert_user.crt -CA marsnet_ca.crt -CAkey marsnet_ca.key -days 365

​
2. Создайте SQL-пользователя и предоставьте права

Подробные сведения о том, как включить SQL-пользователей и назначать роли, см. в руководстве Определение SQL-пользователей и ролей.
  1. Создайте SQL-пользователя с аутентификацией по сертификату: 
    CREATE USER cert_user IDENTIFIED WITH ssl_certificate CN 'chnode1.marsnet.local:cert_user';
  2. Предоставьте привилегии новому пользователю с сертификатом: 
    GRANT ALL ON *.* TO cert_user WITH GRANT OPTION;
В этом примере пользователю предоставлены полные административные привилегии в демонстрационных целях. Сведения о настройке прав см. в документации ClickHouse по RBAC.
Мы рекомендуем использовать SQL для определения пользователей и ролей. Однако если сейчас вы определяете пользователей и роли в конфигурационных файлах, пользователь будет выглядеть так:
<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>
        {/* дополнительные параметры*/}
    </cert_user>
</users>

​
3. Проверка

  1. Скопируйте сертификат пользователя, ключ пользователя и CA‑сертификат на удалённый узел.
  2. Настройте OpenSSL в конфигурации клиента ClickHouse, указав сертификат и пути к файлам. 
    <openSSL>
    <client>
        <certificateFile>my_cert_name.crt</certificateFile>
        <privateKeyFile>my_cert_name.key</privateKeyFile>
        <caConfig>my_ca_cert.crt</caConfig>
    </client>
</openSSL>
  3. Запустите clickhouse-client. 
    clickhouse-client --user <my_user> --query 'SHOW TABLES'
Обратите внимание: пароль, переданный в clickhouse-client, игнорируется, если в конфигурации указан сертификат.

​
4. Тестирование HTTP

  1. Скопируйте сертификат пользователя, его ключ и CA‑сертификат на удалённый узел.
  2. С помощью curl протестируйте пример SQL-команды. Базовый формат: 
    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 @-
    Например: 
    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 @-
    Вывод будет примерно таким: 
    INFORMATION_SCHEMA
default
information_schema
system
Обратите внимание: пароль не указывается, так как вместо него используется сертификат — именно по нему ClickHouse аутентифицирует пользователя.

​
Итоги

В этой статье были рассмотрены основы создания и настройки пользователя для аутентификации по SSL-сертификату. Этот метод можно использовать с clickhouse-client или любыми клиентами, которые поддерживают интерфейс https и позволяют задавать HTTP-заголовки. Сгенерированные сертификат и ключ следует хранить в тайне и ограничить к ним доступ, поскольку сертификат используется для аутентификации и авторизации пользователя при выполнении операций в базе данных ClickHouse. Обращайтесь с сертификатом и ключом так же, как с паролями.
Последнее изменение 10 июня 2026 г.