ClickHouse でのユーザーとロールの作成

ClickHouse は、RBAC に基づくアクセス制御をサポートしています。

ClickHouse のアクセスエンティティ:

• User account
• Role
• Row Policy
• Settings Profile
• Quota

アクセスエンティティは次の方法で設定できます:

• SQL 駆動のワークフロー。

  この機能を利用するには、事前に有効化する必要があります。

• サーバーの設定ファイル users.xml および config.xml。

SQL 駆動のワークフローを使用することを推奨します。どちらの設定方法も同時に動作するため、アカウントやアクセス権限の管理にサーバー設定ファイルを使用している場合でも、SQL 駆動のワークフローへスムーズに移行できます。

注記

同じアクセスエンティティを 2 つの設定方法で同時に管理することはできません。

注記

ClickHouse Cloud コンソールユーザーの管理方法を探している場合は、このページを参照してください。

すべてのユーザー、ロール、プロファイルなどと、それらに対するすべての権限付与を確認するには、SHOW ACCESS ステートメントを使用します。

概要

デフォルトでは、ClickHouse サーバーは default ユーザーアカウントを提供します。このアカウントは SQL ベースのアクセス制御およびアカウント管理には利用できませんが、すべての権限を持っています。default ユーザーアカウントは、たとえばクライアントからのログイン時や分散クエリ内など、ユーザー名が定義されていないすべての場合に使用されます。分散クエリ処理においては、サーバーまたはクラスタの設定で user と password プロパティが指定されていない場合、default ユーザーアカウントが使用されます。

ClickHouse の利用を開始したばかりの場合は、次のシナリオを検討してください。

1. default ユーザーに対して、SQL ベースのアクセス制御とアカウント管理を有効化 します。
2. default ユーザーアカウントにログインし、必要なすべてのユーザーを作成します。管理者アカウント（GRANT ALL ON *.* TO admin_user_account WITH GRANT OPTION）の作成を忘れないでください。
3. default ユーザーの権限を制限し、そのユーザーに対する SQL ベースのアクセス制御とアカウント管理を無効化します。

現在の仕組みの特性

• 存在しないデータベースやテーブルに対しても権限を付与できます。
• テーブルが削除されても、そのテーブルに対応するすべての権限は取り消されません。つまり、後で同じ名前の新しいテーブルを作成した場合でも、すべての権限は有効なままです。削除されたテーブルに対応する権限を取り消すには、REVOKE ALL PRIVILEGES ON db.table FROM ALL クエリなどを実行する必要があります。
• 権限に対する有効期間の設定はありません。

ユーザーアカウント

ユーザーアカウントは、ClickHouse で誰かを認可するためのアクセスエンティティです。ユーザーアカウントには次の情報が含まれます。

• 識別情報
• ユーザーが実行できるクエリの範囲を定義する権限
• ClickHouse サーバーへの接続を許可されているホスト
• 割り当てられたロールおよびデフォルトロール
• ユーザーログイン時にデフォルトで適用される制約付き設定
• 割り当てられた設定プロファイル

権限は、GRANT クエリ、またはロールを割り当てることによってユーザーアカウントに付与できます。ユーザーから権限を取り消すには、ClickHouse は REVOKE クエリを提供します。ユーザーに対する権限の一覧を取得するには、SHOW GRANTS ステートメントを使用します。

管理クエリ:

• CREATE USER
• ALTER USER
• DROP USER
• SHOW CREATE USER
• SHOW USERS

設定の適用

設定は、ユーザーアカウント、そのユーザーに付与されたロール、および設定プロファイルでそれぞれ異なる値を構成できます。ユーザーログイン時に、ある設定が複数のアクセスエンティティで構成されている場合、その値と制約は次のように適用されます（優先度の高い順）。

