메인 콘텐츠로 건너뛰기
users.xml 설정 파일의 users 섹션에는 사용자 설정이 들어 있습니다.
ClickHouse는 사용자 관리를 위한 SQL 기반 워크플로도 지원합니다. 이 방식을 사용하는 것을 권장합니다.
users 섹션의 구조: 
<users>
    <!-- 사용자 이름이 지정되지 않은 경우 'default' 사용자가 사용됩니다. -->
    <user_name>
        <!-- users.user_name 수준에서는 정확히 하나의 인증 방법만 지정할 수 있습니다. 예시: -->
        <password></password>
        <!-- 또는 (단독 사용) -->
        <password_sha256_hex></password_sha256_hex>
 
        <!-- 또는 (단독 사용) (참고: 하위 호환성을 위해 여러 SSH 키를 허용합니다) -->
        <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>

        <!-- 또는 (단독 사용) 여러 인증 방법을 사용하는 경우: -->
        <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>
    <!-- 다른 사용자 설정 -->
</users>

​
user_name/password

비밀번호는 평문(plaintext) 또는 SHA256(16진수 포맷)으로 지정할 수 있습니다.
  • 평문으로 비밀번호를 지정하려면(권장되지 않음) password 요소에 입력하십시오. 예를 들면 <password>qwerty</password>입니다. 비밀번호는 비워 둘 수 있습니다.
  • SHA256 해시를 사용해 비밀번호를 지정하려면 password_sha256_hex 요소에 입력하십시오. 예를 들면 <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>입니다. 셸에서 비밀번호를 생성하는 예시는 다음과 같습니다. 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
    결과의 첫 번째 줄은 비밀번호이고, 두 번째 줄은 해당 SHA256 해시입니다.
  • MySQL 클라이언트와의 호환성을 위해 비밀번호를 double SHA1 해시로 지정할 수 있습니다. password_double_sha1_hex 요소에 입력하십시오. 예를 들면 <password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>입니다. 셸에서 비밀번호를 생성하는 예시는 다음과 같습니다. 
    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
    결과의 첫 번째 줄은 비밀번호이고, 두 번째 줄은 해당 double SHA1 해시입니다.

​
TOTP 인증 구성

시간 기반 일회용 비밀번호(Time-Based One-Time Password, TOTP)는 제한된 시간 동안만 유효한 임시 액세스 코드를 생성해 ClickHouse 사용자를 인증하는 데 사용할 수 있습니다. 이 TOTP 인증 방식은 RFC 6238 표준을 준수하므로 Google Authenticator, 1Password 같은 널리 사용되는 TOTP 애플리케이션과 호환됩니다. 비밀번호 기반 인증과 함께 users.xml 설정 파일을 통해 구성할 수 있습니다. 아직 SQL 기반 Access Control에서는 지원되지 않습니다. TOTP로 인증하려면 기본 비밀번호와 함께 TOTP 애플리케이션이 생성한 일회용 비밀번호를 --one-time-password 명령줄 옵션으로 제공하거나, + 문자를 사용해 기본 비밀번호 뒤에 붙여 제공해야 합니다. 예를 들어 기본 비밀번호가 some_password이고 생성된 TOTP 코드가 345123인 경우, ClickHouse에 연결할 때 --password some_password+345123 또는 --password some_password --one-time-password 345123를 지정할 수 있습니다. 비밀번호를 지정하지 않으면 clickhouse-client가 대화형으로 입력을 요청합니다. 사용자에 대해 TOTP 인증을 활성화하려면 users.xml에서 time_based_one_time_password 섹션을 구성하십시오. 이 섹션에서는 시크릿, 유효 기간, 자릿수, 해시 알고리즘 등 TOTP 설정을 정의합니다. 예시 
<clickhouse>
    <!-- ... -->
    <users>
        <my_user>
            <!-- 기본 비밀번호 기반 인증: -->
            <password>some_password</password>
            <password_sha256_hex>1464acd6765f91fccd3f5bf4f14ebb7ca69f53af91b0a5790c2bba9d8819417b</password_sha256_hex>
            <!-- ... 또는 지원되는 다른 인증 방법 ... -->

            <!-- TOTP 인증 구성 -->
            <time_based_one_time_password>
                <secret>JBSWY3DPEHPK3PXP</secret>      <!-- Base32 인코딩 TOTP 시크릿 -->
                <period>30</period>                    <!-- 선택 사항: OTP 유효 기간(초) -->
                <digits>6</digits>                     <!-- 선택 사항: OTP 자릿수 -->
                <algorithm>SHA1</algorithm>            <!-- 선택 사항: 해시 알고리즘: SHA1, SHA256, SHA512 -->
            </time_based_one_time_password>
        </my_user>
    </users>
