CREATE USER | ClickHouse Docs

構文:

CREATE USER [IF NOT EXISTS | OR REPLACE] name1 [, name2 [,...]] [ON CLUSTER cluster_name]
    [{VALID UNTIL datetime | VALID FOR interval}]
    [NOT IDENTIFIED | IDENTIFIED {[WITH {plaintext_password | sha256_password | sha256_hash | double_sha1_password | double_sha1_hash}] BY {'password' | 'hash'}} | WITH NO_PASSWORD | {WITH ldap SERVER 'server_name'} | {WITH kerberos [REALM 'realm']} | {WITH ssl_certificate CN 'common_name' | SAN 'TYPE:subject_alt_name'} | {WITH ssh_key BY KEY 'public_key' TYPE 'ssh-rsa|...'} | {WITH http SERVER 'server_name' [SCHEME 'Basic']} [{VALID UNTIL datetime | VALID FOR interval}] [GRANTS (privilege ON object [,...])]
    [, {[{plaintext_password | sha256_password | sha256_hash | ...}] BY {'password' | 'hash'}} | {ldap SERVER 'server_name'} | {...} | ... [,...]]]
    [HOST {LOCAL | NAME 'name' | REGEXP 'name_regexp' | IP 'address' | LIKE 'pattern'} [,...] | ANY | NONE]
    [IN access_storage_type]
    [ROLE role [,...]]
    [DEFAULT ROLE role [,...]]
    [DEFAULT DATABASE database | NONE]
    [GRANTEES {user | role | ANY | NONE} [,...] [EXCEPT {user | role} [,...]]]
    [SETTINGS variable [= value] [MIN [=] min_value] [MAX [=] max_value] [READONLY | WRITABLE] | PROFILE 'profile_name'] [,...]

ON CLUSTER 句を使用すると、クラスター内にユーザーを作成できます。詳細は Distributed DDL を参照してください。

識別

ユーザーの識別方法には、複数の種類があります。

IDENTIFIED WITH no_password
IDENTIFIED WITH plaintext_password BY 'qwerty'
IDENTIFIED WITH sha256_password BY 'qwerty' or IDENTIFIED BY 'password'
IDENTIFIED WITH sha256_hash BY 'hash' or IDENTIFIED WITH sha256_hash BY 'hash' SALT 'salt'
IDENTIFIED WITH double_sha1_password BY 'qwerty'
IDENTIFIED WITH double_sha1_hash BY 'hash'
IDENTIFIED WITH bcrypt_password BY 'qwerty'
IDENTIFIED WITH bcrypt_hash BY 'hash'
IDENTIFIED WITH ldap SERVER 'server_name'
IDENTIFIED WITH kerberos or IDENTIFIED WITH kerberos REALM 'realm'
IDENTIFIED WITH ssl_certificate CN 'mysite.com:user'
IDENTIFIED WITH ssh_key BY KEY 'public_key' TYPE 'ssh-rsa', KEY 'another_public_key' TYPE 'ssh-ed25519'
IDENTIFIED WITH http SERVER 'http_server' or IDENTIFIED WITH http SERVER 'http_server' SCHEME 'basic'
IDENTIFIED BY 'qwerty'

パスワード複雑性の要件は、config.xml で変更できます。以下は、パスワードを 12 文字以上とし、数字を 1 つ含むことを必須にする設定例です。各パスワード複雑性ルールでは、パスワードに対して照合する正規表現と、そのルールの説明が必要です。

<clickhouse>
    <password_complexity>
        <rule>
            <pattern>.{12}</pattern>
            <message>be at least 12 characters long</message>
        </rule>
        <rule>
            <pattern>\p{N}</pattern>
            <message>contain at least 1 numeric character</message>
        </rule>
    </password_complexity>
</clickhouse>

例

次のユーザー名は name1 で、パスワードは不要です。これは当然ながら、ほとんどセキュリティになりません。
```
CREATE USER name1 NOT IDENTIFIED
```

平文パスワードを指定するには、次のようにします。

CREATE USER name2 IDENTIFIED WITH plaintext_password BY 'my_password'