1. ユーザーアカウントの設定。
2. ユーザーアカウントのデフォルトロールに対する設定。ある設定が複数のロールで構成されている場合、その設定の適用順序は未定義です。
3. ユーザーまたはそのデフォルトロールに割り当てられた設定プロファイルからの設定。ある設定が複数のプロファイルで構成されている場合、その設定の適用順序は未定義です。
4. サーバー全体にデフォルトで適用される設定、または default profile からの設定。

ロール

ロールは、ユーザーアカウントに付与できるアクセスエンティティのコンテナです。

ロールには次の内容が含まれます。

• 権限
• 設定と制約
• 割り当てられたロールのリスト

管理クエリ:

• CREATE ROLE
• ALTER ROLE
• DROP ROLE
• SET ROLE
• SET DEFAULT ROLE
• SHOW CREATE ROLE
• SHOW ROLES

権限は、GRANT クエリによってロールに付与できます。ロールから権限を取り消すには、ClickHouse は REVOKE クエリを提供します。

行ポリシー

Row policy は、どの行がユーザーまたはロールから利用可能かを定義するフィルターです。Row policy には、特定の 1 つのテーブルに対するフィルターと、この row policy を適用すべきロールやユーザーの一覧が含まれます。

注記

Row policy は、readonly アクセスしか持たないユーザーの場合にのみ意味があります。ユーザーがテーブルを変更したり、テーブル間でパーティションをコピーできる場合、row policy による制限は迂回されてしまいます。

管理クエリ:

• CREATE ROW POLICY
• ALTER ROW POLICY
• DROP ROW POLICY
• SHOW CREATE ROW POLICY
• SHOW POLICIES

Settings profile

Settings profile は、settings の集合です。Settings profile には、設定と制約、およびこのプロファイルが適用されるロールやユーザーの一覧が含まれます。

管理クエリ:

• CREATE SETTINGS PROFILE
• ALTER SETTINGS PROFILE
• DROP SETTINGS PROFILE
• SHOW CREATE SETTINGS PROFILE
• SHOW PROFILES

Quota

Quota はリソース使用量を制限します。Quotas を参照してください。

Quota には、特定の期間に対する一連の制限と、この quota を使用すべきロールやユーザーの一覧が含まれます。

管理クエリ:

• CREATE QUOTA
• ALTER QUOTA
• DROP QUOTA
• SHOW CREATE QUOTA
• SHOW QUOTA
• SHOW QUOTAS

SQL ベースのアクセス制御とアカウント管理の有効化

• 設定ストレージ用のディレクトリをセットアップします。

  ClickHouse は、access_control_path サーバー設定パラメータで指定されたフォルダにアクセスエンティティの設定を保存します。

• 少なくとも 1 つのユーザーアカウントに対して、SQL ベースのアクセス制御とアカウント管理を有効化します。

  既定では、SQL ベースのアクセス制御とアカウント管理はすべてのユーザーで無効になっています。users.xml 設定ファイルで少なくとも 1 つのユーザーを設定し、access_management、named_collection_control、show_named_collections、show_named_collections_secrets 設定の値を 1 に設定する必要があります。

SQL ユーザーとロールの定義

ヒント

ClickHouse Cloud を使用している場合は、Cloud access management を参照してください。

この記事では、SQL ユーザーおよびロールの基本的な定義方法と、それらに付与した権限をデータベース、テーブル、行、列に適用する方法について説明します。

SQL ユーザーモードの有効化

1. users.xml ファイル内の <default> ユーザーの下で SQL ユーザーモードを有効化します:

   <access_management>1</access_management>
   <named_collection_control>1</named_collection_control>
   <show_named_collections>1</show_named_collections>
   <show_named_collections_secrets>1</show_named_collections_secrets>
   
   注記

   default ユーザーは新規インストール時に作成される唯一のユーザーであり、デフォルトではノード間通信にも使用されます。

   本番環境では、SQL 管理者ユーザーでノード間通信を構成し、<secret>、クラスタ認証情報、および／またはノード間 HTTP・トランスポートプロトコルの認証情報を設定した後は、この default ユーザーを無効化することが推奨されます。default アカウントはノード間通信に使用されるためです。

