diff --git a/docs/enterprise/overview.md b/docs/enterprise/overview.md index 5a6d0c601..507a77b97 100644 --- a/docs/enterprise/overview.md +++ b/docs/enterprise/overview.md @@ -39,6 +39,8 @@ which are described in detail in the documentation in this section: analytical queries. - [Triggers](./trigger.md): Periodically evaluate your rules and trigger external webhook. Compatible with Prometheus AlterManager. +- [Built-in User Management](./user.md): Built-in RBAC and fine-grained ACLs + for data security and isolation. - Reliability features for Flow. ## Release Notes diff --git a/docs/enterprise/user.md b/docs/enterprise/user.md new file mode 100644 index 000000000..1f8a17f70 --- /dev/null +++ b/docs/enterprise/user.md @@ -0,0 +1,256 @@ +--- +keywords: [User, Permission, GreptimeDB Enterprise, RBAC, ACL, Authentication] +description: The overview of GreptimeDB User and Permission mechanism. +--- + +# Built-in User Management + +GreptimeDB Enterprise provides a built-in user and permission system backed by +the Metasrv. It supports Role-Based Access Control (RBAC) and fine-grained +Access Control Lists (ACLs) to ensure data security and isolation. + +## Key Features + +- **Built-in User Management**: User accounts and permissions are stored in the + Metasrv, ensuring consistent management across the cluster. +- **Role-Based Access Control (RBAC)**: Assign global privileges to users, + controlling operations like `SELECT`, `INSERT`, `CREATE TABLE`, and more. +- **Fine-grained ACLs**: Control table-level access within specific databases + using exact matches or regular expressions. +- **Dynamic Management**: Manage users dynamically via HTTP APIs without + restarting the server. +- **Initial Seeding**: Support for seeding initial accounts from a password + file at startup. + +## Configuration and Explanation + +This section walks through how to enable the enterprise user provider and +perform basic user management. + +### 1. Enable User Provider + +To use the enterprise user and permission system, enable the +`greptime_ee_user_provider` in the component that receives client requests. +Configure it on the standalone server in standalone mode, or on each frontend +node in cluster mode. + +The user provider value is: + +```text +greptime_ee_user_provider: +``` + +The password file is optional and is used only for initial account seeding. To +enable the provider without seeding users, use `greptime_ee_user_provider:`. +The trailing colon `:` is required by the configuration parser. + +**Standalone command line:** + +```shell +./greptime standalone start \ + --user-provider=greptime_ee_user_provider:/path/to/passwords.txt +``` + +**Standalone configuration file:** + +```toml +user_provider = "greptime_ee_user_provider:/path/to/passwords.txt" +``` + +```shell +./greptime standalone start \ + -c /path/to/standalone.toml +``` + +**Frontend command line:** + +```shell +./greptime frontend start \ + --metasrv-addrs=127.0.0.1:3002 \ + --user-provider=greptime_ee_user_provider:/path/to/passwords.txt +``` + +**Frontend configuration file:** + +```toml +user_provider = "greptime_ee_user_provider:/path/to/passwords.txt" + +[meta_client] +metasrv_addrs = ["127.0.0.1:3002"] +``` + +Then start frontend with the configuration file: + +```shell +./greptime frontend start \ + -c /path/to/frontend.toml +``` + +### 2. Initial Account Seeding (Optional) + +The password file uses the following format: +`[:]=` + +Available roles: +- `admin`: Full privileges, including user management. +- `readonly` (or `ro`): Read-only access (`SqlSelect`). +- `writeonly` (or `wo`): Write-only access (e.g., `SqlInsert`, `TableCreate`). +- `readwrite` (or `rw`): Both read and write access (default). + +Example `passwords.txt`: + +```text +# username[:role]=password +superuser:admin=strong_password +alice:ro=alice_pwd +bob:rw=bob_pwd +``` + +Seeded users are granted full access (`AclType::All`) to the `public` database by default. + +Seed accounts are created only once. If a seeded user already exists on later +startups, it is skipped. You can modify seeded users later through the UI. + +## Privileges and ACLs + +### Global Privileges + +Privileges include the following operations: + +| Privilege | Description | +| :--- | :--- | +| `TableCreate` | Create new tables | +| `TableAlter` | Alter existing tables | +| `TableDrop` | Drop tables | +| `SqlSelect` | Execute `SELECT` queries | +| `SqlInsert` | Execute `INSERT` operations | +| `SqlDelete` | Execute `DELETE` operations | +| `FlowCreate` | Create flows | +| `FlowDrop` | Drop flows | +| `DatabaseCreate` | Create databases | +| `DatabaseAlter` | Alter databases | +| `DatabaseDrop` | Drop databases | +| `Admin` | Full administrative privileges | +| `TriggerCreate` | Create triggers | +| `TriggerDrop` | Drop triggers | +| `TriggerAlter` | Alter triggers | + +#### Predefined Role Privileges + +When using the password file for seeding, the predefined roles map to the +following privilege combinations: + +| Role | Privileges | +| :--- | :--- | +| `admin` | All privileges | +| `readonly` / `ro` | `SqlSelect` | +| `writeonly` / `wo` | `SqlInsert`, `SqlDelete`, `TableCreate`, `TableAlter`, `TableDrop`, `FlowCreate`, `FlowDrop`, `TriggerCreate`, `TriggerDrop`, `TriggerAlter`, `DatabaseCreate`, `DatabaseAlter`, `DatabaseDrop` | +| `readwrite` / `rw` | `readonly` + `writeonly` privileges | + +### Access Control Lists (ACLs) + +ACLs provide table-level security within a database. Each ACL entry is scoped to a +database and controls which tables in that database the user can access. + +The `all` ACL grants access to every table in the database. Use it when a user +should be able to read or write all current and future tables in that database, +subject to the user's global privileges. + +The `match` ACL grants access to one table by exact name. Use it when a user +should only access a specific table and should not automatically gain access to +other tables with similar names. + +The `regex` ACL grants access to tables whose names match a regular expression. +Use it when tables follow a naming convention and should be managed as a group. +For example, `mem_.*` matches table names that start with `mem_`, +`.*_metrics` matches table names that end with `_metrics`, and +`sensor_[0-9]+` matches names such as `sensor_1` and `sensor_2024`. +Regex ACLs are evaluated against table names within the configured database, so +use specific patterns when possible to avoid granting access to more tables than +intended. + +## Validation Rules + +### Username + +Usernames must: +- Start with a letter (`a-z` or `A-Z`) +- Contain only letters, digits, and underscores +- Match the pattern `[a-zA-Z][a-zA-Z0-9_]*` + +### Password + +Password validation depends on how the user is created or updated: + +- Seeded account passwords must not be empty. +- Passwords created or updated through the UI must be 6 to 64 characters long. + +## User Management in the Enterprise Dashboard + +After you enable `greptime_ee_user_provider`, both GreptimeDB and the +Enterprise Dashboard require users to log in with an account. +The following screenshot shows the Enterprise Dashboard login page: + +