最も一般的なのは、SHA-256 でハッシュ化されたパスワードを使用する方法です。IDENTIFIED WITH sha256_password を指定すると、ClickHouse がパスワードをハッシュ化します。例:
```
CREATE USER name3 IDENTIFIED WITH sha256_password BY 'my_password'
```
これで name3 ユーザーは my_password でログインできますが、パスワードは上記のハッシュ値として保存されます。次の SQL ファイルが /var/lib/clickhouse/access に作成され、サーバーの起動時に実行されます。
```
/var/lib/clickhouse/access $ cat 3843f510-6ebd-a52d-72ac-e021686d8a93.sql
ATTACH USER name3 IDENTIFIED WITH sha256_hash BY '0C268556C1680BEF0640AAC1E7187566704208398DA31F03D18C74F5C5BE5053' SALT '4FB16307F5E10048196966DD7E6876AE53DE6A1D1F625488482C75F14A5097C7';
```

double_sha1_password は通常は不要ですが、それを必要とするクライアント (MySQL インターフェイスなど) を扱う場合に便利です。
```
CREATE USER name4 IDENTIFIED WITH double_sha1_password BY 'my_password'
```
ClickHouse は次のクエリを生成して実行します。
```
CREATE USER name4 IDENTIFIED WITH double_sha1_hash BY 'CCD3A959D6A004B9C3807B728BC2E55B67E10518'
```
bcrypt_password は、パスワード保存において最も安全なオプションです。bcrypt アルゴリズムを使用しており、パスワードハッシュが漏えいした場合でも、総当たり攻撃に強いという特長があります。
```
CREATE USER name5 IDENTIFIED WITH bcrypt_password BY 'my_password'
```
この方式では、パスワードの長さは 72 文字までに制限されます。ハッシュの計算とパスワード検証に必要な計算量と時間を定義する bcrypt の work factor パラメーターは、サーバー設定で変更できます。
```
<bcrypt_workfactor>12</bcrypt_workfactor>
```
work factor は 4 から 31 の範囲でなければならず、デフォルト値は 12 です。

パスワードの種類は省略することもできます。
```
CREATE USER name6 IDENTIFIED BY 'my_password'
```
この場合、ClickHouse はサーバー設定で指定されたデフォルトのパスワード種類を使用します。
```
<default_password_type>sha256_password</default_password_type>
```
使用できるパスワード種類は次のとおりです: plaintext_password, sha256_password, double_sha1_password.

複数の認証方式を指定できます。

CREATE USER user1 IDENTIFIED WITH plaintext_password by '1', bcrypt_password by '2', plaintext_password by '3''

注記:

古いバージョンの ClickHouse では、複数の認証方式の構文がサポートされていない場合があります。したがって、ClickHouse serverにそのようなユーザーが存在する状態で、これを未対応のバージョンにダウングレードすると、そのようなユーザーは使用できなくなり、一部のユーザー関連の操作も正常に機能しなくなります。問題なくダウングレードするには、事前にすべてのユーザーが単一の認証方式のみを持つように設定しておく必要があります。あるいは、適切な手順を踏まずにサーバーをダウングレードしてしまった場合は、問題のあるユーザーを削除する必要があります。
セキュリティ上の理由から、no_password は他の認証方式と共存できません。したがって、no_password を指定できるのは、それがクエリ内で唯一の認証方式である場合に限られます。

ユーザーホスト

ユーザーホストとは、ClickHouse server への接続を確立できるホストです。ホストは、HOST クエリセクションで次の方法により指定できます。

HOST IP 'ip_address_or_subnetwork' — ユーザーは、指定した IP アドレスまたはサブネットワークからのみ ClickHouse server に接続できます。例: HOST IP '192.168.0.0/16'、HOST IP '2001:DB8::/32'。本番環境で使用する場合は、host や host_regexp を使用すると余分な遅延が発生する可能性があるため、HOST IP 要素 (IP アドレスとそのマスク) のみを指定してください。
HOST ANY — ユーザーは任意の場所から接続できます。これはデフォルトのオプションです。
HOST LOCAL — ユーザーはローカルからのみ接続できます。
HOST NAME 'fqdn' — ユーザーホストは FQDN として指定できます。たとえば、HOST NAME 'mysite.com' です。
HOST REGEXP 'regexp' — ユーザーホストを指定する際に、pcre 正規表現を使用できます。たとえば、HOST REGEXP '.*\.mysite\.com' です。
HOST LIKE 'template' — LIKE 演算子を使用してユーザーホストを絞り込めます。たとえば、HOST LIKE '%' は HOST ANY と同等で、HOST LIKE '%.mysite.com' は mysite.com ドメイン内のすべてのホストを絞り込みます。

