사용자 및 역할 설정

사용자 및 역할 설정 (Users and roles settings)

users.xml 설정 파일의 users 섹션에는 사용자 설정이 들어 있어요. 여기서는 사용자 인증 방법, 접근 관리, 네트워크 제한, 할당량, 역할 등을 설정하는 방법을 설명해 드릴게요.

출처: 문서

본문

users.xml 설정 파일의 users 섹션에는 사용자 설정이 들어 있어요.

참고: ClickHouse는 사용자 관리용 SQL 기반 워크플로우도 지원해요. 그 방식을 사용하는 것을 권장해요.

users 섹션의 구조:

<users>
    <!-- If user name was not specified, the user from the 'default_session_user' server setting is used ('default' unless configured otherwise). -->
    <user_name>
        <!-- Exactly one authentication method may be specified at the users.user_name level. For example: -->
        <password></password>
        <!-- Or (exclusive) -->
        <password_sha256_hex></password_sha256_hex>
 
        <!-- Or (exclusive) (N.B. multiple SSH keys are allowed for backwards compatibility) -->
        <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>

        <!-- Or (exclusive) for multiple authentication methods: -->
        <auth_methods>
            <method1>
                <password></password>
            </method1>
            <method2>
                <password_sha256_hex></password_sha256_hex>
            </method2>
            <!-- ... -->
            <methodN>
                <!-- ... -->
            </methodN>
        </auth_methods>

        <access_management>0|1</access_management>
        <named_collection_control>0|1</named_collection_control>
        <show_named_collections_secrets>0|1</show_named_collections_secrets>

        <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>
    <!-- Other users settings -->
</users>

user_name/password

비밀번호는 평문 또는 SHA256(hex 형식)으로 지정할 수 있어요.

  • 평문으로 비밀번호를 지정하려면(권장하지 않음) 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 클라이언트와의 호환성을 위해 비밀번호를 이중 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 '-' 결과의 첫 번째 줄이 비밀번호이고, 두 번째 줄이 해당 이중 SHA1 해시예요.

TOTP 인증 구성 (TOTP Authentication Configuration)

TOTP(Time-Based One-Time Password, 시간 기반 일회용 비밀번호)를 사용해 제한된 시간 동안 유효한 임시 접근 코드를 생성하는 방식으로 ClickHouse 사용자를 인증할 수 있어요. 이 TOTP 인증 방식은 RFC 6238 표준을 따르므로 Google Authenticator, 1Password 등 널리 쓰이는 TOTP 앱과 호환돼요. 비밀번호 기반 인증에 더해 users.xml 설정 파일을 통해 설정할 수 있어요. 아직 SQL 기반 접근 제어에서는 지원되지 않아요.

TOTP로 인증하려면 사용자는 기본 비밀번호와 함께 TOTP 앱이 생성한 일회용 비밀번호를 --one-time-password 명령줄 옵션이나 + 문자로 기본 비밀번호에 덧붙여 제공해야 해요. 예를 들어 기본 비밀번호가 some_password이고 생성된 TOTP 코드가 345123이라면, ClickHouse에 연결할 때 --password some_password+345123 또는 --password some_password --one-time-password 345123으로 지정할 수 있어요. 비밀번호를 지정하지 않으면 clickhouse-client가 대화형으로 물어봐요.

RFC 6238 요구대로 각 코드는 최대 한 번만 허용되므로, 사용자는 period당 최대 한 번만 성공적으로 인증할 수 있어요. 모든 요청이나 연결에서 인증하는 클라이언트(예: HTTP 인터페이스를 쓰는 스크립트)에서는 매번 새 코드가 필요하다는 점을 기억해 두세요.

사용자에 대한 TOTP 인증을 활성화하려면 users.xml에 time_based_one_time_password 섹션을 구성해요. 이 섹션은 secret, 유효 기간, 자릿수, 해시 알고리즘 등 TOTP 설정을 정의해요.

예시

