在 ClickHouse 中创建用户和角色

ClickHouse 支持基于 RBAC 方法的访问控制管理。

ClickHouse 访问实体

• 用户帐户
• 角色
• 行策略
• 设置配置文件
• 配额

您可以使用以下方式配置访问实体

• SQL 驱动的工作流程。

  您需要启用此功能。

• 服务器配置文件 users.xml 和 config.xml。

我们建议使用 SQL 驱动的工作流程。两种配置方法可以同时工作，因此如果您使用服务器配置文件来管理帐户和访问权限，您可以平滑地切换到 SQL 驱动的工作流程。

注意

您不能同时通过两种配置方法管理同一个访问实体。

注意

如果您正在查找管理 ClickHouse Cloud Console 用户，请参阅此页面

要查看所有用户、角色、配置文件等及其所有授权，请使用SHOW ACCESS语句。

概述

默认情况下，ClickHouse 服务器提供 default 用户帐户，该帐户不允许使用 SQL 驱动的访问控制和帐户管理，但拥有所有权利和权限。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. 默认情况下或从默认配置文件应用于整个服务器的设置。

角色

角色是可以授予用户帐户的访问实体的容器。

角色包含

• 权限
• 设置和约束
• 已分配角色列表

管理查询

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

可以使用 GRANT 查询将权限授予角色。要从角色撤销权限，ClickHouse 提供了 REVOKE 查询。

行策略

行策略是一个过滤器，用于定义哪些行对用户或角色可用。行策略包含一个特定表的过滤器，以及应使用此行策略的角色和/或用户列表。

注意

行策略仅对具有只读访问权限的用户有意义。如果用户可以修改表或在表之间复制分区，则会破坏行策略的限制。

管理查询

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

设置配置文件

设置配置文件是设置的集合。设置配置文件包含设置和约束，以及应用此配置文件的角色和/或用户列表。

管理查询

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

配额

配额限制资源使用。请参阅配额。

配额包含一组针对某些持续时间的限制，以及应使用此配额的角色和/或用户列表。

管理查询

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

启用 SQL 驱动的访问控制和帐户管理

• 设置用于配置存储的目录。

  ClickHouse 将访问实体配置存储在 access_control_path 服务器配置参数中设置的文件夹中。

• 为至少一个用户帐户启用 SQL 驱动的访问控制和帐户管理。

  默认情况下，SQL 驱动的访问控制和帐户管理对所有用户禁用。您需要在 users.xml 配置文件中配置至少一个用户，并将 access_management、named_collection_control、show_named_collections 和 show_named_collections_secrets 设置的值设置为 1。

定义 SQL 用户和角色

提示

如果您正在 ClickHouse Cloud 中工作，请参阅云访问管理。

本文介绍了定义 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 帐户用于节点间通信。

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 (only for table and view)/
│   ├── 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 权限

GRANT ALTER ON my_db.my_table TO my_user;

生成的权限集

SHOW GRANTS FOR  my_user;

SHOW GRANTS FOR my_user

Query id: 706befbc-525e-4ec1-a1a2-ba2508cc09e3

┌─GRANTS FOR my_user───────────────────────────────────────────┐
│ GRANT ALTER TABLE, ALTER VIEW ON my_db.my_table TO my_user   │
└──────────────────────────────────────────────────────────────┘

这将授予上面示例中 ALTER TABLE 和 ALTER VIEW 下的所有权限，但是，它不会授予某些其他 ALTER 权限，例如 ALTER ROW POLICY（参考层次结构，您将看到 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. 将添加列权限添加到用户

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. 测试删除列

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.

Received exception from server (version 22.5.1):
Code: 497. DB::Exception: Received from chnode1.marsnet.local:9440. DB::Exception: my_user: Not enough privileges. To execute this query it's necessary to have grant ALTER DROP COLUMN(column2) ON my_db.my_table. (ACCESS_DENIED)

5. 通过授予权限来测试 alter 管理员

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

6. 使用 alter 管理员用户登录

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 管理员用户不拥有的权限不是管理员用户授权的子权限。

GRANT ALTER UPDATE ON my_db.my_table TO my_user;

GRANT ALTER UPDATE ON my_db.my_table TO my_user

Query id: 191690dc-55a6-4625-8fee-abc3d14a5545


0 rows in set. Elapsed: 0.004 sec.

Received exception from server (version 22.5.1):
Code: 497. DB::Exception: Received from chnode1.marsnet.local:9440. DB::Exception: my_alter_admin: Not enough privileges. To execute this query it's necessary to have grant ALTER UPDATE ON my_db.my_table WITH GRANT OPTION. (ACCESS_DENIED)

总结 对于具有表和视图的 ALTER，ALTER 权限是分层的，但对于其他 ALTER 语句则不是。权限可以设置为精细级别或权限分组，也可以类似地撤销。授予或撤销的用户必须具有 WITH GRANT OPTION 才能设置用户的权限，包括操作用户自己，并且必须已经拥有该权限。如果操作用户自己没有授权选项权限，则无法撤销自己的权限。