+ login page +

+ +You can log in with the automatically created admin account or with an account +defined in the seeding file. + +Only accounts with the `Admin` privilege can see the database management menu. +Non-admin accounts can only access the query page, similar to the open-source +dashboard. + +After logging in as an admin user, click `User Management` in the lower-left +corner to open the user management page: + +

+ login page +

+ +This page lists all current users. From here, you can: + +1. Create users +2. Update existing users +3. Delete users + +The following screenshot shows the form for creating a user: + +

+ login page +

+ +In this form, you can configure: + +1. The username +2. The password +3. Whether the account has the `Admin` privilege. Non-admin users are granted + the `readwrite` privilege. +4. The account ACL list + +The ACL form has two tabs. You can select an exact table, select an entire +database to grant full-database access, or use a regular expression to grant +access to a range of tables. The following screenshot shows the regular +expression form: + +

+ login page +

+ +## Reference + +- **Admin Account**: On the system's first startup, GreptimeDB Enterprise + automatically creates a default `admin` account if it doesn't already exist. + - If the environment variable `GREPTIME_ENTERPRISE_ADMIN_PASSWORD` is set, + it uses that value as the password. + - If the environment variable is not set, it generates a random UUID as the + password. +- **Checking Auto-generated Password**: If a random password was generated, + you can find it in the GreptimeDB log files. Search for a message like: + ```text + Created admin user with auto-generated password + ``` +- **Persistence**: User information is persisted in the Metasrv's KV store, + making it available across all frontend nodes in a cluster. +- **Admin Protection**: The built-in `admin` user cannot be deleted via the API. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/overview.md index a88cc0c77..fe12fd039 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/overview.md @@ -33,6 +33,7 @@ GreptimeDB Enterprise 包括以下高级功能, - [Greptime 企业版管理控制台](./console-ui.md):加强版本的管理界面,提供更多的集群管理和监控功能。 - [读副本](./read-replicas/overview.md):专门运行复杂的查询操作的 datanode,避免影响实时写入。 - [Trigger](./trigger.md):定时查询和检测预配置的规则,可触发外部 webhook,兼容 Prometheus AlertManager。 +- [内置用户管理](./user.md):内置 RBAC 和细粒度 ACL,确保数据安全和隔离。 - Flow 的可靠性功能。 ## 发布说明 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/user.md b/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/user.md new file mode 100644 index 000000000..4a9f47c98 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/enterprise/user.md @@ -0,0 +1,242 @@ +--- +keywords: [用户, 权限, GreptimeDB 企业版, RBAC, ACL, 身份验证] +description: GreptimeDB 用户与权限机制概述。 +--- + +# 内置用户管理 + +GreptimeDB 企业版提供了由 Metasrv 支持的内置用户与权限系统。它支持 +基于角色的访问控制 (RBAC) 和细粒度访问控制列表 (ACL),用于保障数据 +安全与隔离。 + +## 主要特性 + +- **内置用户管理**:用户账号和权限存储在 Metasrv 中,确保整个集群中的 + 管理保持一致。 +- **基于角色的访问控制 (RBAC)**:为用户分配全局权限,控制 `SELECT`、 + `INSERT`、`CREATE TABLE` 等操作。 +- **细粒度 ACL**:使用精确匹配或正则表达式控制特定数据库内的表级访问。 +- **动态管理**:通过 HTTP API 动态管理用户,无需重启服务器。 +- **初始账号导入**:支持在启动时从密码文件导入初始账号。 + +## 配置说明 + +本节介绍如何启用企业版用户 Provider 并执行基础的用户管理操作。 + +### 1. 启用用户 Provider + +要使用企业版用户与权限系统,需要在接收客户端请求的组件中启用 +`greptime_ee_user_provider`。在单机模式中,请在 standalone server 上配置; +在集群模式中,请在每个 frontend 节点上配置。 + +用户 Provider 的取值如下: + +```text +greptime_ee_user_provider: +``` + +密码文件是可选的,仅用于初始账号导入。若要在不导入用户的情况下启用 +Provider,请使用 `greptime_ee_user_provider:`。配置解析器要求保留末尾的 +冒号 `:`。 + +**Standalone 命令行:** + +```shell +./greptime standalone start \ + --user-provider=greptime_ee_user_provider:/path/to/passwords.txt +``` + +**Standalone 配置文件:** + +```toml +user_provider = "greptime_ee_user_provider:/path/to/passwords.txt" +``` + +```shell +./greptime standalone start \ + -c /path/to/standalone.toml +``` + +**Frontend 命令行:** + +```shell +./greptime frontend start \ + --metasrv-addrs=127.0.0.1:3002 \ + --user-provider=greptime_ee_user_provider:/path/to/passwords.txt +``` + +**Frontend 配置文件:** + +```toml +user_provider = "greptime_ee_user_provider:/path/to/passwords.txt" + +[meta_client] +metasrv_addrs = ["127.0.0.1:3002"] +``` + +然后使用配置文件启动 frontend: + +```shell +./greptime frontend start \ + -c /path/to/frontend.toml +``` + +### 2. 初始账号导入(可选) + +密码文件使用以下格式: +`[:]=` + +可用角色: + +- `admin`:拥有完整权限,包括用户管理权限。 +- `readonly`(或 `ro`):只读访问权限 (`SqlSelect`)。 +- `writeonly`(或 `wo`):只写访问权限,例如 `SqlInsert`、`TableCreate`。 +- `readwrite`(或 `rw`):同时拥有读写访问权限(默认)。 + +`passwords.txt` 示例: + +```text +# username[:role]=password +superuser:admin=strong_password +alice:ro=alice_pwd +bob:rw=bob_pwd +``` + +默认情况下,导入的用户会获得 `public` 数据库的完整访问权限 +(`AclType::All`)。 + +导入的账号只会创建一次。如果后续启动时发现某个导入用户已经存在,则会跳过 +该用户。之后你可以通过 UI 修改这些导入的用户。 + +## 权限与 ACL + +### 全局权限 + +权限包括以下操作: + +| 权限 | 描述 | +| :--- | :--- | +| `TableCreate` | 创建新表 | +| `TableAlter` | 修改已有表 | +| `TableDrop` | 删除表 | +| `SqlSelect` | 执行 `SELECT` 查询 | +| `SqlInsert` | 执行 `INSERT` 操作 | +| `SqlDelete` | 执行 `DELETE` 操作 | +| `FlowCreate` | 创建 flow | +| `FlowDrop` | 删除 flow | +| `DatabaseCreate` | 创建数据库 | +| `DatabaseAlter` | 修改数据库 | +| `DatabaseDrop` | 删除数据库 | +| `Admin` | 完整管理权限 | +| `TriggerCreate` | 创建触发器 | +| `TriggerDrop` | 删除触发器 | +| `TriggerAlter` | 修改触发器 | + +#### 预定义角色权限 + +使用密码文件导入账号时,预定义角色会映射到以下权限组合: + +| 角色 | 权限 | +| :--- | :--- | +| `admin` | 所有权限 | +| `readonly` / `ro` | `SqlSelect` | +| `writeonly` / `wo` | `SqlInsert`, `SqlDelete`, `TableCreate`, `TableAlter`, `TableDrop`, `FlowCreate`, `FlowDrop`, `TriggerCreate`, `TriggerDrop`, `TriggerAlter`, `DatabaseCreate`, `DatabaseAlter`, `DatabaseDrop` | +| `readwrite` / `rw` | `readonly` + `writeonly` 权限 | + +### 访问控制列表 (ACL) + +ACL 在数据库内提供表级安全控制。每条 ACL 都限定在某个数据库中,并控制 +用户可以访问该数据库中的哪些表。 + +`all` ACL 授予对该数据库中所有表的访问权限。当用户需要读取或写入该 +数据库中当前和未来的所有表时,可以使用该 ACL;实际访问能力仍受用户全局 +权限的约束。 + +`match` ACL 通过精确表名授予对单个表的访问权限。当用户只应访问某个特定表, +且不应自动获得对其他相似表名的访问权限时,可以使用该 ACL。 + +`regex` ACL 授予对表名匹配正则表达式的表的访问权限。当表名遵循某种命名规则、 +需要按组管理时,可以使用该 ACL。例如,`mem_.*` 匹配以 `mem_` 开头的表名, +`.*_metrics` 匹配以 `_metrics` 结尾的表名,`sensor_[0-9]+` 匹配 +`sensor_1`、`sensor_2024` 等表名。Regex ACL 会在配置的数据库内对表名 +进行匹配,因此请尽量使用明确的模式,避免授予超出预期的表访问权限。 + +## 校验规则 + +### 用户名 + +用户名必须: + +- 以字母开头(`a-z` 或 `A-Z`) +- 仅包含字母、数字和下划线 +- 匹配 `[a-zA-Z][a-zA-Z0-9_]*` 模式 + +### 密码 + +密码校验规则取决于用户的创建或更新方式: + +- 导入账号的密码不能为空。 +- 通过 UI 创建或更新的密码长度必须为 6 到 64 个字符。 + +## Enterprise Dashboard 中的用户管理 + +启用 `greptime_ee_user_provider` 后,GreptimeDB 和 Enterprise Dashboard 都要求 +用户使用账号登录。下图展示了 Enterprise Dashboard 的登录页面: + +

