メインコンテンツへスキップ
users.xml 構成ファイルの users セクションには、ユーザー設定が含まれています。
ClickHouse は、ユーザー管理のための SQL ベースのワークフロー もサポートしています。こちらの使用を推奨します。
users セクションの構造: 
<users>
    <!-- ユーザー名が指定されていない場合、'default' ユーザーが使用されます。 -->
    <user_name>
        <!-- users.user_name レベルでは、認証方式を1つだけ指定できます。例: -->
        <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

パスワードは、平文または 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 '-'
    結果の 1 行目がパスワードで、2 行目が対応する 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 '-'
    結果の 1 行目がパスワードで、2 行目が対応するダブル SHA1 ハッシュです。

​
TOTP 認証の設定

Time-Based One-Time Password (TOTP) は、一定時間だけ有効な一時的なアクセスコードを生成することで、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 は対話形式で入力を求めます。 ユーザーの TOTP 認証を有効にするには、users.xml で time_based_one_time_password セクションを設定します。このセクションでは、secret、有効期間、桁数、hash アルゴリズムなどの 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 鍵 (ssh-keygen で生成したものなど) があるとします。 
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 に置き換えてください。

​
複数の認証方式

1 人のユーザーに対して、<auth_methods> 要素を使って複数の認証方式を設定できます。これにより、ユーザーは一覧にあるいずれか 1 つの方式で認証できます。たとえば、あるユーザーにパスワードと LDAP 認証情報の両方が設定されている場合、そのどちらでログインしても成功します。 <auth_methods> の各子要素は、任意の名前を付けられるラッパー要素で、その中には認証タイプをちょうど 1 つだけ含めます。ラッパー名 (例: <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> には、少なくとも 1 つの認証方法を含める必要があります。
  • <auth_methods> 内の各ラッパー要素には、認証タイプを必ず 1 つだけ含める必要があります (後方互換性のため、複数含められる <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>
この例では、TOTP 検証はパスワードベースの方式 (<password>) に適用される一方、LDAP 方式は外部サーバーに対して独立して認証を行います。

​
access_management

この設定は、そのユーザーに対して SQL による Access Control and Account Management を使用するかどうかを有効または無効にします。 設定可能な値:
  • 0 — 無効。
  • 1 — 有効。
デフォルト値: 0。

​
grants

この設定では、選択したユーザーに任意の権限を付与できます。 リスト内の各要素は、付与先を指定しない 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

クォータを使用すると、一定期間におけるリソース使用量を追跡したり、制限したりできます。クォータは、users.xml 設定ファイルの quotas セクションで設定します。 ユーザーにはクォータセットを割り当てることができます。クォータの設定の詳細については、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 型の値を返す任意の式を指定できます。通常は、比較や論理演算子が含まれます。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日