ホストを指定する別の方法として、ユーザー名の後に @ 構文を続けて使用する方法があります。例:

CREATE USER mira@'127.0.0.1' — HOST IP 構文と同等です。
CREATE USER mira@'localhost' — HOST LOCAL 構文と同等です。
CREATE USER mira@'192.168.%.%' — HOST LIKE 構文と同等です。

VALID UNTIL 句

認証方式の有効期限の日付と、必要に応じて時刻を指定できます。パラメータには文字列を指定します。datetime には YYYY-MM-DD [hh:mm:ss] [timezone] フォーマットを使用することを推奨します。[timezone] には、+09:00 のような数値オフセット、または UTC、GMT、Z、MSK、MSD のいずれかを指定する必要があります。Asia/Tokyo のような名前付き IANA ゾーンは認識されません (以下の注記を参照) 。デフォルトでは、このパラメータは 'infinity' です。指定できるデッドラインの範囲は、1900-01-01 00:00:00 UTC から 9999-12-31 09:59:59 UTC までです。これは、すべてのタイムゾーンで年 9999 内に収まる最新の時点であるため、格納された時点が表示時にクランプされることはありません。過去のデッドラインは、認証情報がすでに期限切れであることを意味します。1970-01-01 00:00:01 UTC より前のデッドラインは、「すでに期限切れ」を示すマーカーとしてのみ受け入れられます。これらは Unix epoch の 1 秒後 (1970-01-01 00:00:01 UTC) にあたる、期限切れの最小時点へ正規化されます。そのため、SHOW CREATE USER では指定したデッドラインではなく、この時点が表示されます。この時点以降のデッドラインは正確に格納されます。

デッドラインは絶対時点として格納されますが、SHOW CREATE USER と system.users ではサーバーまたは session time zone で表示されます。そのため、同じ格納時点でも、設定が異なるサーバーでは異なるローカル時刻の文字列として表示されます。たとえば、上記の正規化された期限切れ時点は、UTC のサーバーでは 1970-01-01 00:00:01、Pacific/Kiritimati のサーバーでは 1970-01-01 14:00:01 と表示されます。実際の適用では常に格納時点が使用され、表示結果は使用されません。

句の配置によって、適用先の認証方式が決まります。

IDENTIFIED 句より前に指定した場合 (またはクエリで認証方式をまったく指定しない場合) : デッドラインはユーザーレベルのデッドラインとなり、そのユーザーのすべての認証方式に適用されます。
認証方式の後に指定した場合: デッドラインはその方式にのみ適用されます。したがって、IDENTIFIED リスト全体の後に記述した句は最後の方式にのみ関連付けられ、それ以前の方式には有効期限が設定されません。

例:

CREATE USER name1 VALID UNTIL '2025-01-01'
CREATE USER name1 VALID UNTIL '2025-01-01 12:00:00 UTC'
CREATE USER name1 VALID UNTIL '2025-01-01 12:00:00 +09:00'
CREATE USER name1 VALID UNTIL 'infinity'
CREATE USER name1 VALID UNTIL '2025-01-01' IDENTIFIED WITH plaintext_password BY 'password_1', bcrypt_password BY 'password_2' — ユーザーレベルのデッドラインが両方の方式に適用されます。
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID UNTIL '2025-01-01' — デッドラインは bcrypt_password 方式にのみ適用されます。plaintext_password は期限切れになりません。

VALID FOR 句