+ login page +

+ +你可以使用自动创建的 admin 账号,或使用导入文件中定义的账号登录。 + +只有拥有 `Admin` 权限的账号才能看到数据库管理菜单。非 admin 账号只能访问 +查询页面,体验与开源版 dashboard 类似。 + +以 admin 用户登录后,点击左下角的 `User Management`,即可进入用户管理页面: + +

+ login page +

+ +该页面会列出所有当前用户。你可以在此页面执行以下操作: + +1. 创建用户 +2. 更新已有用户 +3. 删除用户 + +下图展示了创建用户的表单: + +

+ login page +

+ +在该表单中,你可以配置: + +1. 用户名 +2. 密码 +3. 账号是否拥有 `Admin` 权限。非 admin 用户会被授予 `readwrite` 权限。 +4. 账号的 ACL 列表 + +ACL 表单包含两个页签。你可以选择精确的表,也可以选择整个数据库来授予 +全库访问权限,或者使用正则表达式为一组表授予访问权限。下图展示了正则表达式 +表单: + +

+ login page +

+ +## 参考 + +- **管理员账号**:系统首次启动时,如果默认 `admin` 账号尚不存在, + GreptimeDB 企业版会自动创建该账号。 + - 如果设置了环境变量 `GREPTIME_ENTERPRISE_ADMIN_PASSWORD`,则使用该变量的 + 值作为密码。 + - 如果未设置该环境变量,则生成一个随机 UUID 作为密码。 +- **查看自动生成的密码**:如果生成了随机密码,你可以在 GreptimeDB 日志文件中 + 找到它。搜索类似如下的消息: + ```text + Created admin user with auto-generated password + ``` +- **持久化**:用户信息会持久化在 Metasrv 的 KV 存储中,因此集群中的所有 + frontend 节点都可以访问这些用户信息。 +- **Admin 保护**:内置的 `admin` 用户不能通过 API 删除。 diff --git a/static/ent_user/create.png b/static/ent_user/create.png new file mode 100644 index 000000000..cd83b2fec Binary files /dev/null and b/static/ent_user/create.png differ diff --git a/static/ent_user/list.png b/static/ent_user/list.png new file mode 100644 index 000000000..6354c12df Binary files /dev/null and b/static/ent_user/list.png differ diff --git a/static/ent_user/login.jpeg b/static/ent_user/login.jpeg new file mode 100644 index 000000000..a62f02de4 Binary files /dev/null and b/static/ent_user/login.jpeg differ diff --git a/static/ent_user/regex.png b/static/ent_user/regex.png new file mode 100644 index 000000000..655d425c4 Binary files /dev/null and b/static/ent_user/regex.png differ