2. 変更を反映するためにノードを再起動します。

3. ClickHouse クライアントを起動します:

   clickhouse-client --user default --password <password>
   

ユーザーの定義

1. SQL 管理者アカウントを作成します:

   CREATE USER clickhouse_admin IDENTIFIED BY 'password';
   
2. 新しいユーザーに完全な管理権限を付与します:

   GRANT ALL ON *.* TO clickhouse_admin WITH GRANT OPTION;
   

ALTER 権限

この記事は、権限の定義方法と、特権ユーザーが ALTER ステートメントを使用する際に権限がどのように機能するかについて、よりよく理解できるようにすることを目的としています。

ALTER ステートメントはいくつかのカテゴリーに分かれており、その一部は階層構造を持ちますが、そうでないものは明示的に定義する必要があります。

DB・テーブル・ユーザー設定の例

1. 管理者ユーザーとしてサンプルユーザーを作成します

CREATE USER my_user IDENTIFIED BY 'password';

2. サンプルデータベースを作成

CREATE DATABASE my_db;

3. サンプルテーブルを作成する

CREATE TABLE my_db.my_table (id UInt64, column1 String) ENGINE = MergeTree() ORDER BY id;

4. 権限の付与／取り消しを行うためのサンプル管理ユーザーを作成する

CREATE USER my_alter_admin IDENTIFIED BY 'password';

注記

権限を付与または取り消すには、管理ユーザーが WITH GRANT OPTION 権限を持っている必要があります。 例えば、次のようになります。

GRANT ALTER ON my_db.* WITH GRANT OPTION

GRANT または REVOKE で権限を付与・取り消しするには、そのユーザー自身が事前にその権限を保持している必要があります。

権限の付与と取り消し

ALTER の階層:

├── ALTER (テーブルおよびビューのみ)/
│   ├── ALTER TABLE/
│   │   ├── ALTER UPDATE
│   │   ├── ALTER DELETE
│   │   ├── ALTER COLUMN/
│   │   │   ├── ALTER ADD COLUMN
│   │   │   ├── ALTER DROP COLUMN
│   │   │   ├── ALTER MODIFY COLUMN
│   │   │   ├── ALTER COMMENT COLUMN
│   │   │   ├── ALTER CLEAR COLUMN
│   │   │   └── ALTER RENAME COLUMN
│   │   ├── ALTER INDEX/
│   │   │   ├── ALTER ORDER BY
│   │   │   ├── ALTER SAMPLE BY
│   │   │   ├── ALTER ADD INDEX
│   │   │   ├── ALTER DROP INDEX
│   │   │   ├── ALTER MATERIALIZE INDEX
│   │   │   └── ALTER CLEAR INDEX
│   │   ├── ALTER CONSTRAINT/
│   │   │   ├── ALTER ADD CONSTRAINT
│   │   │   └── ALTER DROP CONSTRAINT
│   │   ├── ALTER TTL/
│   │   │   └── ALTER MATERIALIZE TTL
│   │   ├── ALTER SETTINGS
│   │   ├── ALTER MOVE PARTITION
│   │   ├── ALTER FETCH PARTITION
│   │   └── ALTER FREEZE PARTITION
│   └── ALTER LIVE VIEW/
│       ├── ALTER LIVE VIEW REFRESH
│       └── ALTER LIVE VIEW MODIFY QUERY
├── ALTER DATABASE
├── ALTER USER
├── ALTER ROLE
├── ALTER QUOTA
├── ALTER [ROW] POLICY
└── ALTER [SETTINGS] PROFILE

1. ユーザーまたはロールへの ALTER 権限の付与

GRANT ALTER ON *.* TO my_user を実行しても、トップレベルの ALTER TABLE と ALTER VIEW にのみ影響し、その他の ALTER 文には影響しません。その他の ALTER 文については、それぞれ個別に権限を付与または取り消す必要があります。