VALID FOR句は、VALID UNTILの簡便な短縮記法です。絶対的な日付と時刻の代わりにインターバルを指定でき、クエリの実行時点の現在時刻にそのインターバルを加算して有効期限のデッドラインを算出します。結果はVALID UNTIL形式で保存されるため、SHOW CREATE USERでは常に解決後の絶対デッドラインが表示されます。VALID UNTILを使用できるすべての場所で使用でき、配置規則も同じです。IDENTIFIEDの前に指定した場合 (または認証方式を指定しない場合) は、すべての方式に適用されるユーザーレベルのデッドラインとなります。一方、認証方式の後に指定した場合は、その方式にのみ適用されます。デッドラインは秒精度で保存・適用されるため、秒未満のインターバル (NANOSECOND、MICROSECOND、MILLISECOND) は受け付けられません。指定できる最小単位はSECONDです。負のインターバルは、認証情報がすでに期限切れであることを示すために使用できます。結果のデッドラインが1970-01-01 00:00:01 UTCより前になる場合は、期限切れとなる最小の時点に正規化されます。SHOW CREATE USERではその値が表示され、VALID UNTILで説明しているとおり、serverまたはsessionのtime zoneで表示されます。

例:

CREATE USER name1 VALID FOR INTERVAL 1 DAY
CREATE USER name1 VALID FOR INTERVAL 3 MONTH
CREATE USER name1 VALID FOR INTERVAL 1 DAY + INTERVAL 12 HOUR
CREATE USER name1 VALID FOR INTERVAL 30 DAY IDENTIFIED WITH plaintext_password BY 'password_1', bcrypt_password BY 'password_2' — ユーザーレベルのデッドラインは両方の方式に適用されます。
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID FOR INTERVAL 30 DAY — デッドラインはbcrypt_password方式にのみ適用されます。plaintext_passwordは期限切れになりません。

GRANTS 句

特定の認証方式で認証されたセッションで使用可能なアクセス権を制限できます。括弧内に、GRANT ステートメントと同じ形式で権限のリストを指定します。この句は認証方式の後 (VALID UNTIL 句がある場合はその後) に指定し、その方式にのみ適用されます。

ユーザーがこのような認証方式でログインすると、セッションのアクセス権は、ユーザーのアクセス権 (付与されたロールによる権限を含む) と句に列挙された権限の積集合になります。この句によってアクセス権が追加されることはありません。列挙された権限がユーザーに付与されていない場合、セッションはその権限を持ちません。このような方式で認証されたセッションでは、権限の付与 (GRANT OPTION は積集合を取ると必ず失われます) やロールの管理もできません。ロールの管理には、ロールの作成、変更、削除、付与、取り消しだけでなく、ユーザーに対してデフォルトで有効化されるロールの変更 (SET DEFAULT ROLE および ALTER USER ... DEFAULT ROLE) も含まれ、これも拒否されます。

EXECUTE AS はセッションのプリンシパルを切り替えるため、権限借用中に実行されるステートメントは、ログインしたユーザーの権限ではなく、対象ユーザーのアクセス権と列挙された権限の積集合によって制限されます。制限自体が解除されることはなく、権限借用には IMPERSONATE ON target がユーザーに付与され、かつ句にも列挙されている必要があります。そのため、制限付き認証情報で同じユーザーの無制限の認証情報より広い権限を得ることはできません。

これにより、アプリケーション用トークンを簡単に作成できます。つまり、有効期限と限定された権限セットを持ち、ユーザーに紐付けられた追加の認証情報です。これは system.query_log および system.processes ではそのユーザーとして表示され、ユーザーが削除されると使用できなくなり、ユーザーがアクセス権を失うとトークンもそのアクセス権を失います。

Caution - Warning

強制適用はイニシエーターでのみ行われます。 認証方式の GRANTS 制限と VALID UNTIL の有効期限は、クエリを受信するノード (イニシエーター) でのみ強制適用されます。これらはクラスター内の他のノードには伝播されないため、この句でクラスター全体の実行を制限できるとは考えないでください。リモートノードでは通常どおりロールのスコープが適用されます。この句は users.xml では使用できません。クエリ結果キャッシュは、ユーザーのすべての認証方式で共有されます。エントリはユーザーとロールごとに分離されますが、キャッシュヒット時には、セッションがログインに使用した方式の GRANTS に対する再チェックは行われません。

例:

CREATE USER name1 IDENTIFIED BY 'qwerty' GRANTS (SELECT ON db.*)
ALTER USER name1 ADD IDENTIFIED WITH plaintext_password BY 'app_token' VALID UNTIL '2026-12-31' GRANTS (SELECT ON db.table, INSERT ON db.table)