<clickhouse>
    <!-- ... -->
    <users>
        <my_user>
            <!-- Primary password-based authentication: -->
            <password>some_password</password>
            <password_sha256_hex>1464acd6765f91fccd3f5bf4f14ebb7ca69f53af91b0a5790c2bba9d8819417b</password_sha256_hex>
            <!-- ... or any other supported authentication method ... -->

            <!-- TOTP authentication configuration -->
            <time_based_one_time_password>
                <secret>JBSWY3DPEHPK3PXP</secret>      <!-- Base32-encoded TOTP secret -->
                <period>30</period>                    <!-- Optional: OTP validity period in seconds -->
                <digits>6</digits>                     <!-- Optional: Number of digits in the OTP -->
                <algorithm>SHA1</algorithm>            <!-- Optional: Hash 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 Secret 생성

ClickHouse에 사용할 TOTP 호환 secret을 생성하려면 터미널에서 다음 명령을 실행해요:

$ base32 -w32 < /dev/urandom | head -1

이 명령은 base32로 인코딩된 secret을 만들어 내며, 이를 users.xml의 secret 필드에 넣을 수 있어요.

특정 사용자에 대해 TOTP를 활성화하려면 기존의 비밀번호 기반 필드(예: password나 password_sha256_hex)에 time_based_one_time_password 섹션을 추가해요.

qrencode 도구를 사용하면 TOTP secret에 대한 QR 코드를 생성할 수 있어요.

$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'

사용자에 대해 TOTP를 구성한 후에는 위에서 설명한 대로 일회용 비밀번호를 인증 과정의 일부로 사용할 수 있어요.

username/ssh-key

이 설정은 SSH 키로 인증할 수 있게 해줘요.

ssh-keygen으로 생성한 것 같은 SSH 키가 주어졌을 때,

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj [email protected]

ssh_key 요소는 다음과 같이 되어야 해요.

<ssh_key>
     <type>ssh-ed25519</type>
     <base64_key>AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj</base64_key>
 </ssh_key>

다른 지원 알고리즘에는 ssh-ed25519를 ssh-rsa 또는 ecdsa-sha2-nistp256로 바꿔 주세요.

다중 인증 방법 (Multiple Authentication Methods)

<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 — 평문 비밀번호
  • password_sha256_hex — SHA256 비밀번호 해시
  • password_scram_sha256_hex — SCRAM-SHA-256 비밀번호 해시
  • password_double_sha1_hex — 이중 SHA1 비밀번호 해시
  • ldap — LDAP 서버 인증
  • kerberos — Kerberos 인증
  • ssl_certificates — SSL 인증서 인증
  • ssh_keys — SSH 키 인증
  • http_authentication — HTTP 인증

규칙 및 제한:

  • <auth_methods>는 사용자 레벨에서 지정된 인증 방법과 함께 사용할 수 없어요. 한 스타일 또는 다른 스타일을 사용해야 하며, 둘 다는 안 돼요.
  • <auth_methods>는 최소한 하나의 인증 방법을 포함해야 해요.
  • <auth_methods> 안의 각 래퍼 요소는 정확히 한 가지 인증 유형을 포함해야 해요(역호환성을 위해 여러 개를 담을 수 있는 <ssh_keys>는 예외).
  • TOTP(<time_based_one_time_password>)는 사용자 레벨(<auth_methods> 바깥)에서 지정되며 목록의 모든 비밀번호 기반 방법에 적용돼요. TOTP를 활성화하려면 최소한 하나의 비밀번호 기반 방법이 필요해요.

예시: 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>

이 예시에서 TOTP 검증은 비밀번호 기반 방법(<password>)에 적용되고, LDAP 방법은 외부 서버에서 독립적으로 인증해요.

access_management

이 설정은 사용자에 대한 SQL 기반 접근 제어 및 계정 관리의 사용을 활성화하거나 비활성화해요.

가능한 값:

  • 0 — 비활성화.
  • 1 — 활성화.

기본값: 0.

named_collection_control

이 설정은 사용자에 대한 명명된 컬렉션(named collections) 관리의 사용을 활성화하거나 비활성화해요. show_named_collections_secrets로 별도 제어되는 SHOW NAMED COLLECTIONS SECRETS를 제외하면 NAMED COLLECTION ADMIN 권한에 해당해요.

named_collection_admin은 이 설정의 동의어로 받아들여져요.

가능한 값:

  • 0 — 비활성화.
  • 1 — 활성화.

기본값: 0.

show_named_collections_secrets

