> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 사용자 및 역할을 구성하기 위한 설정입니다.

# Users and roles 설정

`users.xml` 설정 파일의 `users` 섹션에는 사용자 설정이 들어 있습니다.

<Note>
  ClickHouse는 사용자 관리를 위한 [SQL 기반 워크플로](/ko/concepts/features/security/access-rights#access-control-usage)도 지원합니다. 이 방식을 사용하는 것을 권장합니다.
</Note>

`users` 섹션의 구조:

```xml theme={null}
<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>
```

<div id="user-namepassword">
  ### user\_name/password
</div>

비밀번호는 평문(plaintext) 또는 SHA256(16진수 포맷)으로 지정할 수 있습니다.

* 평문으로 비밀번호를 지정하려면(**권장되지 않음**) `password` 요소에 입력하십시오.

  예를 들면 `<password>qwerty</password>`입니다. 비밀번호는 비워 둘 수 있습니다.

<a id="password_sha256_hex" />

* SHA256 해시를 사용해 비밀번호를 지정하려면 `password_sha256_hex` 요소에 입력하십시오.

  예를 들면 `<password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>`입니다.

  셸에서 비밀번호를 생성하는 예시는 다음과 같습니다.

  ```bash theme={null}
  PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
  ```

  결과의 첫 번째 줄은 비밀번호이고, 두 번째 줄은 해당 SHA256 해시입니다.

<a id="password_double_sha1_hex" />

* MySQL 클라이언트와의 호환성을 위해 비밀번호를 double SHA1 해시로 지정할 수 있습니다. `password_double_sha1_hex` 요소에 입력하십시오.

  예를 들면 `<password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>`입니다.

  셸에서 비밀번호를 생성하는 예시는 다음과 같습니다.

  ```bash theme={null}
  PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'
  ```

  결과의 첫 번째 줄은 비밀번호이고, 두 번째 줄은 해당 double SHA1 해시입니다.

<div id="totp-authentication-configuration">
  ### TOTP 인증 구성
</div>

시간 기반 일회용 비밀번호(Time-Based One-Time Password, TOTP)는 제한된 시간 동안만 유효한 임시 액세스 코드를 생성해 ClickHouse 사용자를 인증하는 데 사용할 수 있습니다.
이 TOTP 인증 방식은 [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238) 표준을 준수하므로 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 설정을 정의합니다.

**예시**

````xml theme={null}
<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](https://linux.die.net/man/1/qrencode) 도구를 사용할 수 있습니다.

```bash theme={null}
$ qrencode -t ansiutf8 'otpauth://totp/ClickHouse?issuer=ClickHouse&secret=JBSWY3DPEHPK3PXP'
```

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

### username/ssh-key

이 설정을 사용하면 SSH 키로 인증할 수 있습니다.

`ssh-keygen`으로 생성한 다음과 같은 SSH 키가 있다고 가정합니다.

```text theme={null}
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNf0r6vRl24Ix3tv2IgPmNPO2ATa2krvt80DdcTatLj john@example.com
```

`ssh_key` 요소는 다음과 같은 형식이어야 합니다

```xml theme={null}
<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>`)은 중요하지 않으며, 내부의 인증 요소만 사용됩니다.

**예시: 여러 비밀번호**

```xml theme={null}
<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>
```

**예시: 혼합 인증 방식**

```xml theme={null}
<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`**

```xml theme={null}
<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 기반 [액세스 제어 및 계정 관리](/ko/concepts/features/security/access-rights#access-control-usage) 사용을 활성화하거나 비활성화합니다.

가능한 값:

* 0 — 비활성화됨.
* 1 — 활성화됨.

기본값: 0.

### 권한 부여

이 설정을 사용하면 선택한 사용자에게 모든 권한을 부여할 수 있습니다.
목록의 각 항목은 권한 수여 대상이 지정되지 않은 `GRANT` 쿼리여야 합니다.

예시:

```xml theme={null}
<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 쿼리](https://en.wikipedia.org/wiki/Reverse_DNS_lookup)를 수행한 다음 지정된 정규식을 적용합니다. 그다음 PTR 쿼리 결과에 대해 다시 DNS 쿼리를 수행하고, 반환된 모든 주소를 peer 주소와 비교합니다. 정규식은 \$로 끝나게 지정하는 것을 강력히 권장합니다.

모든 DNS 요청 결과는 서버가 다시 시작될 때까지 캐시됩니다.

**예시**

임의의 네트워크에서 사용자의 액세스를 허용하려면 다음을 지정하십시오.

```xml theme={null}
<ip>::/0</ip>
```

<Note>
  방화벽이 올바르게 구성되어 있지 않고 서버가 인터넷에 직접 연결되어 있다면, 모든 네트워크에서의 접근을 허용하는 것은 안전하지 않습니다.
</Note>

localhost에서만 접근을 허용하려면 다음을 지정하십시오:

```xml theme={null}
<ip>::1</ip>
<ip>127.0.0.1</ip>
```

### user\_name/profile

사용자에게 설정 프로필을 할당할 수 있습니다. 설정 프로필은 `users.xml` 파일의 별도 섹션에서 설정합니다. 자세한 내용은 [설정 프로필](/ko/concepts/features/configuration/settings/settings-profiles)을 참조하십시오.

### user\_name/quota

쿼터는 일정 기간 동안 리소스 사용량을 추적하거나 제한할 수 있습니다. 쿼터는 `users.xml` 설정 파일의 `quotas`
섹션에서 구성합니다.

사용자에게 하나의 쿼터 집합을 할당할 수 있습니다. 쿼터 구성에 대한 자세한 내용은 [쿼터](/ko/concepts/features/configuration/server-config/quotas)를 참조하십시오.

### user\_name/databases

이 섹션에서는 현재 사용자가 실행한 `SELECT` 쿼리에 대해 ClickHouse가 반환하는 행을 제한하여 기본적인 행 수준 보안을 구현할 수 있습니다.

**예시**

다음 구성은 사용자 `user1`이 `SELECT` 쿼리 결과에서 `id` 필드 값이 1000인 `table1`의 행만 볼 수 있도록 강제합니다.

```xml theme={null}
<user1>
    <databases>
        <database_name>
            <table1>
                <filter>id = 1000</filter>
            </table1>
        </database_name>
    </databases>
</user1>
```

`filter`는 [UInt8](/ko/reference/data-types/int-uint) 타입의 값을 반환하는 어떤 표현식이든 될 수 있습니다. 일반적으로 비교 및 논리 연산자를 포함합니다. `database_name.table1`에서 `filter`의 결과가 0인 행은 이 사용자에게 반환되지 않습니다. 이 필터링은 `PREWHERE` 작업과 호환되지 않으며 `WHERE→PREWHERE` 최적화를 비활성화합니다.

## 역할

사전에 정의된 모든 역할은 `user.xml` 설정 파일의 `roles` 섹션에서 생성할 수 있습니다.

`roles` 섹션의 구조:

```xml theme={null}
<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` 섹션에서도 사용자에게 부여할 수 있습니다:

```xml theme={null}
<users>
    <user_name>
        ...
        <grants>
            <query>GRANT test_role</query>
        </grants>
    </user_name>
<users>
```