この制限は認証方式のプロパティであり、ログイン時に確定されることに注意してください。ALTER USER で句を変更しても影響するのは新しいセッションのみで、すでに確立されているセッションには影響しません。

READ ON S3('s3://bucket/.*') のようなフィルター付きログソースの grant は、まだこの句ではサポートされていません。積集合ではログソースフィルターを不透明な文字列として比較するため、あるフィルターを別のフィルターに絞り込むことができません。そのため、このような grant はアクセス権が暗黙的に付与されないのではなく、拒否されます。

この句は、認証情報がサーバーによって完全にローカルで検証される認証方式でのみサポートされます。検証時に外部システムに接続する方式 (または jwt の場合、たとえば署名キーを取得するために接続する可能性がある方式) (ldap、kerberos、http、jwt) では、この句は拒否されます。複数の認証方式が同じ認証情報を受け入れる場合、制限は他の方式に対して認証情報を再検証することで強制されますが、外部システムへの追加の照会は安全ではありません。そのため、同じ認証情報を受け入れる別の方式が制限を回避する可能性があります。

同じ実効認証情報が複数の認証方式で受け入れられる場合、ログインはそれらすべてによってフェイルクローズで制限されます。セッションには一致するすべての方式の GRANTS の積集合が適用され、有効期限はそれらの VALID UNTIL のうち最も早いものになります。最も早い VALID UNTIL は、すでに過ぎている場合でも優先されます。単一の一致した方式が期限切れになった場合とまったく同様にログインは拒否されるため、トークンの期限切れによって共有認証情報に、より広範な方式の権限や有効期間が暗黙的に与えられることはありません。

この組み合わせは、server によってローカルで検証される認証方式間でのみ確認されます。これは、上記の外部で検証される method で句自体が拒否されるのと同じ理由によるものです。つまり、その認証情報を再確認するには、外部システムに対する安全でない追加の照会が必要になるためです。したがって、同じ認証情報が同じ USER の外部で検証される method (ldap、kerberos、http、jwt) でも受け入れられる場合でも、その method 固有の VALID UNTIL はこの組み合わせの対象には含まれず、そこに設定されたより早い有効期限によって、ローカルで検証される method を通じて取得されたセッションが短縮されることはありません。

GRANTEES 句

このユーザーが GRANT OPTION 付きで必要なすべてのアクセス権も付与されている場合に、このユーザーから権限を受け取ることができるユーザーまたはロールを指定します。GRANTEES 句のオプションは次のとおりです。

user — このユーザーが権限を付与できるユーザーを指定します。
role — このユーザーが権限を付与できるロールを指定します。
ANY — このユーザーは誰にでも権限を付与できます。デフォルト設定です。
NONE — このユーザーは誰にも権限を付与できません。

EXCEPT 式を使用すると、任意のユーザーまたはロールを除外できます。たとえば、CREATE USER user1 GRANTEES ANY EXCEPT user2 と指定します。これは、user1 が GRANT OPTION 付きでいくつかの権限を付与されている場合、それらの権限を user2 を除く誰にでも付与できることを意味します。

例

パスワード qwerty を設定したユーザーアカウント mira を作成します:

CREATE USER mira HOST IP '127.0.0.1' IDENTIFIED WITH sha256_password BY 'qwerty';

mira は、ClickHouse server が稼働しているホスト上でクライアントアプリを起動する必要があります。

ユーザーアカウント john を作成し、ロールを割り当てます:

CREATE USER john ROLE role1, role2;

ユーザーアカウント john を作成し、ロールを割り当て、その一部をデフォルトロールにします:

CREATE USER john ROLE role1, role2 DEFAULT ROLE role1;

または

CREATE USER john ROLE role1, role2 DEFAULT ROLE ALL EXCEPT role2;

ユーザーアカウント john を作成し、jack アカウントのユーザーに自身の権限を付与できるようにします:

CREATE USER john GRANTEES jack;

john のユーザーアカウントを作成するには、クエリパラメータを使用します:

SET param_user=john;
CREATE USER {user:Identifier};