이 설정은 사용자에 대한 SHOW NAMED COLLECTIONS SECRETS 권한을 활성화하거나 비활성화하며, 이를 통해 사용자는 명명된 컬렉션에 저장된 값(예: system.named_collections 테이블)을 볼 수 있어요.

기본적으로 비활성화돼 있어요. 명명된 컬렉션을 관리할 수 있다고 해서 이미 저장된 자격 증명을 다시 읽을 수 있다는 뜻은 아니에요.

이 설정은 named_collection_control과 함께 있을 때만 효과가 있어요. named_collection_control이 비활성화되면 SHOW NAMED COLLECTIONS SECRETS를 포함한 모든 명명된 컬렉션 권한이 어차피 회수되기 때문이에요.

가능한 값:

  • 0 — 비활성화.
  • 1 — 활성화.

기본값: 0.

참고: 사용자는 자신이 가진 권한만 부여할 수 있어요. 따라서 access_management, named_collection_control, show_named_collections_secrets 중 어떤 것이든 비활성화된 사용자는 완전한 권한 집합을 갖지 못하고, 그것을 다른 사람에게 넘겨줄 수도 없어요. 예를 들어 access_management와 named_collection_control만 활성화된 사용자가 GRANT ALL ON *.* TO another_user WITH GRANT OPTION을 실행하면 거부돼요: Not enough privileges. To execute this query, it's necessary to have the grant ALL ON *.* WITH GRANT OPTION. (Missing permissions: SHOW NAMED COLLECTIONS SECRETS ON *). 세 가지 설정을 모두 활성화해야 사용자를 완전한 관리자로 만들 수 있어요.

grants

이 설정은 선택한 사용자에게 어떤 권한이든 부여할 수 있게 해줘요. 리스트의 각 요소는 grantee를 지정하지 않은 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 주소가 피어 주소와 비교돼요.
  • <host_regexp> — 호스트 이름에 대한 정규 표현식. 예: ^example\d\d-\d\d-\d\.host\.ru$ 접근을 확인하기 위해 피어 주소에 대해 DNS PTR 쿼리를 수행한 다음 지정된 정규 표현식을 적용해요. 그런 다음 PTR 쿼리 결과에 대해 또 한 번 DNS 쿼리를 수행하고 받은 모든 주소를 피어 주소와 비교해요. 정규 표현식이 $로 끝나기를 강력히 권장해요.

DNS 요청의 모든 결과는 서버가 재시작될 때까지 캐시돼요.

예시

어떤 네트워크에서든 사용자에게 접근을 열려면 다음을 지정해요:

<ip>::/0</ip>

참고: 방화벽이 제대로 구성되어 있지 않거나 서버가 인터넷에 직접 연결되어 있지 않다면 어떤 네트워크에서든 접근을 여는 것은 안전하지 않아요.

localhost에서만 접근을 열려면 다음을 지정해요:

<ip>::1</ip>
<ip>127.0.0.1</ip>

user_name/profile

사용자에게 설정 프로필을 할당할 수 있어요. 설정 프로필은 users.xml 파일의 별도 섹션에서 구성돼요. 자세한 내용은 설정 프로필을 참고해요.

user_name/quota

할당량(Quotas)을 사용하면 기간에 걸쳐 리소스 사용량을 추적하거나 제한할 수 있어요. 할당량은 users.xml 설정 파일의 quotas 섹션에서 구성돼요.

사용자에게 할당량 세트를 할당할 수 있어요. 할당량 구성에 대한 자세한 내용은 할당량을 참고해요.

user_name/databases

이 섹션에서는 현재 사용자가 수행한 SELECT 쿼리에 대해 ClickHouse가 반환하는 행을 제한하여 기본적인 행 레벨 보안을 구현할 수 있어요.

예시

다음 구성은 사용자 user1이 SELECT 쿼리 결과로 table1의 행 중 id 필드 값이 1000인 행만 볼 수 있게 강제해요.

<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>

filter는 UInt8 타입의 값을 결과로 만드는 어떤 표현식이든 될 수 있어요. 보통 비교와 논리 연산자를 포함해요. filter 결과가 0인 database_name.table1의 행은 이 사용자에게 반환되지 않아요. 이 필터링은 PREWHERE 연산과 호환되지 않으며 WHERE→PREWHERE 최적화를 비활성화해요.

역할 (Roles)

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>

더 알아보기 (Learn more)