たとえば、基本的な ALTER 権限を付与する場合:

GRANT ALTER ON my_db.my_table TO my_user;

最終的に付与される権限の一覧:

SHOW GRANTS FOR  my_user;

SHOW GRANTS FOR my_user

クエリID: 706befbc-525e-4ec1-a1a2-ba2508cc09e3

┌─my_userへの権限──────────────────────────────────────────────┐
│ GRANT ALTER TABLE, ALTER VIEW ON my_db.my_table TO my_user   │
└──────────────────────────────────────────────────────────────┘

これは、上記の例において ALTER TABLE および ALTER VIEW 配下のすべての権限を付与しますが、ALTER ROW POLICY のようないくつかの他の ALTER 権限は付与しません（権限の階層を参照すると、ALTER ROW POLICY は ALTER TABLE や ALTER VIEW の子ではないことが分かります）。それらは明示的に付与または取り消す必要があります。

ALTER 権限の一部だけが必要な場合は、それぞれを個別に付与できます。その権限にサブ権限がある場合は、それらも自動的に付与されます。

例えば次のようにします。

GRANT ALTER COLUMN ON my_db.my_table TO my_user;

権限は次のように付与します：

SHOW GRANTS FOR my_user;

SHOW GRANTS FOR my_user

Query id: 47b3d03f-46ac-4385-91ec-41119010e4e2

┌─GRANTS FOR my_user────────────────────────────────┐
│ GRANT ALTER COLUMN ON default.my_table TO my_user │
└───────────────────────────────────────────────────┘

1 row in set. Elapsed: 0.004 sec.

これにより、以下のサブ権限も与えられます。

ALTER ADD COLUMN
ALTER DROP COLUMN
ALTER MODIFY COLUMN
ALTER COMMENT COLUMN
ALTER CLEAR COLUMN
ALTER RENAME COLUMN

2. ユーザーおよびロールからの ALTER 権限の取り消し

REVOKE 文は、GRANT 文と同様に動作します。

ユーザーまたはロールにサブ権限が付与されている場合、そのサブ権限を直接取り消すことも、そのサブ権限が継承しているより上位の権限を取り消すこともできます。

たとえば、ユーザーに ALTER ADD COLUMN が付与されている場合

GRANT ALTER ADD COLUMN ON my_db.my_table TO my_user;

GRANT ALTER ADD COLUMN ON my_db.my_table TO my_user

Query id: 61fe0fdc-1442-4cd6-b2f3-e8f2a853c739

Ok.

0 rows in set. Elapsed: 0.002 sec.

SHOW GRANTS FOR my_user;

SHOW GRANTS FOR my_user

Query id: 27791226-a18f-46c8-b2b4-a9e64baeb683

┌─GRANTS FOR my_user──────────────────────────────────┐
│ GRANT ALTER ADD COLUMN ON my_db.my_table TO my_user │
└─────────────────────────────────────────────────────┘

権限は個別に取り消すことができます。

REVOKE ALTER ADD COLUMN ON my_db.my_table FROM my_user;

または、いずれかの上位レベルから取り消すこともできます（COLUMN のサブ権限をすべて取り消す）:

REVOKE ALTER COLUMN ON my_db.my_table FROM my_user;

REVOKE ALTER COLUMN ON my_db.my_table FROM my_user

Query id: b882ba1b-90fb-45b9-b10f-3cda251e2ccc

Ok.

0 rows in set. Elapsed: 0.002 sec.

SHOW GRANTS FOR my_user;

SHOW GRANTS FOR my_user

Query id: e7d341de-de65-490b-852c-fa8bb8991174

Ok.

0 rows in set. Elapsed: 0.003 sec.

追加事項

権限を付与するユーザーは、WITH GRANT OPTION を持っているだけでなく、その権限自体も保持している必要があります。

1. 管理者ユーザーに権限を付与し、さらに一連の権限を管理できるようにするには 以下はその例です。