</clickhouse>

매개변수:

- secret - (필수) TOTP 코드 생성에 사용되는 Base32 인코딩 시크릿 키입니다.
- period - 선택 사항. 각 OTP의 유효 기간을 초 단위로 설정합니다. 120 이하의 양수여야 합니다. 기본값은 30입니다.
- digits - 선택 사항. 각 OTP의 자릿수를 지정합니다. 4 이상 10 이하여야 합니다. 기본값은 6입니다.
- algorithm - 선택 사항. OTP 생성에 사용할 해시 알고리즘을 지정합니다. 지원되는 값은 SHA1, SHA256, SHA512입니다. 기본값은 SHA1입니다.

TOTP 시크릿 생성

ClickHouse에서 사용할 TOTP 호환 시크릿을 생성하려면 터미널에서 다음 명령을 실행하십시오:

```bash
$ base32 -w32 < /dev/urandom | head -1
이 명령을 실행하면 users.xml의 secret 필드에 추가할 수 있는 base32 인코딩 시크릿이 생성됩니다. 특정 사용자의 TOTP를 활성화하려면 기존 비밀번호 기반 필드(password 또는 password_sha256_hex 등)에 time_based_one_time_password 섹션을 하나 더 추가하십시오. TOTP 시크릿용 QR 코드를 생성하는 데 qrencode 도구를 사용할 수 있습니다. 
$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'
사용자에 대해 TOTP를 구성한 후에는 위에서 설명한 대로 인증 과정의 일부로 일회용 비밀번호를 사용할 수 있습니다.

​
username/ssh-key

이 설정을 사용하면 SSH 키로 인증할 수 있습니다. ssh-keygen으로 생성한 다음과 같은 SSH 키가 있다고 가정합니다. 
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj john@example.com
ssh_key 요소는 다음과 같은 형식이어야 합니다 
<ssh_key>
     <type>ssh-ed25519</type>
     <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
 </ssh_key>
다른 지원 알고리즘을 사용하는 경우 ssh-ed25519 대신 ssh-rsa 또는 ecdsa-sha2-nistp256을 사용하십시오.

​
여러 인증 방법

<auth_methods> 요소를 사용하면 하나의 사용자에 여러 인증 방법을 구성할 수 있습니다. 이렇게 하면 나열된 방법 중 하나로 인증할 수 있습니다. 예를 들어, 한 사용자에 비밀번호와 LDAP 자격 증명을 모두 설정할 수 있으며, 둘 중 어느 쪽으로 로그인해도 성공합니다. <auth_methods>의 각 하위 요소는 정확히 하나의 인증 유형을 포함하는 임의 이름의 래퍼입니다. 래퍼 이름(예: <method1>, <primary>, <a1>)은 중요하지 않으며, 내부의 인증 요소만 사용됩니다. 예시: 여러 비밀번호 
<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>
예시: 혼합 인증 방식 
<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>
다음 인증 유형을 <auth_methods> 내에서 지원합니다:
  • password — plaintext 비밀번호
  • password_sha256_hex — SHA256 비밀번호 해시
  • password_scram_sha256_hex — SCRAM-SHA-256 비밀번호 해시
  • password_double_sha1_hex — double SHA1 비밀번호 해시
  • ldap — LDAP 서버 인증
  • kerberos — Kerberos 인증
  • ssl_certificates — SSL 인증서 인증
  • ssh_keys — SSH 키 인증
  • http_authentication — HTTP 인증
규칙 및 제한 사항:
  • <auth_methods>는 사용자 수준에서 지정한 인증 방식과 함께 사용할 수 없습니다. 둘 중 한 가지 방식만 사용하십시오.
  • <auth_methods>에는 최소 1개의 인증 방식이 포함되어야 합니다.
  • <auth_methods> 내의 각 래퍼 요소에는 정확히 하나의 인증 유형만 포함되어야 합니다(하위 호환성을 위해 여러 개를 포함할 수 있는 <ssh_keys>는 예외).
  • TOTP (<time_based_one_time_password>)는 사용자 수준(<auth_methods> 외부)에서 지정되며, 목록의 모든 비밀번호 기반 메서드에 적용됩니다. TOTP가 활성화된 경우 비밀번호 기반 메서드가 최소 1개 필요합니다.
예시: TOTP를 사용하는 auth_methods 
<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>
이 예시에서는 비밀번호 기반 메서드(<password>)에 TOTP 검증이 적용되고, LDAP 메서드는 외부 서버에 대해 별도로 인증합니다.

​
access_management

이 설정은 사용자에 대해 SQL 기반 액세스 제어 및 계정 관리 사용을 활성화하거나 비활성화합니다. 가능한 값:
  • 0 — 비활성화됨.
  • 1 — 활성화됨.
기본값: 0.

​
권한 부여

이 설정을 사용하면 선택한 사용자에게 모든 권한을 부여할 수 있습니다. 목록의 각 항목은 권한 수여 대상이 지정되지 않은 GRANT 쿼리여야 합니다. 예시: 
<user1>
    <grants>
        <query>GRANT SHOW ON *.*</query>
        <query>GRANT CREATE ON *.* WITH GRANT OPTION</query>
        <query>GRANT SELECT ON system.*</query>
    </grants>
</user1>
이 설정은 dictionaries, access_management, named_collection_control, show_named_collections_secrets 및 allow_databases 설정과 함께 동시에 지정할 수 없습니다.

​
user_name/networks

사용자가 ClickHouse 서버에 연결할 수 있는 네트워크 목록입니다. 목록의 각 항목은 다음 형식 중 하나를 사용할 수 있습니다.
  • <ip> — IP 주소 또는 네트워크 마스크입니다. 예시: 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> — 호스트명입니다. 예시: example01.host.ru. 액세스를 확인할 때는 DNS 쿼리를 수행한 뒤, 반환된 모든 IP 주소를 peer 주소와 비교합니다.
  • <host_regexp> — 호스트명에 대한 정규식입니다. 예시: ^example\d\d-\d\d-\d\.host\.ru$ 액세스를 확인할 때는 먼저 peer 주소에 대해 DNS PTR 쿼리를 수행한 다음 지정된 정규식을 적용합니다. 그다음 PTR 쿼리 결과에 대해 다시 DNS 쿼리를 수행하고, 반환된 모든 주소를 peer 주소와 비교합니다. 정규식은 $로 끝나게 지정하는 것을 강력히 권장합니다.
모든 DNS 요청 결과는 서버가 다시 시작될 때까지 캐시됩니다. 예시 임의의 네트워크에서 사용자의 액세스를 허용하려면 다음을 지정하십시오. 
<ip>::/0</ip>
방화벽이 올바르게 구성되어 있지 않고 서버가 인터넷에 직접 연결되어 있다면, 모든 네트워크에서의 접근을 허용하는 것은 안전하지 않습니다.
localhost에서만 접근을 허용하려면 다음을 지정하십시오: 
<ip>::1</ip>
<ip>127.0.0.1</ip>

​
user_name/profile

사용자에게 설정 프로필을 할당할 수 있습니다. 설정 프로필은 users.xml 파일의 별도 섹션에서 설정합니다. 자세한 내용은 설정 프로필을 참조하십시오.

​
user_name/quota

쿼터는 일정 기간 동안 리소스 사용량을 추적하거나 제한할 수 있습니다. 쿼터는 users.xml 설정 파일의 quotas 섹션에서 구성합니다. 사용자에게 하나의 쿼터 집합을 할당할 수 있습니다. 쿼터 구성에 대한 자세한 내용은 쿼터를 참조하십시오.

​
user_name/databases

이 섹션에서는 현재 사용자가 실행한 SELECT 쿼리에 대해 ClickHouse가 반환하는 행을 제한하여 기본적인 행 수준 보안을 구현할 수 있습니다. 예시 다음 구성은 사용자 user1이 SELECT 쿼리 결과에서 id 필드 값이 1000인 table1의 행만 볼 수 있도록 강제합니다. 
<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>
filter는 UInt8 타입의 값을 반환하는 어떤 표현식이든 될 수 있습니다. 일반적으로 비교 및 논리 연산자를 포함합니다. database_name.table1에서 filter의 결과가 0인 행은 이 사용자에게 반환되지 않습니다. 이 필터링은 PREWHERE 작업과 호환되지 않으며 WHERE→PREWHERE 최적화를 비활성화합니다.

​
역할

사전에 정의된 모든 역할은 user.xml 설정 파일의 roles 섹션에서 생성할 수 있습니다. 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>
이러한 역할은 users 섹션에서도 사용자에게 부여할 수 있습니다: 
<users>
    <user_name>
        ...
        <grants>
            <query>GRANT test_role</query>
        </grants>
    </user_name>
<users>
마지막 수정일 2026년 6월 10일