GRANT SELECT, ALTER COLUMN ON my_db.my_table TO my_alter_admin WITH GRANT OPTION;

これでユーザーは ALTER COLUMN 権限とそのすべてのサブ権限を付与または取り消すことができます。

テスト

1. SELECT 権限を追加する

 GRANT SELECT ON my_db.my_table TO my_user;

2. ユーザーに ADD COLUMN 権限を付与する

GRANT ADD COLUMN ON my_db.my_table TO my_user;

3. 権限が制限されたユーザーでログインする

clickhouse-client --user my_user --password password --port 9000 --host <your_clickhouse_host>

4. 列追加をテストする

ALTER TABLE my_db.my_table ADD COLUMN column2 String;

ALTER TABLE my_db.my_table
    ADD COLUMN `column2` String

Query id: d5d6bfa1-b80c-4d9f-8dcd-d13e7bd401a5

Ok.

0 rows in set. Elapsed: 0.010 sec.

DESCRIBE my_db.my_table;

DESCRIBE TABLE my_db.my_table

Query id: ab9cb2d0-5b1a-42e1-bc9c-c7ff351cb272

┌─name────┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ UInt64 │ │ │ │ │ │ │ column1 │ String │ │ │ │ │ │ │ column2 │ String │ │ │ │ │ │ └─────────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

4. カラムの削除をテストする
```sql
ALTER TABLE my_db.my_table DROP COLUMN column2;

ALTER TABLE my_db.my_table
    DROP COLUMN column2

Query id: 50ad5f6b-f64b-4c96-8f5f-ace87cea6c47

0 rows in set. Elapsed: 0.004 sec.

サーバーから例外を受信しました (version 22.5.1):
Code: 497. DB::Exception: Received from chnode1.marsnet.local:9440. DB::Exception: my_user: 権限が不足しています。このクエリを実行するには、my_db.my_table に対する ALTER DROP COLUMN(column2) 権限の付与が必要です。(ACCESS_DENIED)

5. 権限を付与し、ALTER ADMIN ロールをテストする

GRANT SELECT, ALTER COLUMN ON my_db.my_table TO my_alter_admin WITH GRANT OPTION;

6. alter admin ユーザーとしてログインします

clickhouse-client --user my_alter_admin --password password --port 9000 --host <my_clickhouse_host>

7. 下位権限を付与する

GRANT ALTER ADD COLUMN ON my_db.my_table TO my_user;

GRANT ALTER ADD COLUMN ON my_db.my_table TO my_user

Query id: 1c7622fa-9df1-4c54-9fc3-f984c716aeba

Ok.

8. alter 管理ユーザーが保持していない権限を付与しようとした場合、それが admin ユーザーに付与されている権限のサブ権限ではないため付与できないことをテストします。

GRANT ALTER UPDATE ON my_db.my_table TO my_user;

GRANT ALTER UPDATE ON my_db.my_table TO my_user

クエリID: 191690dc-55a6-4625-8fee-abc3d14a5545

0行のセット。経過時間: 0.004秒

サーバーから例外を受信しました（バージョン22.5.1）:
コード: 497. DB::Exception: chnode1.marsnet.local:9440から受信。DB::Exception: my_alter_admin: 権限が不足しています。このクエリを実行するには、ALTER UPDATE ON my_db.my_table WITH GRANT OPTIONの付与が必要です。(ACCESS_DENIED)

概要 ALTER の権限は、テーブルおよびビューを対象とする ALTER については階層構造になっていますが、その他の ALTER ステートメントについてはそうではありません。権限は細かな粒度で設定することも、複数の権限をまとめて設定することもでき、取り消しも同様に行えます。権限を付与または取り消すユーザーは、対象ユーザー（自分自身を含む）の権限を設定するために WITH GRANT OPTION を保持している必要があり、かつその権限自体も既に所有していなければなりません。WITH GRANT OPTION を持たないユーザーは、自分自身の権限を取り消すことはできません。