diff --git a/src/.vuepress/sidebar/V2.0.x/en-Table.ts b/src/.vuepress/sidebar/V2.0.x/en-Table.ts index 58260b933..73d3d5fab 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts @@ -111,7 +111,8 @@ export const enSidebar = { text: 'Security Management', collapsible: true, children: [ - { text: 'Authority Management', link: 'Authority-Management_apache' }, + { text: 'Authority Management(Before V2.0.7)', link: 'Authority-Management_apache' }, + { text: 'Authority Management(From V2.0.7)', link: 'Authority-Management-Upgrade_apache' }, ], }, { text: 'Tree-to-Table Mapping', link: 'Tree-to-Table_apache' }, diff --git a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts index ba34cf971..e3d94ceb2 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts @@ -129,7 +129,10 @@ export const enSidebar = { { text: 'Security Management', collapsible: true, - children: [{ text: 'Permission Management', link: 'Authority-Management_apache' }], + children: [ + { text: 'Authority Management(Before V2.0.7)', link: 'Authority-Management_apache' }, + { text: 'Authority Management(From V2.0.7)', link: 'Authority-Management-Upgrade_apache' }, + ], }, { text: 'System Maintenance', diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts index f6285661c..71754c6ac 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts @@ -110,7 +110,10 @@ export const zhSidebar = { { text: '安全管理', collapsible: true, - children: [{ text: '权限管理', link: 'Authority-Management_apache' }], + children: [ + { text: '权限管理(V2.0.7 之前)', link: 'Authority-Management_apache' }, + { text: '权限管理(V2.0.7 起)', link: 'Authority-Management-Upgrade_apache' }, + ], }, { text: '树转表视图', link: 'Tree-to-Table_apache' }, { diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts index ac57f0941..7d8631c8c 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts @@ -120,7 +120,10 @@ export const zhSidebar = { { text: '安全管理', collapsible: true, - children: [{ text: '权限管理', link: 'Authority-Management_apache' }], + children: [ + { text: '权限管理(V2.0.7 之前)', link: 'Authority-Management_apache' }, + { text: '权限管理(V2.0.7 起)', link: 'Authority-Management-Upgrade_apache' }, + ], }, { text: '系统运维', diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts index 047778cac..ca6fee778 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts @@ -138,7 +138,8 @@ export const enSidebar = { text: 'Security Management', collapsible: true, children: [ - { text: 'Authority Management', link: 'Authority-Management_timecho' }, + { text: 'Authority Management(Before V2.0.7)', link: 'Authority-Management_timecho' }, + { text: 'Authority Management(From V2.0.7)', link: 'Authority-Management-Upgrade_timecho' }, { text: 'Black White List', link: 'Black-White-List_timecho' }, { text: 'Security Audit', link: 'Audit-Log_timecho' }, ], diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts index 29954ec26..8ed927fc1 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts @@ -150,7 +150,8 @@ export const enSidebar = { text: 'Security Management', collapsible: true, children: [ - { text: 'Permission Management', link: 'Authority-Management_timecho' }, + { text: 'Authority Management(Before V2.0.7)', link: 'Authority-Management_timecho' }, + { text: 'Authority Management(From V2.0.7)', link: 'Authority-Management-Upgrade_timecho' }, { text: 'Black White List', link: 'Black-White-List_timecho' }, { text: 'Security Audit', link: 'Audit-Log_timecho' }, ], diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts index 8ce05c6f6..275c52420 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts @@ -129,7 +129,8 @@ export const zhSidebar = { text: '安全管理', collapsible: true, children: [ - { text: '权限管理', link: 'Authority-Management_timecho' }, + { text: '权限管理(V2.0.7 之前)', link: 'Authority-Management_timecho' }, + { text: '权限管理(V2.0.7 起)', link: 'Authority-Management-Upgrade_timecho' }, { text: '黑白名单', link: 'Black-White-List_timecho' }, { text: '安全审计', link: 'Audit-Log_timecho' }, ], diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts index 3ca1d9241..05a1ce72c 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts @@ -132,7 +132,8 @@ export const zhSidebar = { text: '安全管理', collapsible: true, children: [ - { text: '权限管理', link: 'Authority-Management_timecho' }, + { text: '权限管理(V2.0.7 之前)', link: 'Authority-Management_timecho' }, + { text: '权限管理(V2.0.7 起)', link: 'Authority-Management-Upgrade_timecho' }, { text: '黑白名单', link: 'Black-White-List_timecho' }, { text: '安全审计', link: 'Audit-Log_timecho' }, ], diff --git a/src/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_apache.md b/src/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..c46333788 --- /dev/null +++ b/src/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,492 @@ + +# Authority Management + +IoTDB provides permission management capabilities to implement fine-grained access control for data and cluster systems, ensuring data and system security. This article introduces the core concepts of the permission module under the IoTDB Table Model, user specifications, permission governance, authentication logic, and practical use cases. + +## 1. Core Concepts +### 1.1 User +A user refers to a legitimate database operator. Each user corresponds to a unique username and is authenticated by a password. To use the database, users must provide valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a wide range of operations, but not all users are authorized to perform every action. A user is considered to have the corresponding privilege if permitted to execute a specific operation. + +### 1.3 Role +A role is a collection of privileges identified by a unique role name. Roles correspond to actual job identities (e.g., traffic dispatchers), and multiple users may share the same identity. Users with identical job roles usually require consistent permissions. Roles serve as an abstraction for unified permission management among user groups. + +### 1.4 Default Users and Roles +After initialization, IoTDB provides one default user named `root` with the default password `root`. As the administrator account, root owns all privileges permanently. Its permissions cannot be granted, revoked, or deleted, and it is the sole administrator user in the database. +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege can create users and roles, subject to the following constraints: + +### 2.1 Username Rules +- Usernames must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of usernames identical to the administrator account is prohibited. +- If a username consists entirely of digits or contains special characters, it must be enclosed in double quotation marks `""` during creation. + +### 2.2 Password Rules +Passwords must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). A password cannot be the same as the associated username. + +### 2.3 Role Name Rules +Role names must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of role names identical to the administrator account is prohibited. + +## 3. Permission Management +Under the IoTDB Table Model, permissions are divided into two major categories: global privileges and data privileges. + +### 3.1 Global Privileges +Global privileges include two types: `SYSTEM` and `SECURITY`: +- **SYSTEM**: Governs O&M operations and Data Definition Language (DDL) related privileges. +- **SECURITY**: Governs the management of users and roles, as well as privilege granting for other accounts. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege CategoryOriginal Privilege NameDescription
SYSTEMN/AAllows users to create, alter and drop databases.
N/AAllows users to create, alter and drop tables and table views.
N/AAllows users to create, drop and query user-defined functions.
N/AAllows users to create, start, stop, drop and query PIPE tasks; allows users to create, drop and query PIPEPLUGINS.
N/AAllows users to execute and cancel queries, view system variables, and check cluster status.
N/AAllows users to create, drop and query deep learning models.
SECURITYMANAGE_USERAllows users to create and drop users, modify user passwords, view user privilege information, and list all users.
MANAGE_ROLEAllows users to create and drop roles, view role privilege information, grant roles to users, revoke roles from users, and list all roles.
+ +### 3.2 Data Privileges +Data privileges consist of privilege types and effective scopes. + +- **Privilege Types**: `CREATE`, `DROP`, `ALTER`, `SELECT`, `INSERT`, `DELETE`. +- **Scopes**: `ANY` (system-wide), `DATABASE` (database-level), `TABLE` (single table). + - Privileges with the `ANY` scope apply to all databases and tables. + - Database-level privileges apply to the specified database and all tables within it. + - Table-level privileges only take effect on the designated single table. +- **Scope Matching Rules**: When executing single-table operations, the system matches user privileges by scope level. For example, when writing data to `DATABASE1.TABLE1`, the system checks write permissions in sequence for `ANY`, `DATABASE1`, and `DATABASE1.TABLE1` until a matching privilege is found or the check fails. + +The logical relationship between privilege types, scopes and capabilities is shown below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege TypeScope LevelCapability Description
CREATEANYAllows creating any databases and tables.
DatabaseAllows creating databases with the specified name and creating tables under the target database.
TableAllows creating the specified table.
DROPANYAllows dropping any databases and tables.
DatabaseAllows dropping the specified database and all tables under it.
TableAllows dropping the specified table.
ALTERANYAllows modifying the definitions of any databases and tables.
DatabaseAllows modifying database definitions and the definitions of all tables under the target database.
TableAllows modifying the structure and definition of the specified table.
SELECTANYAllows querying data from all tables across all databases in the system.
DatabaseAllows querying data from all tables under the specified database.
TableAllows querying data of the specified table. For multi-table queries, only accessible data with valid permissions will be displayed.
INSERTANYAllows inserting and updating data in any tables of all databases.
DatabaseAllows inserting and updating data in all tables under the specified database.
TableAllows inserting and updating data in the specified table.
DELETEANYAllows deleting data from any tables.
DatabaseAllows deleting data within the specified database scope.
TableAllows deleting data from the specified table.
+ +### 3.3 Privilege Granting and Revocation +In IoTDB, user privileges can be granted or revoked through three methods: +1. Direct granting or revocation by the super administrator. +2. Granting or revocation by common users with the `GRANT OPTION` privilege. +3. Granting or revocation via role assignment, operated by the super administrator or users with `SECURITY` privileges. + +The following rules apply to privilege management under the IoTDB Table Model: +- No scope needs to be specified when granting or revoking global privileges. +- Data privilege operations require explicit privilege types and scopes. Revocation only takes effect on the specified scope and is not affected by hierarchical inclusion relationships. +- Pre-authorization is supported for databases and tables that have not yet been created. +- Repeated granting or revocation of privileges is allowed. +- **WITH GRANT OPTION**: Grants users the permission to manage privileges within their authorized scope, including granting and revoking corresponding permissions for other users. + +## 4. Syntax and Usage Examples +### 4.1 User and Role Management +1. **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +-- Example +CREATE USER user1 'passwd' +``` + +2. **Modify Password** + Users can update their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD +-- Example +ALTER USER tempuser SET PASSWORD 'newpwd' +``` + +3. **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +-- Example +DROP USER user1 +``` + +4. **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +-- Example +CREATE ROLE role1 +``` + +5. **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +-- Example +DROP ROLE role1 +``` + +6. **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +-- Example +GRANT ROLE admin TO user1 +``` + +7. **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +-- Example +REVOKE ROLE admin FROM user1 +``` + +8. **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +9. **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +10. **List Users Assigned to a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +-- Example +LIST USER OF ROLE roleuser +``` + +11. **List Roles of a Specified User** + Users can view their own roles; viewing other users' roles requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +-- Example +LIST ROLE OF USER tempuser +``` + +12. **List All Privileges of a User** + Users can view their own privileges; viewing other users' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER +-- Example +LIST PRIVILEGES OF USER tempuser +``` + +13. **List All Privileges of a Role** + Users can view privileges of their assigned roles; viewing other roles' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE +-- Example +LIST PRIVILEGES OF ROLE actor +``` + +### 4.2 Privilege Granting and Revocation +#### 4.2.1 Grant Privileges +1. Grant user management privileges to a user +```SQL +GRANT SECURITY TO USER +-- Example +GRANT SECURITY TO USER TEST_USER +``` + +2. Grant database and table creation privileges with permission management rights +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +-- Example +GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION +``` + +3. Grant database query privileges to a role +```SQL +GRANT SELECT ON DATABASE TO ROLE +-- Example +GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE +``` + +4. Grant table query privileges to a user +```SQL +GRANT SELECT ON . TO USER +-- Example +GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER +``` + +5. Grant global query privileges to a role +```SQL +GRANT SELECT ON ANY TO ROLE +-- Example +GRANT SELECT ON ANY TO ROLE TEST_ROLE +``` + +6. **ALL Syntax Sugar**: `ALL` represents all privileges within the target scope +```SQL +-- Grant all global privileges and full data privileges under ANY scope +GRANT ALL TO USER TESTUSER + +-- Grant all data privileges under ANY scope +GRANT ALL ON ANY TO USER TESTUSER + +-- Grant all data privileges under the specified database +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER + +-- Grant all data privileges under the specified table +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER +``` + +#### 4.2.2 Revoke Privileges +1. Revoke user management privileges +```SQL +REVOKE SECURITY FROM USER +-- Example +REVOKE SECURITY FROM USER TEST_USER +``` + +2. Revoke database and table creation privileges +```SQL +REVOKE CREATE ON DATABASE FROM USER +-- Example +REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER +``` + +3. Revoke table query privileges +```SQL +REVOKE SELECT ON . FROM USER +-- Example +REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER +``` + +4. Revoke global query privileges +```SQL +REVOKE SELECT ON ANY FROM USER +-- Example +REVOKE SELECT ON ANY FROM USER TEST_USER +``` + +5. **ALL Syntax Sugar** for revocation +```SQL +-- Revoke all global privileges and ANY-scoped data privileges +REVOKE ALL FROM USER TESTUSER + +-- Only revoke ANY-scoped data privileges +REVOKE ALL ON ANY FROM USER TESTUSER + +-- Only revoke all data privileges of the specified database +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER + +-- Only revoke all data privileges of the specified table +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER +``` + +### 4.3 View User Privileges +Each user has an independent privilege list recording all authorized permissions. Use the following statement to query privilege details: +```SQL +LIST PRIVILEGES OF USER +``` + +Output format: + +| ROLE | SCOPE | PRIVILEGE | WITH GRANT OPTION | +| ------- |---------|------------| ------------------- | +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | INSERT | TRUE | +| ROLE1 | DB3.* | DELETE | FALSE | +| ROLE1 | *.* | UPDATE | TRUE | + +- **ROLE Column**: Blank for self-owned user privileges; displays the role name if the privilege is inherited from a role. +- **SCOPE Column**: Table-level scope displayed as `DB.TABLE`, database-level scope as `DB.*`, and global ANY scope as `*.*`. +- **PRIVILEGE Column**: Lists specific authorized privilege types. +- **WITH GRANT OPTION Column**: `TRUE` means the user can regrant or revoke privileges within the corresponding scope. + +> Note: Users and roles can hold permissions for both the Tree Model and Table Model simultaneously. The system only displays permissions applicable to the currently connected model, while permissions for the other model are hidden. + +## 5. Practical Scenario Example +Based on the [Sample Data](../Reference/Sample-Data.md), data in different tables belongs to two independent data centers (bj and sh). To ensure data isolation, cross-center data access needs to be restricted through permission control. + +### 5.1 Create Users +Use the `CREATE USER` statement to create new users. For example, the root administrator creates two dedicated write users for the BJ and SH data centers: `bj_write_user` and `sh_write_user`, with a unified password `write_pwd`. + +```SQL +CREATE USER bj_write_user 'write_pwd'; +CREATE USER sh_write_user 'write_pwd'; +``` + +Execute the user query statement: +```SQL +LIST USER +``` + +Query result: +``` ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 Grant Privileges +Newly created users have no permissions by default and cannot perform database operations. For example, an insertion executed by `bj_write_user` will fail: +```SQL +INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +Error message after switching to the target database: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +Grant table write privileges to `bj_write_user` via the root account: +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +Retry data insertion after switching databases: +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Privileges +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +After revocation, the user loses corresponding write permissions and will receive a permission denied error when attempting to write data again: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` diff --git a/src/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_timecho.md b/src/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..5056f75bc --- /dev/null +++ b/src/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,495 @@ + +# Authority Management + +IoTDB provides permission management capabilities to deliver fine-grained access control for data and cluster systems, ensuring data and system security. This document introduces the basic concepts of the permission module under the IoTDB Table Model, user specifications, permission governance, authentication logic, and practical application examples. + +## 1. Basic Concepts +### 1.1 User +A user is a legitimate database operator. Each user is identified by a unique username and authenticated with a password. To use the database, users must provide valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a variety of operations, but not all users are authorized to perform every action. A user is considered to have the corresponding privilege if permitted to execute a specific operation. + +### 1.3 Role +A role is a collection of privileges marked by a unique role identifier. Roles correspond to real-world job identities (e.g., traffic dispatchers), and one identity may cover multiple users. Users with identical job identities usually share the same set of permissions. Roles serve as an abstraction to realize unified permission management for such user groups. + +### 1.4 Default Users and Roles +After initialization, IoTDB provides a default user `root` with the default password `TimechoDB@2021`. As the administrator account, root owns all privileges by default. Its permissions cannot be granted or revoked, and the account cannot be deleted. There is only one administrator user in the database. +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege can create users and roles, and all creations must comply with the following constraints: + +### 2.1 Username Rules +- Length: 4 to 32 characters. Supports uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Usernames identical to the administrator account are not allowed. +- If a username consists entirely of digits or contains special characters, it must be enclosed in double quotation marks `""` during creation. + +### 2.2 Password Rules +Length: 12 to 32 characters. A valid password must contain both uppercase and lowercase letters, at least one digit, and at least one special symbol (`!@#$%^&*()_+-=`). A password cannot be the same as the associated username. + +### 2.3 Role Name Rules +Length: 4 to 32 characters. Supports uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Role names identical to the administrator account are prohibited. + +## 3. Permission Management +Under the IoTDB Table Model, permissions are divided into two major categories: global privileges and data privileges. + +### 3.1 Global Privileges +Global privileges include three types: `SYSTEM`, `SECURITY`, and `AUDIT`: +- **SYSTEM**: Covers privileges for O&M operations and Data Definition Language (DDL) tasks. +- **SECURITY**: Covers management of users and roles, as well as privilege assignment for other accounts. +- **AUDIT**: Covers audit rule maintenance and audit log viewing. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege CategoryOriginal NameDescription
SYSTEMN/AAllows users to create, alter and drop databases.
N/AAllows users to create, alter and drop tables and table views.
N/AAllows users to create, drop and query user-defined functions.
N/AAllows users to create, start, stop, drop and view PIPE tasks; create, drop and view PIPEPLUGINS.
N/AAllows users to execute and cancel queries, view system variables, and check cluster status.
N/AAllows users to create, drop and query deep learning models.
SECURITYMANAGE_USERAllows users to create and drop users, modify user passwords, view user privilege information, and list all users.
MANAGE_ROLEAllows users to create and drop roles, view role privilege information, grant roles to users, revoke roles from users, and list all roles.
AUDITN/AAllows users to maintain audit log rules and view audit logs.
+ +### 3.2 Data Privileges +Data privileges consist of privilege types and effective scopes. + +- **Privilege Types**: `CREATE`, `DROP`, `ALTER`, `SELECT`, `INSERT`, `DELETE`. +- **Scopes**: `ANY` (system-wide), `DATABASE` (database-level), `TABLE` (single table). + - Privileges with the `ANY` scope apply to all databases and tables. + - Database-level privileges apply to the specified database and all tables under it. + - Table-level privileges only take effect on the target single table. +- **Scope Matching Logic**: When performing single-table operations, the system verifies permissions by scope priority. For example, when writing data to `DATABASE1.TABLE1`, the system checks write permissions in sequence for `ANY`, `DATABASE1` and `DATABASE1.TABLE1` until a matching privilege is found or the check fails. + +The logical relationship between privilege types, scopes and capabilities is shown below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege TypePermission Scope (Level)Capability Description
CREATEANYAllows creating any databases and tables.
DatabaseAllows creating the specified database and creating tables under this database.
TableAllows creating the specified table.
DROPANYAllows dropping any databases and tables.
DatabaseAllows dropping the specified database and all tables under it.
TableAllows dropping the specified table.
ALTERANYAllows modifying the definitions of any databases and tables.
DatabaseAllows modifying database definitions and the structure of all tables under the database.
TableAllows modifying the table structure and definition.
SELECTANYAllows querying data from any table across all databases.
DatabaseAllows querying data from all tables in the specified database.
TableAllows querying data in the specified table. For multi-table queries, only accessible data with valid permissions will be displayed.
INSERTANYAllows inserting and updating data in any tables of all databases.
DatabaseAllows inserting and updating data in all tables under the specified database.
TableAllows inserting and updating data in the specified table.
DELETEANYAllows deleting data from any tables.
DatabaseAllows deleting data within the specified database.
TableAllows deleting data in the specified table.
+ +### 3.3 Privilege Granting and Revocation +IoTDB supports privilege assignment and revocation through three methods: +- Direct granting or revocation by the super administrator. +- Granting or revocation by users with the `GRANT OPTION` privilege. +- Granting or revocation via role configuration, operated by the super administrator or users with `SECURITY` privileges. + +The following rules apply to permission management in the IoTDB Table Model: +- No scope needs to be specified when granting or revoking global privileges. +- Data privilege operations require explicit privilege types and scopes. Revocation only takes effect on the designated scope and is not affected by hierarchical inclusion relationships. +- Pre-authorization is supported for databases and tables that have not been created yet. +- Repeated granting or revocation of privileges is permitted. +- **WITH GRANT OPTION**: Authorizes users to manage permissions within their granted scope, including granting and revoking privileges for other users. + +## 4. Syntax and Usage Examples +### 4.1 User and Role Management +1. **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +-- Example +CREATE USER user1 'Passwd@202604' +``` + +2. **Modify Password** + Users can change their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD +-- Example +ALTER USER tempuser SET PASSWORD 'Newpwd@202604' +``` + +3. **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +-- Example +DROP USER user1 +``` + +4. **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +-- Example +CREATE ROLE role1 +``` + +5. **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +-- Example +DROP ROLE role1 +``` + +6. **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +-- Example +GRANT ROLE admin TO user1 +``` + +7. **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +-- Example +REVOKE ROLE admin FROM user1 +``` + +8. **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +9. **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +10. **List Users Under a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +-- Example +LIST USER OF ROLE roleuser +``` + +11. **List Roles of a Specified User** + Users can view their own roles; viewing roles of other users requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +-- Example +LIST ROLE OF USER tempuser +``` + +12. **List All Privileges of a User** + Users can view their own privileges; viewing privileges of other users requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER +-- Example +LIST PRIVILEGES OF USER tempuser +``` + +13. **List All Privileges of a Role** + Users can view privileges of their bound roles; viewing privileges of other roles requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE +-- Example +LIST PRIVILEGES OF ROLE actor +``` + +### 4.2 Granting and Revoking Privileges +#### 4.2.1 Grant Privileges +1. Grant user management privileges to a user +```SQL +GRANT SECURITY TO USER +-- Example +GRANT SECURITY TO USER TEST_USER +``` + +2. Grant database and table creation privileges with independent permission management rights +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +-- Example +GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION +``` + +3. Grant database query privileges to a role +```SQL +GRANT SELECT ON DATABASE TO ROLE +-- Example +GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE +``` + +4. Grant table query privileges to a user +```SQL +GRANT SELECT ON . TO USER +-- Example +GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER +``` + +5. Grant global cross-database query privileges to a role +```SQL +GRANT SELECT ON ANY TO ROLE +-- Example +GRANT SELECT ON ANY TO ROLE TEST_ROLE +``` + +6. **ALL Syntax Sugar**: `ALL` represents all available privileges within the target scope +```SQL +-- Grant all global privileges and full data privileges under the ANY scope +GRANT ALL TO USER TESTUSER + +-- Grant all data privileges covering the entire system scope +GRANT ALL ON ANY TO USER TESTUSER + +-- Grant all data privileges for the specified database +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER + +-- Grant all data privileges for the specified single table +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER +``` + +#### 4.2.2 Revoke Privileges +1. Revoke user management privileges +```SQL +REVOKE SECURITY FROM USER +-- Example +REVOKE SECURITY FROM USER TEST_USER +``` + +2. Revoke database and table creation privileges +```SQL +REVOKE CREATE ON DATABASE FROM USER +-- Example +REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER +``` + +3. Revoke table query privileges +```SQL +REVOKE SELECT ON . FROM USER +-- Example +REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER +``` + +4. Revoke global cross-database query privileges +```SQL +REVOKE SELECT ON ANY FROM USER +-- Example +REVOKE SELECT ON ANY FROM USER TEST_USER +``` + +5. **ALL Syntax Sugar** for privilege revocation +```SQL +-- Revoke all global privileges and ANY-scoped data privileges +REVOKE ALL FROM USER TESTUSER + +-- Only revoke data privileges under the ANY scope +REVOKE ALL ON ANY FROM USER TESTUSER + +-- Only revoke all data privileges of the specified database +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER + +-- Only revoke all data privileges of the specified table +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER +``` + +### 4.3 View User Privileges +Each user has an independent privilege list that records all authorized permissions. +Use `LIST PRIVILEGES OF USER ` to query detailed privileges of a user or role. The output format is as follows: + +| ROLE | SCOPE | PRIVILEGE | WITH GRANT OPTION | +|-------|---------|-----------|------------------| +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | UPDATE | TRUE | +| ROLE1 | DB3.* | DELETE | FALSE | +| ROLE1 | *.* | UPDATE | TRUE | + +- **ROLE**: Blank for self-owned user privileges; displays the role name if the permission is inherited from a role. +- **SCOPE**: Table-level scope displayed as `DB.TABLE`, database-level as `DB.*`, and global ANY scope as `*.*`. +- **PRIVILEGE**: Lists specific authorized permission types. +- **WITH GRANT OPTION**: `TRUE` means the user can grant or revoke permissions within the corresponding scope. +- Users and roles can hold permissions for both the Tree Model and Table Model simultaneously. The system only displays permissions applicable to the currently connected model, while permissions for the other model will be hidden. + +## 5. Practical Scenario Example +Based on the [Sample Data](../Reference/Sample-Data.md), data in different tables belongs to two independent data centers (bj and sh). To prevent unauthorized cross-center data access, permission isolation needs to be configured at the data center level. + +### 5.1 Create Users +Use `CREATE USER` to create new users. For example, the root administrator creates two dedicated write users for the BJ and SH data centers: `bj_write_user` and `sh_write_user`, with a unified password `write_Pwd@2026`. + +```SQL +CREATE USER bj_write_user 'write_Pwd@2026'; +CREATE USER sh_write_user 'write_Pwd@2026'; +``` + +Execute the user query statement: +```SQL +LIST USER +``` + +Query result: +``` ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 Grant Privileges +Newly created users have no permissions by default and cannot perform database operations. For example, an insertion executed by `bj_write_user` will fail: +```SQL +INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +Error prompt: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: database is not specified +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +Grant table write privileges to `bj_write_user` via the root account: +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +Retry data insertion after switching to the target database: +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Privileges +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +After revocation, `bj_write_user` no longer has write access to table1: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` + \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_apache.md b/src/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..13993753b --- /dev/null +++ b/src/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,426 @@ + +# Authority Management + +IoTDB provides permission management capabilities for users to control access to data and cluster systems, ensuring data and system security. This article introduces the core concepts of the permission module in IoTDB, user definitions, permission governance, authentication logic, and practical use cases. + +## 1. Core Concepts +### 1.1 User +A user refers to a legitimate database operator. Each user corresponds to a unique username and is authenticated via a password. Before accessing the database, users must log in with valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a wide range of operations, but not all users are authorized to perform every action. A user is considered privileged for an operation if they are permitted to execute it. Each privilege is bounded by a specific path, and path patterns ([Path Pattern](../Basic-Concept/Operate-Metadata_apache.md)) enable flexible permission management. + +### 1.3 Role +A role is a collection of privileges identified by a unique role name. Roles correspond to actual job identities (e.g., traffic dispatchers), and multiple users may share the same identity and identical permission sets. Roles enable unified batch management of permissions for user groups with identical access requirements. + +### 1.4 Default Users and Roles +After initialization, IoTDB contains one default user: `root` with the default password `root`. As the built-in administrator account, the root user owns all permissions permanently. Its permissions cannot be granted, revoked, or deleted, and it is the sole administrator account in the database. + +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege are allowed to create users and roles, subject to the following constraints: + +### 2.1 Username Rules +Usernames must be 4 to 32 characters long, supporting uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of duplicate usernames matching the administrator account is prohibited. + +### 2.2 Password Rules +Passwords must be 4 to 32 characters long, supporting uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Passwords cannot be identical to the associated username. + +### 2.3 Role Name Rules +Role names must be 4 to 32 characters long, supporting uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of duplicate role names matching the administrator account is prohibited. + +## 3. Permission Governance +Based on its tree data model, IoTDB classifies permissions into two major categories: global privileges and series privileges. + +### 3.1 Global Privileges +Global privileges include two types: `SYSTEM` and `SECURITY`: +- **SYSTEM**: Governs O&M operations and Data Definition Language (DDL) actions. +- **SECURITY**: Governs user/role management and privilege granting for other accounts. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege NameOriginal Privilege NameDescription
SYSTEMMANAGE_DATABASEAllows creation and deletion of databases.
USE_TRIGGERAllows creation, deletion and query of triggers.
USE_UDFAllows creation, deletion and query of user-defined functions.
USE_PIPEAllows creation, startup, stop, deletion and query of PIPE tasks; allows creation, deletion and query of PIPEPLUGINS.
USE_CQAllows registration, startup, stop, uninstallation and query of stream processing tasks; allows registration, uninstallation and query of stream processing plugins.
EXTEND_TEMPLATEAllows automatic template extension.
MAINTAINAllows query execution and cancellation, system variable viewing, and cluster status inspection.
USE_MODELAllows creation, deletion and query of deep learning models.
SECURITYMANAGE_USERAllows creation, deletion, modification and query of users.
MANAGE_ROLEAllows creation, deletion and query of roles; grants and revokes roles for other users.
+ +#### Template-Related Permission Rules +1. Template creation, deletion, modification, query, mounting and unmounting are restricted to the administrator only. +2. Template activation requires the `WRITE_SCHEMA` privilege for the target activation path. +3. When auto-creation is enabled, writing data to non-existent paths with mounted templates requires both the `EXTEND_TEMPLATE` privilege and the `WRITE_DATA` privilege for target time series. +4. Template unmounting requires the `WRITE_SCHEMA` privilege for the template mounting path. +5. Querying paths bound to metadata templates requires the `READ_SCHEMA` privilege for the target path; empty results will be returned without sufficient permissions. + +### 3.2 Series Privileges +Series privileges control the scope and mode of user data access, supporting authorization for absolute paths and prefix-matched paths at the time series granularity. + +Definitions of all series privileges are listed below: + +| Privilege Name | Description | +| --------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ_DATA | Allows reading time series data under authorized paths. | +| WRITE_DATA | Permits reading time series data under authorized paths;
Allows insertion and deletion of time series data;
Supports data import and loading. Data import requires the `WRITE_DATA` privilege for target paths; automatic database and time series creation additionally requires `SYSTEM` and `WRITE_SCHEMA` privileges. | +| READ_SCHEMA | Allows viewing detailed metadata tree information under authorized paths, including databases, sub-paths, nodes, devices, time series, templates and views. | +| WRITE_SCHEMA | Permits viewing metadata tree information under authorized paths;
Enables creation, deletion and modification of time series, templates and views;
View creation and modification require `WRITE_SCHEMA` for the view path and `READ_SCHEMA` for data sources; view read/write operations require `READ_DATA` and `WRITE_DATA` for the view path;
Supports TTL configuration, cancellation and query;
Allows template mounting and unmounting. | + +### 3.3 Privilege Granting and Revocation +Users can obtain permissions through three methods: +1. Grants issued by the super administrator (root). +2. Grants issued by common users with the `grant option` for specific privileges. +3. Role assignment by the super administrator or users with the `SECURITY` privilege. + +Permissions can be revoked through three methods: +1. Revocation operations executed by the super administrator. +2. Revocation operations executed by common users with the `grant option` for specific privileges. +3. Role revocation performed by the super administrator or users with the `SECURITY` privilege. + +- A valid path must be specified for all authorization operations. Global privileges require the path `root.**`, while series privileges require absolute paths or prefix paths ending with double wildcards. +- The `WITH GRANT OPTION` keyword can be appended during role authorization, enabling grantees to regrant or revoke the same privileges within the authorized path scope. For example, if User A is granted read access to `Group1.Company1.**` with the grant option, User A can authorize or revoke read permissions for all sub-nodes under `Group1.Company1`. +- Revocation statements perform full matching against existing user permission paths. For instance, revoking read access for `Group1.Company1.**` will clear all granular read permissions for sub-paths such as `Group1.Company1.Factory1`. + +## 4. Syntax and Usage Examples +IoTDB provides combined privilege aliases to simplify authorization configuration: + +| Combined Privilege | Coverage | +| ---------- | ---------------------------- | +| ALL | All system and series privileges | +| READ | READ_SCHEMA, READ_DATA | +| WRITE | WRITE_SCHEMA, WRITE_DATA | + +Combined privileges are simplified aliases and function identically to declaring individual privileges separately. + +The following examples demonstrate common permission management SQL statements. Non-administrator users require corresponding prerequisites for executing these operations, which are marked in each scenario. + +### 4.1 User and Role Management +- **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +-- Example +CREATE USER user1 'passwd' +``` + +- **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +-- Example +DROP USER user1 +``` + +- **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +-- Example +CREATE ROLE role1 +``` + +- **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +-- Example +DROP ROLE role1 +``` + +- **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +-- Example +GRANT ROLE admin TO user1 +``` + +- **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +-- Example +REVOKE ROLE admin FROM user1 +``` + +- **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +- **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +- **List Users Assigned to a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +-- Example +LIST USER OF ROLE roleuser +``` + +- **List Roles of a Specified User** + Users can view their own roles; viewing other users' roles requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +-- Example +LIST ROLE OF USER tempuser +``` + +- **List All Privileges of a Specified User** + Users can view their own privileges; viewing other users' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER ; +-- Example +LIST PRIVILEGES OF USER tempuser; +``` + +- **List All Privileges of a Specified Role** + Users can view privileges of their assigned roles; viewing other roles' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE ; +-- Example +LIST PRIVILEGES OF ROLE actor; +``` + +- **Modify Password** + Users can update their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD ; +-- Example +ALTER USER tempuser SET PASSWORD 'newpwd'; +``` + +### 4.2 Privilege Granting and Revocation +#### Grant Syntax +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]; +-- Examples +GRANT READ ON root.** TO ROLE role1; +GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +#### Revoke Syntax +```SQL +REVOKE ON FROM ROLE/USER ; +-- Examples +REVOKE READ ON root.** FROM ROLE role1; +REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +REVOKE SECURITY ON root.** FROM USER user1; +REVOKE ALL ON root.** FROM USER user1; +``` + +- Non-administrator users must hold the target privileges with the `WITH GRANT OPTION` attribute for the specified paths to execute grant or revoke operations. +- For global privileges (or statements containing global privileges such as `ALL`), the path must be strictly set to `root.**`. + +**Valid Authorization Examples** +```SQL +GRANT SECURITY ON root.** TO USER user1; +GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; +GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; +REVOKE SECURITY ON root.** FROM USER user1; +REVOKE SECURITY ON root.** FROM ROLE role1; +REVOKE ALL ON root.** FROM ROLE role1; +``` + +**Invalid Authorization Examples** +```SQL +GRANT READ, SECURITY ON root.t1.** TO USER user1; +GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; +REVOKE ALL ON root.t1.t2 FROM USER user1; +REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; +``` + +- Valid path formats include absolute full paths and paths ending with double wildcards: + ```SQL + -- Valid Paths + root.** + root.t1.t2.** + root.t1.t2.t3 + ``` + + ```SQL + -- Invalid Paths + root.t1.* + root.t1.**.t2 + root.t1*.t2.t3 + ``` + +## 5. Practical Scenario Example +Based on [sample data](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt), IoTDB sample data belongs to multiple power generation groups such as ln and sgcc. To ensure data isolation, cross-group data access needs to be restricted via permission control. + +### 5.1 Create Users +Use the `CREATE USER` statement to create dedicated users. The root administrator creates two write users for the ln and sgcc groups with the unified password `write_pwd`: +```SQL +CREATE USER `ln_write_user` 'write_pwd'; +CREATE USER `sgcc_write_user` 'write_pwd'; +``` + +Execute the user listing statement to verify creation: +```SQL +LIST USER; +``` + +Execution result: +``` +IoTDB> CREATE USER `ln_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 Grant Permissions +Newly created users have no permissions by default. Attempting to write data directly will trigger a permission error: +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +Error message: +``` +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +Grant targeted write permissions to each user via the root account: +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +Execution result: +``` +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +Retry data writing with `ln_write_user`: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Permissions +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +``` + +Execution result: +``` +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user` +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user` +Msg: The statement is executed successfully. +``` + +After permission revocation, the user loses write access again: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true) +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. Authentication & Supplementary Instructions +### 6.1 Authentication Mechanism +Each user's permission set consists of three core elements: effective path range, privilege type, and the `with grant option` tag. + +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +All user permissions can be queried via `LIST PRIVILEGES OF USER `. + +During authentication, IoTDB matches the target operation path against the user's authorized paths in sequence. The check passes if a matching path and corresponding privilege are found; otherwise, the operation is rejected. + +- For multi-path query tasks, only data accessible to the current user will be returned. +- For multi-path write tasks, the operation requires valid write permissions for **all** target time series. + +**Operations Requiring Combined Permissions** +1. With auto-creation enabled, inserting data into non-existent time series requires both `WRITE_DATA` and `WRITE_SCHEMA` privileges. +2. The `SELECT INTO` statement requires read permissions for source paths and write permissions for target paths. Insufficient source permissions result in partial data; insufficient target permissions terminate the task directly. +3. View access control is isolated from source data paths. Read and write operations on views only verify view-specific permissions without checking underlying data source permissions. + +### 6.2 Supplementary Notes +A role is an independent permission container, while users possess both individual standalone permissions and inherited role permissions. + +User effective permissions are the **union** of personal permissions and all permissions from assigned roles. No permission conflicts exist in IoTDB. + +- Revoking a user's standalone permission cannot restrict the operation if the same permission is inherited from an assigned role. To fully disable an operation, administrators must revoke both user-specific permissions and relevant role permissions, or unbind the role from the user. +- Role permission modifications take effect in real time for all bound users. Adding permissions to a role immediately grants access to all associated users, and removing permissions restricts access unless users hold identical standalone permissions. \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_timecho.md b/src/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..83690fdeb --- /dev/null +++ b/src/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,410 @@ + +# Authority Management + +IoTDB provides comprehensive permission management features to control access to data and cluster resources, ensuring data and system security. This document introduces the core concepts of the IoTDB permission module, user specifications, permission governance, authentication logic, and practical application examples. + +## 1. Core Concepts +### 1.1 User +A user refers to a legitimate database operator. Each user is identified by a unique username and authenticated by a password. To access the database, users must log in with valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a wide range of operations, but not all users are authorized to perform every action. A user is granted a corresponding privilege if permitted to execute a specific operation. Each privilege is bounded by a designated path. Flexible permission management can be implemented via [Path Pattern](../Basic-Concept/Operate-Metadata_timecho.md). + +### 1.3 Role +A role is a collection of privileges identified by a unique role name. Roles correspond to actual job identities (e.g., traffic dispatchers), and multiple users may share the same identity with identical permission sets. Roles enable unified and centralized management of permissions for user groups with consistent access requirements. + +### 1.4 Default Users and Roles +After initialization, IoTDB provides one default user: `root`, with the default password `TimechoDB@2021`. As the built-in super administrator, the root user permanently owns all privileges. Its permissions cannot be granted, revoked, or deleted, and it is the sole administrator account in the database. + +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege are authorized to create users and roles, subject to the following constraints: + +### 2.1 Username Rules +Usernames must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of usernames identical to the administrator account is prohibited. + +### 2.2 Password Rules +Passwords must be 12 to 32 characters long, containing both uppercase and lowercase letters, at least one digit, and at least one special symbol (`!@#$%^&*()_+-=`). Passwords cannot be the same as the associated username. + +### 2.3 Role Name Rules +Role names must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of role names identical to the administrator account is prohibited. + +## 3. Permission Management +Based on its tree data model, IoTDB classifies permissions into two major categories: global privileges and time series privileges. + +### 3.1 Global Privileges +Global privileges include three types: `SYSTEM`, `SECURITY`, and `AUDIT`: +- **SYSTEM**: Governs O&M operations and Data Definition Language (DDL) operations. +- **SECURITY**: Governs user and role management, as well as privilege granting for other accounts. +- **AUDIT**: Governs audit rule maintenance and audit log viewing. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege NameOriginal Privilege NameDescription
SYSTEMMANAGE_DATABASEAllows users to create and drop databases.
USE_TRIGGERAllows users to create, drop and query triggers.
USE_UDFAllows users to create, drop and query user-defined functions.
USE_PIPEAllows users to create, start, stop, drop and query PIPE tasks; allows users to create, drop and query PIPEPLUGINS.
USE_CQAllows users to register, start, stop, uninstall and query stream processing tasks; allows users to register, uninstall and query stream processing plugins.
MAINTAINAllows users to execute and cancel queries, view system variables, and check cluster status.
USE_MODELAllows users to create, drop and query deep learning models.
SECURITYMANAGE_USERAllows users to create, drop, modify and query users.
MANAGE_ROLEAllows users to create, drop and query roles; grant roles to other users or revoke roles from other users.
AUDITN/AAllows users to maintain audit log rules and view audit logs.
+ +### 3.2 Time Series Privileges +Time series privileges control the scope and mode of user data access. They support authorization for absolute paths and prefix matching paths, and take effect at the time series granularity. + +Definitions of all time series privileges are listed in the table below: + +| Privilege Name | Description | +| --------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ_DATA | Allows reading time series data under authorized paths. | +| WRITE_DATA | Allows reading time series data under authorized paths.
Allows inserting and deleting time series data under authorized paths.
Supports data import and loading within authorized paths. Data import requires the `WRITE_DATA` privilege for target paths; automatic creation of databases and time series additionally requires `SYSTEM` and `WRITE_SCHEMA` privileges. | +| READ_SCHEMA | Allows viewing detailed metadata tree information under authorized paths, including databases, sub-paths, child nodes, devices, time series, templates, views and other metadata. | +| WRITE_SCHEMA | Allows viewing metadata tree information under authorized paths.
Allows creating, dropping and modifying time series, templates and views under authorized paths.
When creating or modifying a view, the system checks the `WRITE_SCHEMA` privilege for the view path and the `READ_SCHEMA` privilege for data sources.
Querying and inserting data into a view requires the `READ_DATA` and `WRITE_DATA` privileges for the view path.
Allows configuring, canceling and querying TTL settings under authorized paths.
Allows mounting and unmounting templates under authorized paths.
Supports renaming the full path of time series (supported since V2.0.8.2). | + +### 3.3 Privilege Granting and Revocation +In IoTDB, users can obtain permissions through three methods: +1. Granted by the super administrator, who has full control over all user permissions. +2. Granted by common users with authorization permission, who have been assigned the `GRANT OPTION` keyword for specific privileges. +3. Assigned via roles granted by the super administrator or users with the `SECURITY` privilege. + +Permissions can be revoked through the following methods: +1. Revoked by the super administrator. +2. Revoked by common users with authorization permission, who have been assigned the `GRANT OPTION` keyword for specific privileges. +3. Revoked by the super administrator or users with the `SECURITY` privilege by removing specific roles from target users. + +- A valid path must be specified for all authorization operations. Global privileges require the path `root.**`, while time series privileges must use absolute paths or prefix paths ending with double wildcards. +- The `WITH GRANT OPTION` keyword can be specified when granting privileges to roles, enabling grantees to regrant or revoke corresponding privileges within the authorized path scope. For example, if User A is granted read access to `Group1.Company1.**` with the `GRANT OPTION`, User A can authorize or revoke read permissions for all sub-nodes and time series under `Group1.Company1`. +- During revocation, the system matches the revocation statement with all existing permission paths of the target user and clears all matched permissions. For instance, if User A owns the read privilege for `Group1.Company1.Factory1`, revoking the read privilege for `Group1.Company1.**` will clear the permission for the sub-path as well. + +## 4. Syntax and Usage Examples +IoTDB provides combined privilege aliases to simplify authorization configuration: + +| Privilege Name | Scope of Authority | +| ---------- | ---------------------------- | +| ALL | All privileges | +| READ | READ_SCHEMA, READ_DATA | +| WRITE | WRITE_SCHEMA, WRITE_DATA | + +Combined privileges are simplified aliases rather than independent privilege types, and function identically to declaring individual privileges separately. + +The following examples demonstrate common permission management SQL statements. Non-administrator users need corresponding prerequisites to execute these operations, which are noted in each scenario. + +### 4.1 User and Role Management +- **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +eg: CREATE USER user1 'Passwd@202604' +``` + +- **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +eg: DROP USER user1 +``` + +- **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +eg: CREATE ROLE role1 +``` + +- **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +eg: DROP ROLE role1 +``` + +- **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1 +``` + +- **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1 +``` + +- **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +- **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +- **List All Users Under a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser +``` + +- **List Roles of a Specified User** + Users can view their own roles; viewing other users' roles requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser +``` + +- **List All Privileges of a Specified User** + Users can view their own privileges; viewing other users' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER ; +eg: LIST PRIVILEGES OF USER tempuser; +``` + +- **List All Privileges of a Specified Role** + Users can view privileges of their assigned roles; viewing other roles' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE ; +eg: LIST PRIVILEGES OF ROLE actor; +``` + +- **Modify Password** + Users can update their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD ; +eg: ALTER USER tempuser SET PASSWORD 'Newpwd@202604'; +``` + +### 4.2 Privilege Granting and Revocation +#### Grant Syntax +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]; +eg: GRANT READ ON root.** TO ROLE role1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +eg: GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +#### Revoke Syntax +```SQL +REVOKE ON FROM ROLE/USER ; +eg: REVOKE READ ON root.** FROM ROLE role1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +eg: REVOKE SECURITY ON root.** FROM USER user1; +eg: REVOKE ALL ON root.** FROM USER user1; +``` + +- Non-administrator users must hold the target privileges with the `WITH GRANT OPTION` attribute for the specified paths to execute grant or revoke operations. +- When granting or revoking global privileges (or statements containing global privileges, as `ALL` includes global privileges), the path must be set to `root.**`. + +**Valid Examples of Grant & Revoke** +```SQL +GRANT SECURITY ON root.** TO USER user1; +GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; +GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; +REVOKE SECURITY ON root.** FROM USER user1; +REVOKE SECURITY ON root.** FROM ROLE role1; +REVOKE ALL ON root.** FROM ROLE role1; +``` + +**Invalid Statements** +```SQL +GRANT READ, SECURITY ON root.t1.** TO USER user1; +GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; +REVOKE ALL ON root.t1.t2 FROM USER user1; +REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; +``` + +- Valid path formats include complete absolute paths and paths ending with double wildcards: +```SQL +-- Valid Paths +root.** +root.t1.t2.** +root.t1.t2.t3 +``` + +```SQL +-- Invalid Paths +root.t1.* +root.t1.**.t2 +root.t1*.t2.t3 +``` + +## 5. Practical Scenario Example +Based on the [sample data](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt), IoTDB sample data belongs to multiple power generation groups such as ln and sgcc. To prevent cross-group data access, strict permission isolation at the group level is required. + +### 5.1 Create Users +Use the `CREATE USER` statement to create new users. For example, the root administrator creates two write users for the ln and sgcc groups with the unified password `write_Pwd@2026`. It is recommended to wrap usernames with backticks (`). + +```SQL +CREATE USER `ln_write_user` 'write_Pwd@2026'; +CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +``` + +Execute the following statement to query all users: +```SQL +LIST USER; +``` + +Query result: +``` +IoTDB> CREATE USER `ln_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 Grant Permissions +Newly created users have no permissions by default and cannot perform any database operations. For example, an insertion executed by `ln_write_user` will fail: +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +Error message: +``` +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +Grant targeted write permissions to each user via the root account: +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +Execution result: +``` +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +Retry data insertion with `ln_write_user`: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Permissions +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user` +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user` +``` + +Execution result: +``` +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user` +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user` +Msg: The statement is executed successfully. +``` + +After permission revocation, `ln_write_user` loses write access to the `root.ln.**` path: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true) +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. Authentication & Supplementary Instructions +### 6.1 Authentication Mechanism +User permissions consist of three core elements: effective path scope, privilege type, and the `WITH GRANT OPTION` tag. +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +Each user has an independent permission list recording all authorized privileges, which can be queried via `LIST PRIVILEGES OF USER `. + +During authentication, the system matches the target operation path with authorized paths in sequence. When verifying the `read_schema` privilege for `root.t1.t2`, the system first matches the path rule `root.t1.**`. If matched, it checks whether the required privilege is included; otherwise, it continues matching until a valid rule is found or all rules are traversed. + +- For multi-path query tasks, the system only returns data accessible to the current user and filters out unauthorized content. +- For multi-path write tasks, the operation requires valid write permissions for **all** target time series. + +**Operations Requiring Combined Privileges** +1. With automatic time series creation enabled, inserting data into non-existent time series requires both `WRITE_DATA` and metadata modification privileges. +2. The `SELECT INTO` statement requires read privileges for source paths and write privileges for target paths. Insufficient source permissions lead to incomplete data; insufficient target permissions will terminate the task and throw an error. +3. View permissions are independent of underlying data sources. Read and write operations on views only verify view-specific permissions without checking privileges of the original data paths. + +### 6.2 Supplementary Notes +A role is a collection of privileges, while users have two types of attributes: independent individual privileges and inherited role privileges. A single role can contain multiple privileges, and a single user can be assigned multiple roles and independent permissions. + +No conflicting permissions exist in IoTDB. A user’s final effective permissions are the **union** of personal privileges and all privileges from assigned roles. An operation is permitted if either the user’s individual privileges or inherited role privileges contain the required authorization. Duplicate permissions between personal and role settings do not affect normal usage. + +Key notes: +If a user holds an independent privilege for Operation A and obtains the same privilege via a role, revoking only the user’s individual privilege cannot restrict the operation. Administrators must revoke the privilege from the corresponding role or remove the role from the user to disable the operation completely. Similarly, revoking privileges only from roles cannot restrict users with independent permissions. + +Modifications to role permissions take effect in real time for all bound users. Adding privileges to a role immediately grants access to all associated users, and removing privileges will revoke corresponding access unless users hold independent overriding permissions. \ No newline at end of file diff --git a/src/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_apache.md b/src/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..c46333788 --- /dev/null +++ b/src/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,492 @@ + +# Authority Management + +IoTDB provides permission management capabilities to implement fine-grained access control for data and cluster systems, ensuring data and system security. This article introduces the core concepts of the permission module under the IoTDB Table Model, user specifications, permission governance, authentication logic, and practical use cases. + +## 1. Core Concepts +### 1.1 User +A user refers to a legitimate database operator. Each user corresponds to a unique username and is authenticated by a password. To use the database, users must provide valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a wide range of operations, but not all users are authorized to perform every action. A user is considered to have the corresponding privilege if permitted to execute a specific operation. + +### 1.3 Role +A role is a collection of privileges identified by a unique role name. Roles correspond to actual job identities (e.g., traffic dispatchers), and multiple users may share the same identity. Users with identical job roles usually require consistent permissions. Roles serve as an abstraction for unified permission management among user groups. + +### 1.4 Default Users and Roles +After initialization, IoTDB provides one default user named `root` with the default password `root`. As the administrator account, root owns all privileges permanently. Its permissions cannot be granted, revoked, or deleted, and it is the sole administrator user in the database. +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege can create users and roles, subject to the following constraints: + +### 2.1 Username Rules +- Usernames must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of usernames identical to the administrator account is prohibited. +- If a username consists entirely of digits or contains special characters, it must be enclosed in double quotation marks `""` during creation. + +### 2.2 Password Rules +Passwords must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). A password cannot be the same as the associated username. + +### 2.3 Role Name Rules +Role names must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of role names identical to the administrator account is prohibited. + +## 3. Permission Management +Under the IoTDB Table Model, permissions are divided into two major categories: global privileges and data privileges. + +### 3.1 Global Privileges +Global privileges include two types: `SYSTEM` and `SECURITY`: +- **SYSTEM**: Governs O&M operations and Data Definition Language (DDL) related privileges. +- **SECURITY**: Governs the management of users and roles, as well as privilege granting for other accounts. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege CategoryOriginal Privilege NameDescription
SYSTEMN/AAllows users to create, alter and drop databases.
N/AAllows users to create, alter and drop tables and table views.
N/AAllows users to create, drop and query user-defined functions.
N/AAllows users to create, start, stop, drop and query PIPE tasks; allows users to create, drop and query PIPEPLUGINS.
N/AAllows users to execute and cancel queries, view system variables, and check cluster status.
N/AAllows users to create, drop and query deep learning models.
SECURITYMANAGE_USERAllows users to create and drop users, modify user passwords, view user privilege information, and list all users.
MANAGE_ROLEAllows users to create and drop roles, view role privilege information, grant roles to users, revoke roles from users, and list all roles.
+ +### 3.2 Data Privileges +Data privileges consist of privilege types and effective scopes. + +- **Privilege Types**: `CREATE`, `DROP`, `ALTER`, `SELECT`, `INSERT`, `DELETE`. +- **Scopes**: `ANY` (system-wide), `DATABASE` (database-level), `TABLE` (single table). + - Privileges with the `ANY` scope apply to all databases and tables. + - Database-level privileges apply to the specified database and all tables within it. + - Table-level privileges only take effect on the designated single table. +- **Scope Matching Rules**: When executing single-table operations, the system matches user privileges by scope level. For example, when writing data to `DATABASE1.TABLE1`, the system checks write permissions in sequence for `ANY`, `DATABASE1`, and `DATABASE1.TABLE1` until a matching privilege is found or the check fails. + +The logical relationship between privilege types, scopes and capabilities is shown below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege TypeScope LevelCapability Description
CREATEANYAllows creating any databases and tables.
DatabaseAllows creating databases with the specified name and creating tables under the target database.
TableAllows creating the specified table.
DROPANYAllows dropping any databases and tables.
DatabaseAllows dropping the specified database and all tables under it.
TableAllows dropping the specified table.
ALTERANYAllows modifying the definitions of any databases and tables.
DatabaseAllows modifying database definitions and the definitions of all tables under the target database.
TableAllows modifying the structure and definition of the specified table.
SELECTANYAllows querying data from all tables across all databases in the system.
DatabaseAllows querying data from all tables under the specified database.
TableAllows querying data of the specified table. For multi-table queries, only accessible data with valid permissions will be displayed.
INSERTANYAllows inserting and updating data in any tables of all databases.
DatabaseAllows inserting and updating data in all tables under the specified database.
TableAllows inserting and updating data in the specified table.
DELETEANYAllows deleting data from any tables.
DatabaseAllows deleting data within the specified database scope.
TableAllows deleting data from the specified table.
+ +### 3.3 Privilege Granting and Revocation +In IoTDB, user privileges can be granted or revoked through three methods: +1. Direct granting or revocation by the super administrator. +2. Granting or revocation by common users with the `GRANT OPTION` privilege. +3. Granting or revocation via role assignment, operated by the super administrator or users with `SECURITY` privileges. + +The following rules apply to privilege management under the IoTDB Table Model: +- No scope needs to be specified when granting or revoking global privileges. +- Data privilege operations require explicit privilege types and scopes. Revocation only takes effect on the specified scope and is not affected by hierarchical inclusion relationships. +- Pre-authorization is supported for databases and tables that have not yet been created. +- Repeated granting or revocation of privileges is allowed. +- **WITH GRANT OPTION**: Grants users the permission to manage privileges within their authorized scope, including granting and revoking corresponding permissions for other users. + +## 4. Syntax and Usage Examples +### 4.1 User and Role Management +1. **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +-- Example +CREATE USER user1 'passwd' +``` + +2. **Modify Password** + Users can update their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD +-- Example +ALTER USER tempuser SET PASSWORD 'newpwd' +``` + +3. **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +-- Example +DROP USER user1 +``` + +4. **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +-- Example +CREATE ROLE role1 +``` + +5. **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +-- Example +DROP ROLE role1 +``` + +6. **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +-- Example +GRANT ROLE admin TO user1 +``` + +7. **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +-- Example +REVOKE ROLE admin FROM user1 +``` + +8. **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +9. **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +10. **List Users Assigned to a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +-- Example +LIST USER OF ROLE roleuser +``` + +11. **List Roles of a Specified User** + Users can view their own roles; viewing other users' roles requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +-- Example +LIST ROLE OF USER tempuser +``` + +12. **List All Privileges of a User** + Users can view their own privileges; viewing other users' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER +-- Example +LIST PRIVILEGES OF USER tempuser +``` + +13. **List All Privileges of a Role** + Users can view privileges of their assigned roles; viewing other roles' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE +-- Example +LIST PRIVILEGES OF ROLE actor +``` + +### 4.2 Privilege Granting and Revocation +#### 4.2.1 Grant Privileges +1. Grant user management privileges to a user +```SQL +GRANT SECURITY TO USER +-- Example +GRANT SECURITY TO USER TEST_USER +``` + +2. Grant database and table creation privileges with permission management rights +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +-- Example +GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION +``` + +3. Grant database query privileges to a role +```SQL +GRANT SELECT ON DATABASE TO ROLE +-- Example +GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE +``` + +4. Grant table query privileges to a user +```SQL +GRANT SELECT ON . TO USER +-- Example +GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER +``` + +5. Grant global query privileges to a role +```SQL +GRANT SELECT ON ANY TO ROLE +-- Example +GRANT SELECT ON ANY TO ROLE TEST_ROLE +``` + +6. **ALL Syntax Sugar**: `ALL` represents all privileges within the target scope +```SQL +-- Grant all global privileges and full data privileges under ANY scope +GRANT ALL TO USER TESTUSER + +-- Grant all data privileges under ANY scope +GRANT ALL ON ANY TO USER TESTUSER + +-- Grant all data privileges under the specified database +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER + +-- Grant all data privileges under the specified table +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER +``` + +#### 4.2.2 Revoke Privileges +1. Revoke user management privileges +```SQL +REVOKE SECURITY FROM USER +-- Example +REVOKE SECURITY FROM USER TEST_USER +``` + +2. Revoke database and table creation privileges +```SQL +REVOKE CREATE ON DATABASE FROM USER +-- Example +REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER +``` + +3. Revoke table query privileges +```SQL +REVOKE SELECT ON . FROM USER +-- Example +REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER +``` + +4. Revoke global query privileges +```SQL +REVOKE SELECT ON ANY FROM USER +-- Example +REVOKE SELECT ON ANY FROM USER TEST_USER +``` + +5. **ALL Syntax Sugar** for revocation +```SQL +-- Revoke all global privileges and ANY-scoped data privileges +REVOKE ALL FROM USER TESTUSER + +-- Only revoke ANY-scoped data privileges +REVOKE ALL ON ANY FROM USER TESTUSER + +-- Only revoke all data privileges of the specified database +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER + +-- Only revoke all data privileges of the specified table +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER +``` + +### 4.3 View User Privileges +Each user has an independent privilege list recording all authorized permissions. Use the following statement to query privilege details: +```SQL +LIST PRIVILEGES OF USER +``` + +Output format: + +| ROLE | SCOPE | PRIVILEGE | WITH GRANT OPTION | +| ------- |---------|------------| ------------------- | +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | INSERT | TRUE | +| ROLE1 | DB3.* | DELETE | FALSE | +| ROLE1 | *.* | UPDATE | TRUE | + +- **ROLE Column**: Blank for self-owned user privileges; displays the role name if the privilege is inherited from a role. +- **SCOPE Column**: Table-level scope displayed as `DB.TABLE`, database-level scope as `DB.*`, and global ANY scope as `*.*`. +- **PRIVILEGE Column**: Lists specific authorized privilege types. +- **WITH GRANT OPTION Column**: `TRUE` means the user can regrant or revoke privileges within the corresponding scope. + +> Note: Users and roles can hold permissions for both the Tree Model and Table Model simultaneously. The system only displays permissions applicable to the currently connected model, while permissions for the other model are hidden. + +## 5. Practical Scenario Example +Based on the [Sample Data](../Reference/Sample-Data.md), data in different tables belongs to two independent data centers (bj and sh). To ensure data isolation, cross-center data access needs to be restricted through permission control. + +### 5.1 Create Users +Use the `CREATE USER` statement to create new users. For example, the root administrator creates two dedicated write users for the BJ and SH data centers: `bj_write_user` and `sh_write_user`, with a unified password `write_pwd`. + +```SQL +CREATE USER bj_write_user 'write_pwd'; +CREATE USER sh_write_user 'write_pwd'; +``` + +Execute the user query statement: +```SQL +LIST USER +``` + +Query result: +``` ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 Grant Privileges +Newly created users have no permissions by default and cannot perform database operations. For example, an insertion executed by `bj_write_user` will fail: +```SQL +INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +Error message after switching to the target database: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +Grant table write privileges to `bj_write_user` via the root account: +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +Retry data insertion after switching databases: +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Privileges +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +After revocation, the user loses corresponding write permissions and will receive a permission denied error when attempting to write data again: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` diff --git a/src/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_timecho.md b/src/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..5056f75bc --- /dev/null +++ b/src/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,495 @@ + +# Authority Management + +IoTDB provides permission management capabilities to deliver fine-grained access control for data and cluster systems, ensuring data and system security. This document introduces the basic concepts of the permission module under the IoTDB Table Model, user specifications, permission governance, authentication logic, and practical application examples. + +## 1. Basic Concepts +### 1.1 User +A user is a legitimate database operator. Each user is identified by a unique username and authenticated with a password. To use the database, users must provide valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a variety of operations, but not all users are authorized to perform every action. A user is considered to have the corresponding privilege if permitted to execute a specific operation. + +### 1.3 Role +A role is a collection of privileges marked by a unique role identifier. Roles correspond to real-world job identities (e.g., traffic dispatchers), and one identity may cover multiple users. Users with identical job identities usually share the same set of permissions. Roles serve as an abstraction to realize unified permission management for such user groups. + +### 1.4 Default Users and Roles +After initialization, IoTDB provides a default user `root` with the default password `TimechoDB@2021`. As the administrator account, root owns all privileges by default. Its permissions cannot be granted or revoked, and the account cannot be deleted. There is only one administrator user in the database. +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege can create users and roles, and all creations must comply with the following constraints: + +### 2.1 Username Rules +- Length: 4 to 32 characters. Supports uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Usernames identical to the administrator account are not allowed. +- If a username consists entirely of digits or contains special characters, it must be enclosed in double quotation marks `""` during creation. + +### 2.2 Password Rules +Length: 12 to 32 characters. A valid password must contain both uppercase and lowercase letters, at least one digit, and at least one special symbol (`!@#$%^&*()_+-=`). A password cannot be the same as the associated username. + +### 2.3 Role Name Rules +Length: 4 to 32 characters. Supports uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Role names identical to the administrator account are prohibited. + +## 3. Permission Management +Under the IoTDB Table Model, permissions are divided into two major categories: global privileges and data privileges. + +### 3.1 Global Privileges +Global privileges include three types: `SYSTEM`, `SECURITY`, and `AUDIT`: +- **SYSTEM**: Covers privileges for O&M operations and Data Definition Language (DDL) tasks. +- **SECURITY**: Covers management of users and roles, as well as privilege assignment for other accounts. +- **AUDIT**: Covers audit rule maintenance and audit log viewing. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege CategoryOriginal NameDescription
SYSTEMN/AAllows users to create, alter and drop databases.
N/AAllows users to create, alter and drop tables and table views.
N/AAllows users to create, drop and query user-defined functions.
N/AAllows users to create, start, stop, drop and view PIPE tasks; create, drop and view PIPEPLUGINS.
N/AAllows users to execute and cancel queries, view system variables, and check cluster status.
N/AAllows users to create, drop and query deep learning models.
SECURITYMANAGE_USERAllows users to create and drop users, modify user passwords, view user privilege information, and list all users.
MANAGE_ROLEAllows users to create and drop roles, view role privilege information, grant roles to users, revoke roles from users, and list all roles.
AUDITN/AAllows users to maintain audit log rules and view audit logs.
+ +### 3.2 Data Privileges +Data privileges consist of privilege types and effective scopes. + +- **Privilege Types**: `CREATE`, `DROP`, `ALTER`, `SELECT`, `INSERT`, `DELETE`. +- **Scopes**: `ANY` (system-wide), `DATABASE` (database-level), `TABLE` (single table). + - Privileges with the `ANY` scope apply to all databases and tables. + - Database-level privileges apply to the specified database and all tables under it. + - Table-level privileges only take effect on the target single table. +- **Scope Matching Logic**: When performing single-table operations, the system verifies permissions by scope priority. For example, when writing data to `DATABASE1.TABLE1`, the system checks write permissions in sequence for `ANY`, `DATABASE1` and `DATABASE1.TABLE1` until a matching privilege is found or the check fails. + +The logical relationship between privilege types, scopes and capabilities is shown below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege TypePermission Scope (Level)Capability Description
CREATEANYAllows creating any databases and tables.
DatabaseAllows creating the specified database and creating tables under this database.
TableAllows creating the specified table.
DROPANYAllows dropping any databases and tables.
DatabaseAllows dropping the specified database and all tables under it.
TableAllows dropping the specified table.
ALTERANYAllows modifying the definitions of any databases and tables.
DatabaseAllows modifying database definitions and the structure of all tables under the database.
TableAllows modifying the table structure and definition.
SELECTANYAllows querying data from any table across all databases.
DatabaseAllows querying data from all tables in the specified database.
TableAllows querying data in the specified table. For multi-table queries, only accessible data with valid permissions will be displayed.
INSERTANYAllows inserting and updating data in any tables of all databases.
DatabaseAllows inserting and updating data in all tables under the specified database.
TableAllows inserting and updating data in the specified table.
DELETEANYAllows deleting data from any tables.
DatabaseAllows deleting data within the specified database.
TableAllows deleting data in the specified table.
+ +### 3.3 Privilege Granting and Revocation +IoTDB supports privilege assignment and revocation through three methods: +- Direct granting or revocation by the super administrator. +- Granting or revocation by users with the `GRANT OPTION` privilege. +- Granting or revocation via role configuration, operated by the super administrator or users with `SECURITY` privileges. + +The following rules apply to permission management in the IoTDB Table Model: +- No scope needs to be specified when granting or revoking global privileges. +- Data privilege operations require explicit privilege types and scopes. Revocation only takes effect on the designated scope and is not affected by hierarchical inclusion relationships. +- Pre-authorization is supported for databases and tables that have not been created yet. +- Repeated granting or revocation of privileges is permitted. +- **WITH GRANT OPTION**: Authorizes users to manage permissions within their granted scope, including granting and revoking privileges for other users. + +## 4. Syntax and Usage Examples +### 4.1 User and Role Management +1. **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +-- Example +CREATE USER user1 'Passwd@202604' +``` + +2. **Modify Password** + Users can change their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD +-- Example +ALTER USER tempuser SET PASSWORD 'Newpwd@202604' +``` + +3. **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +-- Example +DROP USER user1 +``` + +4. **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +-- Example +CREATE ROLE role1 +``` + +5. **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +-- Example +DROP ROLE role1 +``` + +6. **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +-- Example +GRANT ROLE admin TO user1 +``` + +7. **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +-- Example +REVOKE ROLE admin FROM user1 +``` + +8. **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +9. **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +10. **List Users Under a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +-- Example +LIST USER OF ROLE roleuser +``` + +11. **List Roles of a Specified User** + Users can view their own roles; viewing roles of other users requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +-- Example +LIST ROLE OF USER tempuser +``` + +12. **List All Privileges of a User** + Users can view their own privileges; viewing privileges of other users requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER +-- Example +LIST PRIVILEGES OF USER tempuser +``` + +13. **List All Privileges of a Role** + Users can view privileges of their bound roles; viewing privileges of other roles requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE +-- Example +LIST PRIVILEGES OF ROLE actor +``` + +### 4.2 Granting and Revoking Privileges +#### 4.2.1 Grant Privileges +1. Grant user management privileges to a user +```SQL +GRANT SECURITY TO USER +-- Example +GRANT SECURITY TO USER TEST_USER +``` + +2. Grant database and table creation privileges with independent permission management rights +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +-- Example +GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION +``` + +3. Grant database query privileges to a role +```SQL +GRANT SELECT ON DATABASE TO ROLE +-- Example +GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE +``` + +4. Grant table query privileges to a user +```SQL +GRANT SELECT ON . TO USER +-- Example +GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER +``` + +5. Grant global cross-database query privileges to a role +```SQL +GRANT SELECT ON ANY TO ROLE +-- Example +GRANT SELECT ON ANY TO ROLE TEST_ROLE +``` + +6. **ALL Syntax Sugar**: `ALL` represents all available privileges within the target scope +```SQL +-- Grant all global privileges and full data privileges under the ANY scope +GRANT ALL TO USER TESTUSER + +-- Grant all data privileges covering the entire system scope +GRANT ALL ON ANY TO USER TESTUSER + +-- Grant all data privileges for the specified database +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER + +-- Grant all data privileges for the specified single table +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER +``` + +#### 4.2.2 Revoke Privileges +1. Revoke user management privileges +```SQL +REVOKE SECURITY FROM USER +-- Example +REVOKE SECURITY FROM USER TEST_USER +``` + +2. Revoke database and table creation privileges +```SQL +REVOKE CREATE ON DATABASE FROM USER +-- Example +REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER +``` + +3. Revoke table query privileges +```SQL +REVOKE SELECT ON . FROM USER +-- Example +REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER +``` + +4. Revoke global cross-database query privileges +```SQL +REVOKE SELECT ON ANY FROM USER +-- Example +REVOKE SELECT ON ANY FROM USER TEST_USER +``` + +5. **ALL Syntax Sugar** for privilege revocation +```SQL +-- Revoke all global privileges and ANY-scoped data privileges +REVOKE ALL FROM USER TESTUSER + +-- Only revoke data privileges under the ANY scope +REVOKE ALL ON ANY FROM USER TESTUSER + +-- Only revoke all data privileges of the specified database +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER + +-- Only revoke all data privileges of the specified table +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER +``` + +### 4.3 View User Privileges +Each user has an independent privilege list that records all authorized permissions. +Use `LIST PRIVILEGES OF USER ` to query detailed privileges of a user or role. The output format is as follows: + +| ROLE | SCOPE | PRIVILEGE | WITH GRANT OPTION | +|-------|---------|-----------|------------------| +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | UPDATE | TRUE | +| ROLE1 | DB3.* | DELETE | FALSE | +| ROLE1 | *.* | UPDATE | TRUE | + +- **ROLE**: Blank for self-owned user privileges; displays the role name if the permission is inherited from a role. +- **SCOPE**: Table-level scope displayed as `DB.TABLE`, database-level as `DB.*`, and global ANY scope as `*.*`. +- **PRIVILEGE**: Lists specific authorized permission types. +- **WITH GRANT OPTION**: `TRUE` means the user can grant or revoke permissions within the corresponding scope. +- Users and roles can hold permissions for both the Tree Model and Table Model simultaneously. The system only displays permissions applicable to the currently connected model, while permissions for the other model will be hidden. + +## 5. Practical Scenario Example +Based on the [Sample Data](../Reference/Sample-Data.md), data in different tables belongs to two independent data centers (bj and sh). To prevent unauthorized cross-center data access, permission isolation needs to be configured at the data center level. + +### 5.1 Create Users +Use `CREATE USER` to create new users. For example, the root administrator creates two dedicated write users for the BJ and SH data centers: `bj_write_user` and `sh_write_user`, with a unified password `write_Pwd@2026`. + +```SQL +CREATE USER bj_write_user 'write_Pwd@2026'; +CREATE USER sh_write_user 'write_Pwd@2026'; +``` + +Execute the user query statement: +```SQL +LIST USER +``` + +Query result: +``` ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 Grant Privileges +Newly created users have no permissions by default and cannot perform database operations. For example, an insertion executed by `bj_write_user` will fail: +```SQL +INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +Error prompt: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: database is not specified +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +Grant table write privileges to `bj_write_user` via the root account: +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +Retry data insertion after switching to the target database: +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('Beijing', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Privileges +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +After revocation, `bj_write_user` no longer has write access to table1: +``` +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` + \ No newline at end of file diff --git a/src/UserGuide/latest/User-Manual/Authority-Management-Upgrade_apache.md b/src/UserGuide/latest/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..13993753b --- /dev/null +++ b/src/UserGuide/latest/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,426 @@ + +# Authority Management + +IoTDB provides permission management capabilities for users to control access to data and cluster systems, ensuring data and system security. This article introduces the core concepts of the permission module in IoTDB, user definitions, permission governance, authentication logic, and practical use cases. + +## 1. Core Concepts +### 1.1 User +A user refers to a legitimate database operator. Each user corresponds to a unique username and is authenticated via a password. Before accessing the database, users must log in with valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a wide range of operations, but not all users are authorized to perform every action. A user is considered privileged for an operation if they are permitted to execute it. Each privilege is bounded by a specific path, and path patterns ([Path Pattern](../Basic-Concept/Operate-Metadata_apache.md)) enable flexible permission management. + +### 1.3 Role +A role is a collection of privileges identified by a unique role name. Roles correspond to actual job identities (e.g., traffic dispatchers), and multiple users may share the same identity and identical permission sets. Roles enable unified batch management of permissions for user groups with identical access requirements. + +### 1.4 Default Users and Roles +After initialization, IoTDB contains one default user: `root` with the default password `root`. As the built-in administrator account, the root user owns all permissions permanently. Its permissions cannot be granted, revoked, or deleted, and it is the sole administrator account in the database. + +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege are allowed to create users and roles, subject to the following constraints: + +### 2.1 Username Rules +Usernames must be 4 to 32 characters long, supporting uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of duplicate usernames matching the administrator account is prohibited. + +### 2.2 Password Rules +Passwords must be 4 to 32 characters long, supporting uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Passwords cannot be identical to the associated username. + +### 2.3 Role Name Rules +Role names must be 4 to 32 characters long, supporting uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of duplicate role names matching the administrator account is prohibited. + +## 3. Permission Governance +Based on its tree data model, IoTDB classifies permissions into two major categories: global privileges and series privileges. + +### 3.1 Global Privileges +Global privileges include two types: `SYSTEM` and `SECURITY`: +- **SYSTEM**: Governs O&M operations and Data Definition Language (DDL) actions. +- **SECURITY**: Governs user/role management and privilege granting for other accounts. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege NameOriginal Privilege NameDescription
SYSTEMMANAGE_DATABASEAllows creation and deletion of databases.
USE_TRIGGERAllows creation, deletion and query of triggers.
USE_UDFAllows creation, deletion and query of user-defined functions.
USE_PIPEAllows creation, startup, stop, deletion and query of PIPE tasks; allows creation, deletion and query of PIPEPLUGINS.
USE_CQAllows registration, startup, stop, uninstallation and query of stream processing tasks; allows registration, uninstallation and query of stream processing plugins.
EXTEND_TEMPLATEAllows automatic template extension.
MAINTAINAllows query execution and cancellation, system variable viewing, and cluster status inspection.
USE_MODELAllows creation, deletion and query of deep learning models.
SECURITYMANAGE_USERAllows creation, deletion, modification and query of users.
MANAGE_ROLEAllows creation, deletion and query of roles; grants and revokes roles for other users.
+ +#### Template-Related Permission Rules +1. Template creation, deletion, modification, query, mounting and unmounting are restricted to the administrator only. +2. Template activation requires the `WRITE_SCHEMA` privilege for the target activation path. +3. When auto-creation is enabled, writing data to non-existent paths with mounted templates requires both the `EXTEND_TEMPLATE` privilege and the `WRITE_DATA` privilege for target time series. +4. Template unmounting requires the `WRITE_SCHEMA` privilege for the template mounting path. +5. Querying paths bound to metadata templates requires the `READ_SCHEMA` privilege for the target path; empty results will be returned without sufficient permissions. + +### 3.2 Series Privileges +Series privileges control the scope and mode of user data access, supporting authorization for absolute paths and prefix-matched paths at the time series granularity. + +Definitions of all series privileges are listed below: + +| Privilege Name | Description | +| --------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ_DATA | Allows reading time series data under authorized paths. | +| WRITE_DATA | Permits reading time series data under authorized paths;
Allows insertion and deletion of time series data;
Supports data import and loading. Data import requires the `WRITE_DATA` privilege for target paths; automatic database and time series creation additionally requires `SYSTEM` and `WRITE_SCHEMA` privileges. | +| READ_SCHEMA | Allows viewing detailed metadata tree information under authorized paths, including databases, sub-paths, nodes, devices, time series, templates and views. | +| WRITE_SCHEMA | Permits viewing metadata tree information under authorized paths;
Enables creation, deletion and modification of time series, templates and views;
View creation and modification require `WRITE_SCHEMA` for the view path and `READ_SCHEMA` for data sources; view read/write operations require `READ_DATA` and `WRITE_DATA` for the view path;
Supports TTL configuration, cancellation and query;
Allows template mounting and unmounting. | + +### 3.3 Privilege Granting and Revocation +Users can obtain permissions through three methods: +1. Grants issued by the super administrator (root). +2. Grants issued by common users with the `grant option` for specific privileges. +3. Role assignment by the super administrator or users with the `SECURITY` privilege. + +Permissions can be revoked through three methods: +1. Revocation operations executed by the super administrator. +2. Revocation operations executed by common users with the `grant option` for specific privileges. +3. Role revocation performed by the super administrator or users with the `SECURITY` privilege. + +- A valid path must be specified for all authorization operations. Global privileges require the path `root.**`, while series privileges require absolute paths or prefix paths ending with double wildcards. +- The `WITH GRANT OPTION` keyword can be appended during role authorization, enabling grantees to regrant or revoke the same privileges within the authorized path scope. For example, if User A is granted read access to `Group1.Company1.**` with the grant option, User A can authorize or revoke read permissions for all sub-nodes under `Group1.Company1`. +- Revocation statements perform full matching against existing user permission paths. For instance, revoking read access for `Group1.Company1.**` will clear all granular read permissions for sub-paths such as `Group1.Company1.Factory1`. + +## 4. Syntax and Usage Examples +IoTDB provides combined privilege aliases to simplify authorization configuration: + +| Combined Privilege | Coverage | +| ---------- | ---------------------------- | +| ALL | All system and series privileges | +| READ | READ_SCHEMA, READ_DATA | +| WRITE | WRITE_SCHEMA, WRITE_DATA | + +Combined privileges are simplified aliases and function identically to declaring individual privileges separately. + +The following examples demonstrate common permission management SQL statements. Non-administrator users require corresponding prerequisites for executing these operations, which are marked in each scenario. + +### 4.1 User and Role Management +- **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +-- Example +CREATE USER user1 'passwd' +``` + +- **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +-- Example +DROP USER user1 +``` + +- **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +-- Example +CREATE ROLE role1 +``` + +- **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +-- Example +DROP ROLE role1 +``` + +- **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +-- Example +GRANT ROLE admin TO user1 +``` + +- **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +-- Example +REVOKE ROLE admin FROM user1 +``` + +- **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +- **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +- **List Users Assigned to a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +-- Example +LIST USER OF ROLE roleuser +``` + +- **List Roles of a Specified User** + Users can view their own roles; viewing other users' roles requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +-- Example +LIST ROLE OF USER tempuser +``` + +- **List All Privileges of a Specified User** + Users can view their own privileges; viewing other users' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER ; +-- Example +LIST PRIVILEGES OF USER tempuser; +``` + +- **List All Privileges of a Specified Role** + Users can view privileges of their assigned roles; viewing other roles' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE ; +-- Example +LIST PRIVILEGES OF ROLE actor; +``` + +- **Modify Password** + Users can update their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD ; +-- Example +ALTER USER tempuser SET PASSWORD 'newpwd'; +``` + +### 4.2 Privilege Granting and Revocation +#### Grant Syntax +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]; +-- Examples +GRANT READ ON root.** TO ROLE role1; +GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +#### Revoke Syntax +```SQL +REVOKE ON FROM ROLE/USER ; +-- Examples +REVOKE READ ON root.** FROM ROLE role1; +REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +REVOKE SECURITY ON root.** FROM USER user1; +REVOKE ALL ON root.** FROM USER user1; +``` + +- Non-administrator users must hold the target privileges with the `WITH GRANT OPTION` attribute for the specified paths to execute grant or revoke operations. +- For global privileges (or statements containing global privileges such as `ALL`), the path must be strictly set to `root.**`. + +**Valid Authorization Examples** +```SQL +GRANT SECURITY ON root.** TO USER user1; +GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; +GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; +REVOKE SECURITY ON root.** FROM USER user1; +REVOKE SECURITY ON root.** FROM ROLE role1; +REVOKE ALL ON root.** FROM ROLE role1; +``` + +**Invalid Authorization Examples** +```SQL +GRANT READ, SECURITY ON root.t1.** TO USER user1; +GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; +REVOKE ALL ON root.t1.t2 FROM USER user1; +REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; +``` + +- Valid path formats include absolute full paths and paths ending with double wildcards: + ```SQL + -- Valid Paths + root.** + root.t1.t2.** + root.t1.t2.t3 + ``` + + ```SQL + -- Invalid Paths + root.t1.* + root.t1.**.t2 + root.t1*.t2.t3 + ``` + +## 5. Practical Scenario Example +Based on [sample data](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt), IoTDB sample data belongs to multiple power generation groups such as ln and sgcc. To ensure data isolation, cross-group data access needs to be restricted via permission control. + +### 5.1 Create Users +Use the `CREATE USER` statement to create dedicated users. The root administrator creates two write users for the ln and sgcc groups with the unified password `write_pwd`: +```SQL +CREATE USER `ln_write_user` 'write_pwd'; +CREATE USER `sgcc_write_user` 'write_pwd'; +``` + +Execute the user listing statement to verify creation: +```SQL +LIST USER; +``` + +Execution result: +``` +IoTDB> CREATE USER `ln_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 Grant Permissions +Newly created users have no permissions by default. Attempting to write data directly will trigger a permission error: +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +Error message: +``` +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +Grant targeted write permissions to each user via the root account: +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +Execution result: +``` +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +Retry data writing with `ln_write_user`: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Permissions +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +``` + +Execution result: +``` +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user` +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user` +Msg: The statement is executed successfully. +``` + +After permission revocation, the user loses write access again: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true) +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. Authentication & Supplementary Instructions +### 6.1 Authentication Mechanism +Each user's permission set consists of three core elements: effective path range, privilege type, and the `with grant option` tag. + +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +All user permissions can be queried via `LIST PRIVILEGES OF USER `. + +During authentication, IoTDB matches the target operation path against the user's authorized paths in sequence. The check passes if a matching path and corresponding privilege are found; otherwise, the operation is rejected. + +- For multi-path query tasks, only data accessible to the current user will be returned. +- For multi-path write tasks, the operation requires valid write permissions for **all** target time series. + +**Operations Requiring Combined Permissions** +1. With auto-creation enabled, inserting data into non-existent time series requires both `WRITE_DATA` and `WRITE_SCHEMA` privileges. +2. The `SELECT INTO` statement requires read permissions for source paths and write permissions for target paths. Insufficient source permissions result in partial data; insufficient target permissions terminate the task directly. +3. View access control is isolated from source data paths. Read and write operations on views only verify view-specific permissions without checking underlying data source permissions. + +### 6.2 Supplementary Notes +A role is an independent permission container, while users possess both individual standalone permissions and inherited role permissions. + +User effective permissions are the **union** of personal permissions and all permissions from assigned roles. No permission conflicts exist in IoTDB. + +- Revoking a user's standalone permission cannot restrict the operation if the same permission is inherited from an assigned role. To fully disable an operation, administrators must revoke both user-specific permissions and relevant role permissions, or unbind the role from the user. +- Role permission modifications take effect in real time for all bound users. Adding permissions to a role immediately grants access to all associated users, and removing permissions restricts access unless users hold identical standalone permissions. \ No newline at end of file diff --git a/src/UserGuide/latest/User-Manual/Authority-Management-Upgrade_timecho.md b/src/UserGuide/latest/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..83690fdeb --- /dev/null +++ b/src/UserGuide/latest/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,410 @@ + +# Authority Management + +IoTDB provides comprehensive permission management features to control access to data and cluster resources, ensuring data and system security. This document introduces the core concepts of the IoTDB permission module, user specifications, permission governance, authentication logic, and practical application examples. + +## 1. Core Concepts +### 1.1 User +A user refers to a legitimate database operator. Each user is identified by a unique username and authenticated by a password. To access the database, users must log in with valid usernames and passwords stored in the system. + +### 1.2 Privilege +The database supports a wide range of operations, but not all users are authorized to perform every action. A user is granted a corresponding privilege if permitted to execute a specific operation. Each privilege is bounded by a designated path. Flexible permission management can be implemented via [Path Pattern](../Basic-Concept/Operate-Metadata_timecho.md). + +### 1.3 Role +A role is a collection of privileges identified by a unique role name. Roles correspond to actual job identities (e.g., traffic dispatchers), and multiple users may share the same identity with identical permission sets. Roles enable unified and centralized management of permissions for user groups with consistent access requirements. + +### 1.4 Default Users and Roles +After initialization, IoTDB provides one default user: `root`, with the default password `TimechoDB@2021`. As the built-in super administrator, the root user permanently owns all privileges. Its permissions cannot be granted, revoked, or deleted, and it is the sole administrator account in the database. + +Newly created users and roles have no permissions by default. + +## 2. User Specifications +Users with the `SECURITY` privilege are authorized to create users and roles, subject to the following constraints: + +### 2.1 Username Rules +Usernames must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of usernames identical to the administrator account is prohibited. + +### 2.2 Password Rules +Passwords must be 12 to 32 characters long, containing both uppercase and lowercase letters, at least one digit, and at least one special symbol (`!@#$%^&*()_+-=`). Passwords cannot be the same as the associated username. + +### 2.3 Role Name Rules +Role names must be 4 to 32 characters long, including uppercase and lowercase letters, digits, and special symbols (`!@#$%^&*()_+-=`). Creation of role names identical to the administrator account is prohibited. + +## 3. Permission Management +Based on its tree data model, IoTDB classifies permissions into two major categories: global privileges and time series privileges. + +### 3.1 Global Privileges +Global privileges include three types: `SYSTEM`, `SECURITY`, and `AUDIT`: +- **SYSTEM**: Governs O&M operations and Data Definition Language (DDL) operations. +- **SECURITY**: Governs user and role management, as well as privilege granting for other accounts. +- **AUDIT**: Governs audit rule maintenance and audit log viewing. + +Detailed descriptions of each global privilege are shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Privilege NameOriginal Privilege NameDescription
SYSTEMMANAGE_DATABASEAllows users to create and drop databases.
USE_TRIGGERAllows users to create, drop and query triggers.
USE_UDFAllows users to create, drop and query user-defined functions.
USE_PIPEAllows users to create, start, stop, drop and query PIPE tasks; allows users to create, drop and query PIPEPLUGINS.
USE_CQAllows users to register, start, stop, uninstall and query stream processing tasks; allows users to register, uninstall and query stream processing plugins.
MAINTAINAllows users to execute and cancel queries, view system variables, and check cluster status.
USE_MODELAllows users to create, drop and query deep learning models.
SECURITYMANAGE_USERAllows users to create, drop, modify and query users.
MANAGE_ROLEAllows users to create, drop and query roles; grant roles to other users or revoke roles from other users.
AUDITN/AAllows users to maintain audit log rules and view audit logs.
+ +### 3.2 Time Series Privileges +Time series privileges control the scope and mode of user data access. They support authorization for absolute paths and prefix matching paths, and take effect at the time series granularity. + +Definitions of all time series privileges are listed in the table below: + +| Privilege Name | Description | +| --------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ_DATA | Allows reading time series data under authorized paths. | +| WRITE_DATA | Allows reading time series data under authorized paths.
Allows inserting and deleting time series data under authorized paths.
Supports data import and loading within authorized paths. Data import requires the `WRITE_DATA` privilege for target paths; automatic creation of databases and time series additionally requires `SYSTEM` and `WRITE_SCHEMA` privileges. | +| READ_SCHEMA | Allows viewing detailed metadata tree information under authorized paths, including databases, sub-paths, child nodes, devices, time series, templates, views and other metadata. | +| WRITE_SCHEMA | Allows viewing metadata tree information under authorized paths.
Allows creating, dropping and modifying time series, templates and views under authorized paths.
When creating or modifying a view, the system checks the `WRITE_SCHEMA` privilege for the view path and the `READ_SCHEMA` privilege for data sources.
Querying and inserting data into a view requires the `READ_DATA` and `WRITE_DATA` privileges for the view path.
Allows configuring, canceling and querying TTL settings under authorized paths.
Allows mounting and unmounting templates under authorized paths.
Supports renaming the full path of time series (supported since V2.0.8.2). | + +### 3.3 Privilege Granting and Revocation +In IoTDB, users can obtain permissions through three methods: +1. Granted by the super administrator, who has full control over all user permissions. +2. Granted by common users with authorization permission, who have been assigned the `GRANT OPTION` keyword for specific privileges. +3. Assigned via roles granted by the super administrator or users with the `SECURITY` privilege. + +Permissions can be revoked through the following methods: +1. Revoked by the super administrator. +2. Revoked by common users with authorization permission, who have been assigned the `GRANT OPTION` keyword for specific privileges. +3. Revoked by the super administrator or users with the `SECURITY` privilege by removing specific roles from target users. + +- A valid path must be specified for all authorization operations. Global privileges require the path `root.**`, while time series privileges must use absolute paths or prefix paths ending with double wildcards. +- The `WITH GRANT OPTION` keyword can be specified when granting privileges to roles, enabling grantees to regrant or revoke corresponding privileges within the authorized path scope. For example, if User A is granted read access to `Group1.Company1.**` with the `GRANT OPTION`, User A can authorize or revoke read permissions for all sub-nodes and time series under `Group1.Company1`. +- During revocation, the system matches the revocation statement with all existing permission paths of the target user and clears all matched permissions. For instance, if User A owns the read privilege for `Group1.Company1.Factory1`, revoking the read privilege for `Group1.Company1.**` will clear the permission for the sub-path as well. + +## 4. Syntax and Usage Examples +IoTDB provides combined privilege aliases to simplify authorization configuration: + +| Privilege Name | Scope of Authority | +| ---------- | ---------------------------- | +| ALL | All privileges | +| READ | READ_SCHEMA, READ_DATA | +| WRITE | WRITE_SCHEMA, WRITE_DATA | + +Combined privileges are simplified aliases rather than independent privilege types, and function identically to declaring individual privileges separately. + +The following examples demonstrate common permission management SQL statements. Non-administrator users need corresponding prerequisites to execute these operations, which are noted in each scenario. + +### 4.1 User and Role Management +- **Create User** (Requires `SECURITY` privilege) +```SQL +CREATE USER +eg: CREATE USER user1 'Passwd@202604' +``` + +- **Drop User** (Requires `SECURITY` privilege) +```SQL +DROP USER +eg: DROP USER user1 +``` + +- **Create Role** (Requires `SECURITY` privilege) +```SQL +CREATE ROLE +eg: CREATE ROLE role1 +``` + +- **Drop Role** (Requires `SECURITY` privilege) +```SQL +DROP ROLE +eg: DROP ROLE role1 +``` + +- **Grant Role to User** (Requires `SECURITY` privilege) +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1 +``` + +- **Revoke Role from User** (Requires `SECURITY` privilege) +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1 +``` + +- **List All Users** (Requires `SECURITY` privilege) +```SQL +LIST USER +``` + +- **List All Roles** (Requires `SECURITY` privilege) +```SQL +LIST ROLE +``` + +- **List All Users Under a Specified Role** (Requires `SECURITY` privilege) +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser +``` + +- **List Roles of a Specified User** + Users can view their own roles; viewing other users' roles requires the `SECURITY` privilege. +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser +``` + +- **List All Privileges of a Specified User** + Users can view their own privileges; viewing other users' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF USER ; +eg: LIST PRIVILEGES OF USER tempuser; +``` + +- **List All Privileges of a Specified Role** + Users can view privileges of their assigned roles; viewing other roles' privileges requires the `SECURITY` privilege. +```SQL +LIST PRIVILEGES OF ROLE ; +eg: LIST PRIVILEGES OF ROLE actor; +``` + +- **Modify Password** + Users can update their own passwords; modifying other users' passwords requires the `SECURITY` privilege. +```SQL +ALTER USER SET PASSWORD ; +eg: ALTER USER tempuser SET PASSWORD 'Newpwd@202604'; +``` + +### 4.2 Privilege Granting and Revocation +#### Grant Syntax +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]; +eg: GRANT READ ON root.** TO ROLE role1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +eg: GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +#### Revoke Syntax +```SQL +REVOKE ON FROM ROLE/USER ; +eg: REVOKE READ ON root.** FROM ROLE role1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +eg: REVOKE SECURITY ON root.** FROM USER user1; +eg: REVOKE ALL ON root.** FROM USER user1; +``` + +- Non-administrator users must hold the target privileges with the `WITH GRANT OPTION` attribute for the specified paths to execute grant or revoke operations. +- When granting or revoking global privileges (or statements containing global privileges, as `ALL` includes global privileges), the path must be set to `root.**`. + +**Valid Examples of Grant & Revoke** +```SQL +GRANT SECURITY ON root.** TO USER user1; +GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; +GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; +REVOKE SECURITY ON root.** FROM USER user1; +REVOKE SECURITY ON root.** FROM ROLE role1; +REVOKE ALL ON root.** FROM ROLE role1; +``` + +**Invalid Statements** +```SQL +GRANT READ, SECURITY ON root.t1.** TO USER user1; +GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; +REVOKE ALL ON root.t1.t2 FROM USER user1; +REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; +``` + +- Valid path formats include complete absolute paths and paths ending with double wildcards: +```SQL +-- Valid Paths +root.** +root.t1.t2.** +root.t1.t2.t3 +``` + +```SQL +-- Invalid Paths +root.t1.* +root.t1.**.t2 +root.t1*.t2.t3 +``` + +## 5. Practical Scenario Example +Based on the [sample data](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt), IoTDB sample data belongs to multiple power generation groups such as ln and sgcc. To prevent cross-group data access, strict permission isolation at the group level is required. + +### 5.1 Create Users +Use the `CREATE USER` statement to create new users. For example, the root administrator creates two write users for the ln and sgcc groups with the unified password `write_Pwd@2026`. It is recommended to wrap usernames with backticks (`). + +```SQL +CREATE USER `ln_write_user` 'write_Pwd@2026'; +CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +``` + +Execute the following statement to query all users: +```SQL +LIST USER; +``` + +Query result: +``` +IoTDB> CREATE USER `ln_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 Grant Permissions +Newly created users have no permissions by default and cannot perform any database operations. For example, an insertion executed by `ln_write_user` will fail: +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +Error message: +``` +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +Grant targeted write permissions to each user via the root account: +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +Execution result: +``` +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +Retry data insertion with `ln_write_user`: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 Revoke Permissions +Use the `REVOKE` statement to reclaim granted permissions: +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user` +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user` +``` + +Execution result: +``` +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user` +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user` +Msg: The statement is executed successfully. +``` + +After permission revocation, `ln_write_user` loses write access to the `root.ln.**` path: +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true) +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. Authentication & Supplementary Instructions +### 6.1 Authentication Mechanism +User permissions consist of three core elements: effective path scope, privilege type, and the `WITH GRANT OPTION` tag. +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +Each user has an independent permission list recording all authorized privileges, which can be queried via `LIST PRIVILEGES OF USER `. + +During authentication, the system matches the target operation path with authorized paths in sequence. When verifying the `read_schema` privilege for `root.t1.t2`, the system first matches the path rule `root.t1.**`. If matched, it checks whether the required privilege is included; otherwise, it continues matching until a valid rule is found or all rules are traversed. + +- For multi-path query tasks, the system only returns data accessible to the current user and filters out unauthorized content. +- For multi-path write tasks, the operation requires valid write permissions for **all** target time series. + +**Operations Requiring Combined Privileges** +1. With automatic time series creation enabled, inserting data into non-existent time series requires both `WRITE_DATA` and metadata modification privileges. +2. The `SELECT INTO` statement requires read privileges for source paths and write privileges for target paths. Insufficient source permissions lead to incomplete data; insufficient target permissions will terminate the task and throw an error. +3. View permissions are independent of underlying data sources. Read and write operations on views only verify view-specific permissions without checking privileges of the original data paths. + +### 6.2 Supplementary Notes +A role is a collection of privileges, while users have two types of attributes: independent individual privileges and inherited role privileges. A single role can contain multiple privileges, and a single user can be assigned multiple roles and independent permissions. + +No conflicting permissions exist in IoTDB. A user’s final effective permissions are the **union** of personal privileges and all privileges from assigned roles. An operation is permitted if either the user’s individual privileges or inherited role privileges contain the required authorization. Duplicate permissions between personal and role settings do not affect normal usage. + +Key notes: +If a user holds an independent privilege for Operation A and obtains the same privilege via a role, revoking only the user’s individual privilege cannot restrict the operation. Administrators must revoke the privilege from the corresponding role or remove the role from the user to disable the operation completely. Similarly, revoking privileges only from roles cannot restrict users with independent permissions. + +Modifications to role permissions take effect in real time for all bound users. Adding privileges to a role immediately grants access to all associated users, and removing privileges will revoke corresponding access unless users hold independent overriding permissions. \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_apache.md b/src/zh/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..bf93815ce --- /dev/null +++ b/src/zh/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,533 @@ + + +# 权限管理 + +IoTDB 提供了权限管理功能，用于对数据和集群系统执行精细的访问控制，保障数据与系统安全。本篇介绍了 IoTDB 表模型中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户 root，默认密码为 root。该用户为管理员用户，拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +* 4\~32个字符，支持使用英文大小写字母、数字、特殊字符`（!@#$%^&*()_+-=）`，用户无法创建和管理员用户同名的用户。 +* 如果用户名全是数字或包含特殊字符，则创建时需要使用双引号`""`括起来。 + +### 2.2 密码限制 + +4~32个字符，可使用大写小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4\~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 表模型主要有两类权限：全局权限、数据权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY 两种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEM无允许用户创建、修改、删除数据库。
无允许用户创建、修改、删除表及表视图。
无允许用户创建、删除、查看用户自定义函数。
无允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
无允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
无允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER-允许用户创建、删除用户 允许用户修改用户密码 允许用户查看用户的权限信息 允许用户列出所有用户
MANAGE_ROLE-允许用户创建、删除角色 允许用户查看角色的权限信息 允许用户将角色授予某个用户或撤销 允许用户列出所有角色
+ +### 3.2 数据权限 + +数据权限由权限类型和范围组成。 + +* 权限类型包括：CREATE（创建权限），DROP（删除权限），ALTER（修改权限），SELECT（查询数据权限），INSERT（插入/更新数据权限），DELETE（删除数据权限）。 +* 范围包括：ANY（系统范围内），DATABASE（数据库范围内），TABLE（单个表）。 + * 作用于 ANY 的权限会影响所有数据库和表。 + * 作用于数据库的权限会影响该数据库及其所有表。 + * 作用于表的权限仅影响该表。 +* 范围生效说明：执行单表操作时，数据库会匹配用户权限与数据权限范围。例如，用户尝试向 DATABASE1.TABLE1 写入数据时，系统会依次检查用户是否有对 ANY、DATABASE1或 DATABASE1.TABLE1 的写入权限，直到匹配成功或者匹配失败。 +* 权限类型、范围及效果逻辑关系如下表所示： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限类型权限范围（层级）权限效果
CREATEANY允许创建任意表、创建任意数据库
数据库允许用户在该数据库下创建表;允许用户创建该名称的数据库
表允许用户创建该名称的表
DROPANY允许删除任意表、删除任意数据库
数据库允许用户删除该数据库;允许用户删除该数据库下的表
表D允许用户删除该表
ALTERANY允许修改任意表的定义、任意数据库的定义
数据库允许用户修改数据库的定义，允许用户修改数据库下表的定义
表允许用户修改表的定义
SELECTANY允许查询系统内任意数据库中任意表的数据
数据库允许用户查询该数据库中任意表的数据
表允许用户查询该表中的数据。执行多表查询时，数据库仅展示用户有权限访问的数据。
INSERTANY允许任意数据库的任意表插入/更新数据
数据库允许用户向该数据库范围内任意表插入/更新数据
表允许用户向该表中插入/更新数据
DELETEANY允许删除任意表的数据
数据库允许用户删除该数据库范围内的数据
表允许用户删除该表中的数据
+ +### 3.3 权限授予与取消 + +IoTDB支持通过如下三种途径进行用户授权和撤销权限： + +* 超级管理员直接授予或撤销 +* 拥有GRANT OPTION权限的用户授予或撤销 +* 通过角色授予或撤销（由超级管理员或具备 SECURITY 权限的用户操作角色） + +在IoTDB 表模型中，授权或撤销权限时需遵循以下原则： + +* 授权/撤销全局权限时，无需指定权限的范围。 +* 授予/撤销数据权限时，需要指定权限类型和权限范围。在撤销权限时只会撤销指定的权限范围，不会受权限范围包含关系的影响。 +* 允许对尚未创建的数据库或表提前进行权限规划和授权。 +* 允许重复授权/撤销权限。 +* WITH GRANT OPTION: 允许用户在授权范围内管理权限。用户可以授予或撤销其他用户在该范围内的权限。 + +## 4. 功能语法与示例 + +### 4.1 用户与角色相关 + +1. 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'passwd'; +``` + +2. 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD +eg: ALTER USER tempuser SET PASSWORD 'newpwd'; +``` + +3. 删除用户（需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +4. 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +5. 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +6. 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +7. 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +8. 列出所有用户（需 SECURITY 权限) + +```SQL +LIST USER; +``` + +9. 列出所有的角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +10. 列出指定角色下所有用户（需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +11. 列出指定用户下的所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +12. 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER +eg: LIST PRIVILEGES OF USER tempuser; +``` + +13. 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE +eg: LIST PRIVILEGES OF ROLE actor; +``` + +### 4.2 授权与取消授权 + +#### 4.2.1 授予权限 + +1. 给用户授予管理用户的权限 + +```SQL +GRANT SECURITY TO USER +eg: GRANT SECURITY TO USER TEST_USER; +``` + +2. 给用户授予创建数据库及在数据库范围内创建表的权限，且允许用户在该范围内管理权限 + +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +eg: GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION; +``` + +3. 给角色授予查询数据库的权限 + +```SQL +GRANT SELECT ON DATABASE TO ROLE +eg: GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE; +``` + +4. 给用户授予查询表的权限 + +```SQL +GRANT SELECT ON . TO USER +eg: GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER; +``` + +5. 给角色授予查询所有数据库及表的权限 + +```SQL +GRANT SELECT ON ANY TO ROLE +eg: GRANT SELECT ON ANY TO ROLE TEST_ROLE; +``` + +6. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地授予权限。 + +```SQL +GRANT ALL TO USER TESTUSER; +-- 将用户可以获取的所有权限授予给用户,包括全局权限和 ANY 范围的所有数据权限 + +GRANT ALL ON ANY TO USER TESTUSER; +-- 将 ANY 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在所有数据库上的所有数据权限 + +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER; +-- 将 DB 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该数据库上的所有数据权限 + +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER; +-- 将 TABLE 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该表上的所有数据权限 +``` + +#### 4.2.2 撤销权限 + +1. 取消用户管理用户的权限 + +```SQL +REVOKE SECURITY FROM USER +eg: REVOKE SECURITY FROM USER TEST_USER; +``` + +2. 取消用户创建数据库及在数据库范围内创建表的权限 + +```SQL +REVOKE CREATE ON DATABASE FROM USER +eg: REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER; +``` + +3. 取消用户查询表的权限 + +```SQL +REVOKE SELECT ON . FROM USER +eg: REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER; +``` + +4. 取消用户查询所有数据库及表的权限 + +```SQL +REVOKE SELECT ON ANY FROM USER +eg: REVOKE SELECT ON ANY FROM USER TEST_USER; +``` + +5. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地撤销权限。 + +```SQL +REVOKE ALL FROM USER TESTUSER; +-- 取消用户所有的全局权限以及 ANY 范围的所有数据权限 + +REVOKE ALL ON ANY FROM USER TESTUSER; +-- 取消用户 ANY 范围的所有数据权限，不会影响 DB 范围和 TABLE 范围的权限 + +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER; +-- 取消用户在 DB 上的所有数据权限,不会影响 TABLE 权限 + +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER; +-- 取消用户在 TABLE 上的所有数据权限 +``` + +### 4.3 查看用户权限 + +每个用户都有一个权限访问列表，标识其获得的所有权限。可使用 `LIST PRIVILEGES OF USER ` 语句查看某个用户或角色的权限信息，输出格式如下： + +| ROLE | SCOPE | PRIVIVLEGE | WITH GRANT OPTION | +| ------- |---------|------------| ------------------- | +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | UPDATE | TRUE | +| ROLE1 | DB3.\* | DELETE | FALSE | +| ROLE1 | \*.\* | UPDATE | TRUE | + +其中： + +* `ROLE` 列：如果为空，则表示为该用户的自身权限。如果不为空，则表示该权限来源于被授予的角色。 +* `SCOPE` 列：表示该用户/角色的权限范围，表范围的权限表示为`DB.TABLE`，数据库范围的权限表示为`DB.*`, ANY 范围的权限表示为`*.*`。 +* `PRIVIVLEGE` 列：列出具体的权限类型。 +* `WITH GRANT OPTION` 列：如果为 TRUE，表示用户可以将自己的权限授予他人。 +* 用户或者角色可以同时具有树模型和表模型的权限，但系统会根据当前连接的模型来显示相应的权限，另一种模型下的权限则不会显示。 + +## 5. 场景示例 + +以 [示例数据](../Reference/Sample-Data.md) 内容为例，两个表的数据可能分别属于 bj、sh 两个数据中心，彼此间不希望对方获取自己的数据库数据，因此我们需要将不同的数据在数据中心层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 `bj_write_user`, `sh_write_user`，密码均为 write_pwd。SQL 语句为： + +```SQL +CREATE USER bj_write_user 'write_pwd'; +CREATE USER sh_write_user 'write_pwd'; +``` + +使用展示用户的 SQL 语句： + +```SQL +LIST USER +``` + +可以看到这两个已经被创建的用户，结果如下： + +```SQL ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 赋予用户权限 + +虽然两个用户已经创建，但是不具有任何权限，因此并不能对数据库进行操作，例如使用 `bj_write_user` 用户对 table1 中的数据进行写入，SQL 语句为： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: database is not specified +IoTDB> use database1 +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +root 用户使用 `GRANT ON TO USER ` 语句赋予用户`bj_write_user`对 table1 的写入权限，例如： + +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +使用`bj_write_user`再尝试写入数据 + +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销`bj_write_user`和`sh_write_user`的权限： + +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +撤销权限后，`bj_write_user`就没有向table1写入数据的权限了。 + +```SQL +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` diff --git a/src/zh/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_timecho.md b/src/zh/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..94334ce70 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,539 @@ + + +# 权限管理 + +IoTDB 提供了权限管理功能，用于对数据和集群系统执行精细的访问控制，保障数据与系统安全。本篇介绍了 IoTDB 表模型中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户 root，默认密码为 TimechoDB@2021。该用户为管理员用户，拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +* 4\~32个字符，支持使用英文大小写字母、数字、特殊字符`（!@#$%^&*()_+-=）`，用户无法创建和管理员用户同名的用户。 +* 如果用户名全是数字或包含特殊字符，则创建时需要使用双引号`""`括起来。 + +### 2.2 密码限制 + +12~32个字符，必须包含大写小写字母、至少一个数字、至少一个特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4\~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 表模型主要有两类权限：全局权限、数据权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY、AUDIT 三种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 +* AUDIT ：只具备维护审计规则、查看审计日志的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEM无允许用户创建、修改、删除数据库。
无允许用户创建、修改、删除表及表视图。
无允许用户创建、删除、查看用户自定义函数。
无允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
无允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
无允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER-允许用户创建、删除用户 允许用户修改用户密码 允许用户查看用户的权限信息 允许用户列出所有用户
MANAGE_ROLE-允许用户创建、删除角色 允许用户查看角色的权限信息 允许用户将角色授予某个用户或撤销 允许用户列出所有角色
AUDIT无允许用户维护审计日志的规则 允许用户查看审计日志
+ +### 3.2 数据权限 + +数据权限由权限类型和范围组成。 + +* 权限类型包括：CREATE（创建权限），DROP（删除权限），ALTER（修改权限），SELECT（查询数据权限），INSERT（插入/更新数据权限），DELETE（删除数据权限）。 +* 范围包括：ANY（系统范围内），DATABASE（数据库范围内），TABLE（单个表）。 + * 作用于 ANY 的权限会影响所有数据库和表。 + * 作用于数据库的权限会影响该数据库及其所有表。 + * 作用于表的权限仅影响该表。 +* 范围生效说明：执行单表操作时，数据库会匹配用户权限与数据权限范围。例如，用户尝试向 DATABASE1.TABLE1 写入数据时，系统会依次检查用户是否有对 ANY、DATABASE1或 DATABASE1.TABLE1 的写入权限，直到匹配成功或者匹配失败。 +* 权限类型、范围及效果逻辑关系如下表所示： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限类型权限范围（层级）权限效果
CREATEANY允许创建任意表、创建任意数据库
数据库允许用户在该数据库下创建表;允许用户创建该名称的数据库
表允许用户创建该名称的表
DROPANY允许删除任意表、删除任意数据库
数据库允许用户删除该数据库;允许用户删除该数据库下的表
表D允许用户删除该表
ALTERANY允许修改任意表的定义、任意数据库的定义
数据库允许用户修改数据库的定义，允许用户修改数据库下表的定义
表允许用户修改表的定义
SELECTANY允许查询系统内任意数据库中任意表的数据
数据库允许用户查询该数据库中任意表的数据
表允许用户查询该表中的数据。执行多表查询时，数据库仅展示用户有权限访问的数据。
INSERTANY允许任意数据库的任意表插入/更新数据
数据库允许用户向该数据库范围内任意表插入/更新数据
表允许用户向该表中插入/更新数据
DELETEANY允许删除任意表的数据
数据库允许用户删除该数据库范围内的数据
表允许用户删除该表中的数据
+ +### 3.3 权限授予与取消 + +IoTDB支持通过如下三种途径进行用户授权和撤销权限： + +* 超级管理员直接授予或撤销 +* 拥有GRANT OPTION权限的用户授予或撤销 +* 通过角色授予或撤销（由超级管理员或具备 SECURITY 权限的用户操作角色） + +在IoTDB 表模型中，授权或撤销权限时需遵循以下原则： + +* 授权/撤销全局权限时，无需指定权限的范围。 +* 授予/撤销数据权限时，需要指定权限类型和权限范围。在撤销权限时只会撤销指定的权限范围，不会受权限范围包含关系的影响。 +* 允许对尚未创建的数据库或表提前进行权限规划和授权。 +* 允许重复授权/撤销权限。 +* WITH GRANT OPTION: 允许用户在授权范围内管理权限。用户可以授予或撤销其他用户在该范围内的权限。 + +## 4. 功能语法与示例 + +### 4.1 用户与角色相关 + +1. 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'Passwd@202604'; +``` + +2. 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD +eg: ALTER USER tempuser SET PASSWORD 'Newpwd@202604'; +``` + +3. 删除用户（需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +4. 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +5. 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +6. 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +7. 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +8. 列出所有用户（需 SECURITY 权限) + +```SQL +LIST USER; +``` + +9. 列出所有的角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +10. 列出指定角色下所有用户（需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +11. 列出指定用户下的所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +12. 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER +eg: LIST PRIVILEGES OF USER tempuser; +``` + +13. 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE +eg: LIST PRIVILEGES OF ROLE actor; +``` + +### 4.2 授权与取消授权 + +#### 4.2.1 授予权限 + +1. 给用户授予管理用户的权限 + +```SQL +GRANT SECURITY TO USER +eg: GRANT SECURITY TO USER TEST_USER; +``` + +2. 给用户授予创建数据库及在数据库范围内创建表的权限，且允许用户在该范围内管理权限 + +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +eg: GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION; +``` + +3. 给角色授予查询数据库的权限 + +```SQL +GRANT SELECT ON DATABASE TO ROLE +eg: GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE; +``` + +4. 给用户授予查询表的权限 + +```SQL +GRANT SELECT ON . TO USER +eg: GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER; +``` + +5. 给角色授予查询所有数据库及表的权限 + +```SQL +GRANT SELECT ON ANY TO ROLE +eg: GRANT SELECT ON ANY TO ROLE TEST_ROLE; +``` + +6. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地授予权限。 + +```SQL +GRANT ALL TO USER TESTUSER; +-- 将用户可以获取的所有权限授予给用户,包括全局权限和 ANY 范围的所有数据权限 + +GRANT ALL ON ANY TO USER TESTUSER; +-- 将 ANY 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在所有数据库上的所有数据权限 + +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER; +-- 将 DB 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该数据库上的所有数据权限 + +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER; +-- 将 TABLE 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该表上的所有数据权限 +``` + +#### 4.2.2 撤销权限 + +1. 取消用户管理用户的权限 + +```SQL +REVOKE SECURITY FROM USER +eg: REVOKE SECURITY FROM USER TEST_USER; +``` + +2. 取消用户创建数据库及在数据库范围内创建表的权限 + +```SQL +REVOKE CREATE ON DATABASE FROM USER +eg: REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER; +``` + +3. 取消用户查询表的权限 + +```SQL +REVOKE SELECT ON . FROM USER +eg: REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER; +``` + +4. 取消用户查询所有数据库及表的权限 + +```SQL +REVOKE SELECT ON ANY FROM USER +eg: REVOKE SELECT ON ANY FROM USER TEST_USER; +``` + +5. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地撤销权限。 + +```SQL +REVOKE ALL FROM USER TESTUSER; +-- 取消用户所有的全局权限以及 ANY 范围的所有数据权限 + +REVOKE ALL ON ANY FROM USER TESTUSER; +-- 取消用户 ANY 范围的所有数据权限，不会影响 DB 范围和 TABLE 范围的权限 + +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER; +-- 取消用户在 DB 上的所有数据权限,不会影响 TABLE 权限 + +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER; +-- 取消用户在 TABLE 上的所有数据权限 +``` + +### 4.3 查看用户权限 + +每个用户都有一个权限访问列表，标识其获得的所有权限。可使用 `LIST PRIVILEGES OF USER ` 语句查看某个用户或角色的权限信息，输出格式如下： + +| ROLE | SCOPE | PRIVIVLEGE | WITH GRANT OPTION | +| ------- |---------|------------| ------------------- | +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | UPDATE | TRUE | +| ROLE1 | DB3.\* | DELETE | FALSE | +| ROLE1 | \*.\* | UPDATE | TRUE | + +其中： + +* `ROLE` 列：如果为空，则表示为该用户的自身权限。如果不为空，则表示该权限来源于被授予的角色。 +* `SCOPE` 列：表示该用户/角色的权限范围，表范围的权限表示为`DB.TABLE`，数据库范围的权限表示为`DB.*`, ANY 范围的权限表示为`*.*`。 +* `PRIVIVLEGE` 列：列出具体的权限类型。 +* `WITH GRANT OPTION` 列：如果为 TRUE，表示用户可以将自己的权限授予他人。 +* 用户或者角色可以同时具有树模型和表模型的权限，但系统会根据当前连接的模型来显示相应的权限，另一种模型下的权限则不会显示。 + +## 5. 场景示例 + +以 [示例数据](../Reference/Sample-Data.md) 内容为例，两个表的数据可能分别属于 bj、sh 两个数据中心，彼此间不希望对方获取自己的数据库数据，因此我们需要将不同的数据在数据中心层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 `bj_write_user`, `sh_write_user`，密码均为 write_Pwd@2026。SQL 语句为： + +```SQL +CREATE USER bj_write_user 'write_Pwd@2026'; +CREATE USER sh_write_user 'write_Pwd@2026'; +``` + +使用展示用户的 SQL 语句： + +```SQL +LIST USER; +``` + +可以看到这两个已经被创建的用户，结果如下： + +```SQL ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 赋予用户权限 + +虽然两个用户已经创建，但是不具有任何权限，因此并不能对数据库进行操作，例如使用 `bj_write_user` 用户对 table1 中的数据进行写入，SQL 语句为： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: database is not specified +IoTDB> use database1 +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +root 用户使用 `GRANT ON TO USER ` 语句赋予用户`bj_write_user`对 table1 的写入权限，例如： + +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +使用`bj_write_user`再尝试写入数据 + +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销`bj_write_user`和`sh_write_user`的权限： + +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +撤销权限后，`bj_write_user`就没有向table1写入数据的权限了。 + +```SQL +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` diff --git a/src/zh/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_apache.md b/src/zh/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..b8e374776 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,474 @@ + + +# 权限管理 + +IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群系统的权限管理功能，保障数据与系统安全。本篇介绍IoTDB 中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码，作为用户成功登录。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。权限通常需要一个路径来限定其生效范围，可以使用[路径模式](../Basic-Concept/Operate-Metadata_apache.md)灵活管理权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户：root，默认密码为`root`。该用户为管理员用户，固定拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。 + +一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的用户。 + +### 2.2 密码限制 + +4~32个字符，可使用大写小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 树模型主要有两类权限：全局权限、序列权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY 两种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEMMANAGE_DATABASE允许用户创建、删除数据库.
USE_TRIGGER允许用户创建、删除、查看触发器。
USE_UDF允许用户创建、删除、查看用户自定义函数。
USE_PIPE允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
USE_CQ允许用户注册、开始、停止、卸载、查询流处理任务。允许用户注册、卸载、查询注册流处理任务插件。
EXTEND_TEMPLATE允许自动扩展模板。
MAINTAIN允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
USE_MODEL允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER允许用户创建、删除、修改、查看用户。
MANAGE_ROLE允许用户创建、删除、查看角色。允许用户将角色授予给其他用户,或取消其他用户的角色。
+ +关于模板权限： + +1. 模板的创建、删除、修改、查询、挂载、卸载仅允许管理员操作。 +2. 激活模板需要拥有激活路径的 WRITE\_SCHEMA 权限。 +3. 若开启了自动创建，在向挂载了模板的不存在路径写入时，数据库会自动扩展模板并写入数据，因此需要有 EXTEND\_TEMPLATE 权限与写入序列的 WRITE\_DATA 权限。 +4. 解除模板，需要拥有挂载模板路径的 WRITE\_SCHEMA 权限。 +5. 查询使用了某个元数据模板的路径，需要有路径的 READ\_SCHEMA 权限，否则将返回为空。 + +### 3.2 序列权限 + +序列权限约束了用户访问数据的范围与方式，支持对绝对路径与前缀匹配路径授权，可对timeseries 粒度生效。 + +下表描述了这类权限的种类与范围： + +| 权限名称 | 描述 | +| --------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ\_DATA | 允许读取授权路径下的序列数据。 | +| WRITE\_DATA | 允许读取授权路径下的序列数据。
允许插入、删除授权路径下的的序列数据。
允许在授权路径下导入、加载数据，在导入数据时，需要拥有对应路径的 WRITE\_DATA 权限，在自动创建数据库与序列时，需要有SYSTEM与 WRITE\_SCHEMA 权限。 | +| READ\_SCHEMA | 允许获取授权路径下元数据树的详细信息，包括：路径下的数据库、子路径、子节点、设备、序列、模版、视图等。 | +| WRITE\_SCHEMA | 允许获取授权路径下元数据树的详细信息。
允许在授权路径下对序列、模版、视图等进行创建、删除、修改操作。
在创建或修改 view 的时候，会检查 view 路径的 WRITE\_SCHEMA 权限、数据源的 READ\_SCHEMA 权限。
在对 view 进行查询、插入时，会检查 view 路径的 READ\_DATA 权限、WRITE\_DATA 权限。
允许在授权路径下设置、取消、查看TTL。
允许在授权路径下挂载或者接触挂载模板。 | + +### 3.3 权限授予与取消 + +在 IoTDB 中，用户可以由三种途径获得权限： + +1. 由超级管理员授予，超级管理员可以控制其他用户的权限。 +2. 由允许权限授权的用户授予，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者有 SECURITY 的用户授予某个角色进而获取权限。 + +取消用户的权限，可以由以下几种途径： + +1. 由超级管理员取消用户的权限。 +2. 由允许权限授权的用户取消权限，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者 SECURITY 的用户取消用户的某个角色进而取消权限。 + +* 在授权时，必须指定路径。全局权限需要指定为 root.\*\*, 而序列相关权限必须为绝对路径或者以双通配符结尾的前缀路径。 +* 当授予角色权限时，可以为该权限指定 with grant option 关键字，意味着用户可以转授其授权路径上的权限，也可以取消其他用户的授权路径上的权限。例如用户 A 在被授予`集团1.公司1.**`的读权限时制定了 grant option 关键字，那么 A 可以将`集团1.公司1`以下的任意节点、序列的读权限转授给他人， 同样也可以取消其他用户 `集团1.公司1` 下任意节点的读权限。 +* 在取消授权时，取消授权语句会与用户所有的权限路径进行匹配，将匹配到的权限路径进行清理，例如用户A 具有 `集团1.公司1.工厂1 `的读权限， 在取消 `集团1.公司1.** `的读权限时，会清除用户A 的 `集团1.公司1.工厂1` 的读权限。 + +## 4. 功能语法与示例 + +IoTDB 提供了组合权限，方便用户授权： + +| 权限名称 | 权限范围 | +| ---------- | ---------------------------- | +| ALL | 所有权限 | +| READ | READ\_SCHEMA、READ\_DATA | +| WRITE | WRITE\_SCHEMA、WRITE\_DATA | + +组合权限并不是一种具体的权限，而是一种简写方式，与直接书写对应的权限名称没有差异。 + +下面将通过一系列具体的用例展示权限语句的用法，非管理员执行下列语句需要提前获取权限，所需的权限标记在操作描述后。 + +### 4.1 用户与角色相关 + +* 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'passwd'; +``` + +* 删除用户 (需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +* 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +* 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +* 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +* 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +* 列出所有用户 (需 SECURITY 权限) + +```SQL +LIST USER; +``` + +* 列出所有角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +* 列出指定角色下所有用户 (需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +* 列出指定用户下所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +* 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER ; +eg: LIST PRIVILEGES OF USER tempuser; +``` + +* 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE ; +eg: LIST PRIVILEGES OF ROLE actor; +``` + +* 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD ; +eg: ALTER USER tempuser SET PASSWORD 'newpwd'; +``` + +### 4.2 授权与取消授权 + +用户使用授权语句对赋予其他用户权限，语法如下： + +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]； +eg: GRANT READ ON root.** TO ROLE role1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +eg: GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +用户使用取消授权语句可以将其他的权限取消，语法如下： + +```SQL +REVOKE ON FROM ROLE/USER ; +eg: REVOKE READ ON root.** FROM ROLE role1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +eg: REVOKE SECURITY ON root.** FROM USER user1; +eg: REVOKE ALL ON root.** FROM USER user1; +``` + +* **非管理员用户执行授权/取消授权语句时，需要对`` 有`` 权限，并且该权限是被标记带有 WITH GRANT OPTION 的。** +* 在授予取消全局权限时，或者语句中包含全局权限时(ALL 展开会包含全局权限），须指定 path 为 root.\*\*。 例如，以下授权/取消授权语句是合法的： + + ```SQL + GRANT SECURITY ON root.** TO USER user1; + GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; + GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; + REVOKE SECURITY ON root.** FROM USER user1; + REVOKE SECURITY ON root.** FROM ROLE role1; + REVOKE ALL ON root.** FROM ROLE role1; + ``` + + 下面的语句是非法的： + + ```SQL + GRANT READ, SECURITY ON root.t1.** TO USER user1; + GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; + REVOKE ALL ON root.t1.t2 FROM USER user1; + REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; + ``` +* `` 必须为全路径或者以双通配符结尾的匹配路径，以下路径是合法的: + + ```SQL + root.** + root.t1.t2.** + root.t1.t2.t3 + ``` + + 以下的路径是非法的： + + ```SQL + root.t1.* + root.t1.**.t2 + root.t1*.t2.t3 + ``` + +## 5. 场景示例 + +根据本文中描述的 [样例数据](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt) 内容，IoTDB 的样例数据可能同时属于 ln, sgcc 等不同发电集团，不同的发电集团不希望其他发电集团获取自己的数据库数据，因此我们需要将不同的数据在集团层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，我们可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 ln\_write\_user, sgcc\_write\_user，密码均为 write_pwd。建议使用反引号(\`)包裹用户名。SQL 语句为： + +```SQL +CREATE USER `ln_write_user` 'write_pwd'; +CREATE USER `sgcc_write_user` 'write_pwd'; +``` + +此时使用展示用户的 SQL 语句： + +```SQL +LIST USER; +``` + +我们可以看到这两个已经被创建的用户，结果如下： + +```SQL +IoTDB> CREATE USER `ln_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 赋予用户权限 + +此时，虽然两个用户已经创建，但是他们不具有任何权限，因此他们并不能对数据库进行操作，例如我们使用 ln\_write\_user 用户对数据库中的数据进行写入，SQL 语句为： + +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +此时，系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +现在，我们用 root 用户分别赋予他们向对应路径的写入权限. + +我们使用 `GRANT ON TO USER ` 语句赋予用户权限,例如： + +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +接着使用ln\_write\_user再尝试写入数据 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，我们可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销ln\_write\_user和sgcc\_write\_user的权限： + +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +撤销权限后，ln\_write\_user就没有向root.ln.\*\*写入数据的权限了。 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. 鉴权及其他 + +### 6.1 鉴权 + +用户权限主要由三部分组成：权限生效范围（路径）， 权限类型， with grant option 标记： + +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +每个用户都有一个这样的权限访问列表，标识他们获得的所有权限，可以通过 `LIST PRIVILEGES OF USER ` 查看他们的权限。 + +在对一个路径进行鉴权时，数据库会进行路径与权限的匹配。例如检查 `root.t1.t2` 的 read\_schema 权限时，首先会与权限访问列表的 `root.t1.**`进行匹配，匹配成功，则检查该路径是否包含待鉴权的权限，否则继续下一条路径-权限的匹配，直到匹配成功或者匹配结束。 + +在进行多路径鉴权时，对于多路径查询任务，数据库只会将有权限的数据呈现出来，无权限的数据不会包含在结果中；对于多路径写入任务，数据库要求必须所有的目标序列都获得了对应的权限，才能进行写入。 + +请注意，下面的操作需要检查多重权限 + +1. 开启了自动创建序列功能，在用户将数据插入到不存在的序列中时，不仅需要对应序列的写入权限，还需要序列的元数据修改权限。 +2. 执行 select into 语句时，需要检查源序列的读权限与目标序列的写权限。需要注意的是源序列数据可能因为权限不足而仅能获取部分数据，目标序列写入权限不足时会报错终止任务。 +3. View 权限与数据源的权限是独立的，向 view 执行读写操作仅会检查 view 的权限，而不再对源路径进行权限校验。 + +### 6.2 其他说明 + +角色是权限的集合，而权限和角色都是用户的一种属性。即一个角色可以拥有若干权限。一个用户可以拥有若干角色与权限（称为用户自身权限）。 + +目前在 IoTDB 中并不存在相互冲突的权限，因此一个用户真正具有的权限是用户自身权限与其所有的角色的权限的并集。即要判定用户是否能执行某一项操作，就要看用户自身权限或用户的角色的所有权限中是否有一条允许了该操作。用户自身权限与其角色权限，他的多个角色的权限之间可能存在相同的权限，但这并不会产生影响。 + +需要注意的是：如果一个用户自身有某种权限（对应操作 A），而他的某个角色有相同的权限。那么如果仅从该用户撤销该权限无法达到禁止该用户执行操作 A 的目的，还需要从这个角色中也撤销对应的权限，或者从这个用户将该角色撤销。同样，如果仅从上述角色将权限撤销，也不能禁止该用户执行操作 A。 + +同时，对角色的修改会立即反映到所有拥有该角色的用户上，例如对角色增加某种权限将立即使所有拥有该角色的用户都拥有对应权限，删除某种权限也将使对应用户失去该权限（除非用户本身有该权限）。 diff --git a/src/zh/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_timecho.md b/src/zh/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..2733e772c --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,468 @@ + + +# 权限管理 + +IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群系统的权限管理功能，保障数据与系统安全。本篇介绍IoTDB 中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码，作为用户成功登录。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。权限通常需要一个路径来限定其生效范围，可以使用[路径模式](../Basic-Concept/Operate-Metadata_timecho.md)灵活管理权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户：root，默认密码为`TimechoDB@2021`。该用户为管理员用户，固定拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。 + +一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的用户。 + +### 2.2 密码限制 + +12~32个字符，必须包含大写小写字母、至少一个数字、至少一个特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 树模型主要有两类权限：全局权限、序列权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY、AUDIT 三种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 +* AUDIT ：只具备维护审计规则、查看审计日志的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEMMANAGE_DATABASE允许用户创建、删除数据库.
USE_TRIGGER允许用户创建、删除、查看触发器。
USE_UDF允许用户创建、删除、查看用户自定义函数。
USE_PIPE允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
USE_CQ允许用户注册、开始、停止、卸载、查询流处理任务。允许用户注册、卸载、查询注册流处理任务插件。
MAINTAIN允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
USE_MODEL允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER允许用户创建、删除、修改、查看用户。
MANAGE_ROLE允许用户创建、删除、查看角色。允许用户将角色授予给其他用户,或取消其他用户的角色。
AUDIT无允许用户维护审计日志的规则 允许用户查看审计日志
+ +### 3.2 序列权限 + +序列权限约束了用户访问数据的范围与方式，支持对绝对路径与前缀匹配路径授权，可对timeseries 粒度生效。 + +下表描述了这类权限的种类与范围： + +| 权限名称 | 描述 | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| READ\_DATA | 允许读取授权路径下的序列数据。 | +| WRITE\_DATA | 允许读取授权路径下的序列数据。
允许插入、删除授权路径下的的序列数据。
允许在授权路径下导入、加载数据，在导入数据时，需要拥有对应路径的 WRITE\_DATA 权限，在自动创建数据库与序列时，需要有SYSTEM与 WRITE\_SCHEMA 权限。 | +| READ\_SCHEMA | 允许获取授权路径下元数据树的详细信息，包括：路径下的数据库、子路径、子节点、设备、序列、模版、视图等。 | +| WRITE\_SCHEMA | 允许获取授权路径下元数据树的详细信息。
允许在授权路径下对序列、模版、视图等进行创建、删除、修改操作。
在创建或修改 view 的时候，会检查 view 路径的 WRITE\_SCHEMA 权限、数据源的 READ\_SCHEMA 权限。
在对 view 进行查询、插入时，会检查 view 路径的 READ\_DATA 权限、WRITE\_DATA 权限。
允许在授权路径下设置、取消、查看TTL。
允许在授权路径下挂载或者接触挂载模板。
允许在授权路径下对序列进行全路径名称的修改操作。//V2.0.8.2 起支持该功能 | + +### 3.3 权限授予与取消 + +在 IoTDB 中，用户可以由三种途径获得权限： + +1. 由超级管理员授予，超级管理员可以控制其他用户的权限。 +2. 由允许权限授权的用户授予，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者有 SECURITY 的用户授予某个角色进而获取权限。 + +取消用户的权限，可以由以下几种途径： + +1. 由超级管理员取消用户的权限。 +2. 由允许权限授权的用户取消权限，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者 SECURITY 的用户取消用户的某个角色进而取消权限。 + +* 在授权时，必须指定路径。全局权限需要指定为 root.\*\*, 而序列相关权限必须为绝对路径或者以双通配符结尾的前缀路径。 +* 当授予角色权限时，可以为该权限指定 with grant option 关键字，意味着用户可以转授其授权路径上的权限，也可以取消其他用户的授权路径上的权限。例如用户 A 在被授予`集团1.公司1.**`的读权限时制定了 grant option 关键字，那么 A 可以将`集团1.公司1`以下的任意节点、序列的读权限转授给他人， 同样也可以取消其他用户 `集团1.公司1` 下任意节点的读权限。 +* 在取消授权时，取消授权语句会与用户所有的权限路径进行匹配，将匹配到的权限路径进行清理，例如用户A 具有 `集团1.公司1.工厂1 `的读权限， 在取消 `集团1.公司1.** `的读权限时，会清除用户A 的 `集团1.公司1.工厂1` 的读权限。 + +## 4. 功能语法与示例 + +IoTDB 提供了组合权限，方便用户授权： + +| 权限名称 | 权限范围 | +| ---------- | ---------------------------- | +| ALL | 所有权限 | +| READ | READ\_SCHEMA、READ\_DATA | +| WRITE | WRITE\_SCHEMA、WRITE\_DATA | + +组合权限并不是一种具体的权限，而是一种简写方式，与直接书写对应的权限名称没有差异。 + +下面将通过一系列具体的用例展示权限语句的用法，非管理员执行下列语句需要提前获取权限，所需的权限标记在操作描述后。 + +### 4.1 用户与角色相关 + +* 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'Passwd@202604'; +``` + +* 删除用户 (需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +* 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +* 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +* 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +* 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +* 列出所有用户 (需 SECURITY 权限) + +```SQL +LIST USER; +``` + +* 列出所有角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +* 列出指定角色下所有用户 (需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +* 列出指定用户下所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +* 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER ; +eg: LIST PRIVILEGES OF USER tempuser; +``` + +* 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE ; +eg: LIST PRIVILEGES OF ROLE actor; +``` + +* 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD ; +eg: ALTER USER tempuser SET PASSWORD 'Newpwd@202604'; +``` + +### 4.2 授权与取消授权 + +用户使用授权语句对赋予其他用户权限，语法如下： + +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]； +eg: GRANT READ ON root.** TO ROLE role1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +eg: GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +用户使用取消授权语句可以将其他的权限取消，语法如下： + +```SQL +REVOKE ON FROM ROLE/USER ; +eg: REVOKE READ ON root.** FROM ROLE role1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +eg: REVOKE SECURITY ON root.** FROM USER user1; +eg: REVOKE ALL ON root.** FROM USER user1; +``` + +* **非管理员用户执行授权/取消授权语句时，需要对`` 有`` 权限，并且该权限是被标记带有 WITH GRANT OPTION 的。** +* 在授予取消全局权限时，或者语句中包含全局权限时(ALL 展开会包含全局权限），须指定 path 为 root.\*\*。 例如，以下授权/取消授权语句是合法的： + + ```SQL + GRANT SECURITY ON root.** TO USER user1; + GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; + GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; + REVOKE SECURITY ON root.** FROM USER user1; + REVOKE SECURITY ON root.** FROM ROLE role1; + REVOKE ALL ON root.** FROM ROLE role1; + ``` + + 下面的语句是非法的： + + ```SQL + GRANT READ, SECURITY ON root.t1.** TO USER user1; + GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; + REVOKE ALL ON root.t1.t2 FROM USER user1; + REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; + ``` +* `` 必须为全路径或者以双通配符结尾的匹配路径，以下路径是合法的: + + ```SQL + root.** + root.t1.t2.** + root.t1.t2.t3 + ``` + + 以下的路径是非法的： + + ```SQL + root.t1.* + root.t1.**.t2 + root.t1*.t2.t3 + ``` + +## 5. 场景示例 + +根据本文中描述的 [样例数据](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt) 内容，IoTDB 的样例数据可能同时属于 ln, sgcc 等不同发电集团，不同的发电集团不希望其他发电集团获取自己的数据库数据，因此我们需要将不同的数据在集团层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，我们可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 ln\_write\_user, sgcc\_write\_user，密码均为 write_Pwd@2026。建议使用反引号(\`)包裹用户名。SQL 语句为： + +```SQL +CREATE USER `ln_write_user` 'write_Pwd@2026'; +CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +``` + +此时使用展示用户的 SQL 语句： + +```SQL +LIST USER; +``` + +我们可以看到这两个已经被创建的用户，结果如下： + +```SQL +IoTDB> CREATE USER `ln_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 赋予用户权限 + +此时，虽然两个用户已经创建，但是他们不具有任何权限，因此他们并不能对数据库进行操作，例如我们使用 ln\_write\_user 用户对数据库中的数据进行写入，SQL 语句为： + +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +此时，系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +现在，我们用 root 用户分别赋予他们向对应路径的写入权限. + +我们使用 `GRANT ON TO USER ` 语句赋予用户权限,例如： + +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +接着使用ln\_write\_user再尝试写入数据 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，我们可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销ln\_write\_user和sgcc\_write\_user的权限： + +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +撤销权限后，ln\_write\_user就没有向root.ln.\*\*写入数据的权限了。 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. 鉴权及其他 + +### 6.1 鉴权 + +用户权限主要由三部分组成：权限生效范围（路径）， 权限类型， with grant option 标记： + +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +每个用户都有一个这样的权限访问列表，标识他们获得的所有权限，可以通过 `LIST PRIVILEGES OF USER ` 查看他们的权限。 + +在对一个路径进行鉴权时，数据库会进行路径与权限的匹配。例如检查 `root.t1.t2` 的 read\_schema 权限时，首先会与权限访问列表的 `root.t1.**`进行匹配，匹配成功，则检查该路径是否包含待鉴权的权限，否则继续下一条路径-权限的匹配，直到匹配成功或者匹配结束。 + +在进行多路径鉴权时，对于多路径查询任务，数据库只会将有权限的数据呈现出来，无权限的数据不会包含在结果中；对于多路径写入任务，数据库要求必须所有的目标序列都获得了对应的权限，才能进行写入。 + +请注意，下面的操作需要检查多重权限 + +1. 开启了自动创建序列功能，在用户将数据插入到不存在的序列中时，不仅需要对应序列的写入权限，还需要序列的元数据修改权限。 +2. 执行 select into 语句时，需要检查源序列的读权限与目标序列的写权限。需要注意的是源序列数据可能因为权限不足而仅能获取部分数据，目标序列写入权限不足时会报错终止任务。 +3. View 权限与数据源的权限是独立的，向 view 执行读写操作仅会检查 view 的权限，而不再对源路径进行权限校验。 + +### 6.2 其他说明 + +角色是权限的集合，而权限和角色都是用户的一种属性。即一个角色可以拥有若干权限。一个用户可以拥有若干角色与权限（称为用户自身权限）。 + +目前在 IoTDB 中并不存在相互冲突的权限，因此一个用户真正具有的权限是用户自身权限与其所有的角色的权限的并集。即要判定用户是否能执行某一项操作，就要看用户自身权限或用户的角色的所有权限中是否有一条允许了该操作。用户自身权限与其角色权限，他的多个角色的权限之间可能存在相同的权限，但这并不会产生影响。 + +需要注意的是：如果一个用户自身有某种权限（对应操作 A），而他的某个角色有相同的权限。那么如果仅从该用户撤销该权限无法达到禁止该用户执行操作 A 的目的，还需要从这个角色中也撤销对应的权限，或者从这个用户将该角色撤销。同样，如果仅从上述角色将权限撤销，也不能禁止该用户执行操作 A。 + +同时，对角色的修改会立即反映到所有拥有该角色的用户上，例如对角色增加某种权限将立即使所有拥有该角色的用户都拥有对应权限，删除某种权限也将使对应用户失去该权限（除非用户本身有该权限）。 diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_apache.md b/src/zh/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..bf93815ce --- /dev/null +++ b/src/zh/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,533 @@ + + +# 权限管理 + +IoTDB 提供了权限管理功能，用于对数据和集群系统执行精细的访问控制，保障数据与系统安全。本篇介绍了 IoTDB 表模型中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户 root，默认密码为 root。该用户为管理员用户，拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +* 4\~32个字符，支持使用英文大小写字母、数字、特殊字符`（!@#$%^&*()_+-=）`，用户无法创建和管理员用户同名的用户。 +* 如果用户名全是数字或包含特殊字符，则创建时需要使用双引号`""`括起来。 + +### 2.2 密码限制 + +4~32个字符，可使用大写小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4\~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 表模型主要有两类权限：全局权限、数据权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY 两种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEM无允许用户创建、修改、删除数据库。
无允许用户创建、修改、删除表及表视图。
无允许用户创建、删除、查看用户自定义函数。
无允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
无允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
无允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER-允许用户创建、删除用户 允许用户修改用户密码 允许用户查看用户的权限信息 允许用户列出所有用户
MANAGE_ROLE-允许用户创建、删除角色 允许用户查看角色的权限信息 允许用户将角色授予某个用户或撤销 允许用户列出所有角色
+ +### 3.2 数据权限 + +数据权限由权限类型和范围组成。 + +* 权限类型包括：CREATE（创建权限），DROP（删除权限），ALTER（修改权限），SELECT（查询数据权限），INSERT（插入/更新数据权限），DELETE（删除数据权限）。 +* 范围包括：ANY（系统范围内），DATABASE（数据库范围内），TABLE（单个表）。 + * 作用于 ANY 的权限会影响所有数据库和表。 + * 作用于数据库的权限会影响该数据库及其所有表。 + * 作用于表的权限仅影响该表。 +* 范围生效说明：执行单表操作时，数据库会匹配用户权限与数据权限范围。例如，用户尝试向 DATABASE1.TABLE1 写入数据时，系统会依次检查用户是否有对 ANY、DATABASE1或 DATABASE1.TABLE1 的写入权限，直到匹配成功或者匹配失败。 +* 权限类型、范围及效果逻辑关系如下表所示： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限类型权限范围（层级）权限效果
CREATEANY允许创建任意表、创建任意数据库
数据库允许用户在该数据库下创建表;允许用户创建该名称的数据库
表允许用户创建该名称的表
DROPANY允许删除任意表、删除任意数据库
数据库允许用户删除该数据库;允许用户删除该数据库下的表
表D允许用户删除该表
ALTERANY允许修改任意表的定义、任意数据库的定义
数据库允许用户修改数据库的定义，允许用户修改数据库下表的定义
表允许用户修改表的定义
SELECTANY允许查询系统内任意数据库中任意表的数据
数据库允许用户查询该数据库中任意表的数据
表允许用户查询该表中的数据。执行多表查询时，数据库仅展示用户有权限访问的数据。
INSERTANY允许任意数据库的任意表插入/更新数据
数据库允许用户向该数据库范围内任意表插入/更新数据
表允许用户向该表中插入/更新数据
DELETEANY允许删除任意表的数据
数据库允许用户删除该数据库范围内的数据
表允许用户删除该表中的数据
+ +### 3.3 权限授予与取消 + +IoTDB支持通过如下三种途径进行用户授权和撤销权限： + +* 超级管理员直接授予或撤销 +* 拥有GRANT OPTION权限的用户授予或撤销 +* 通过角色授予或撤销（由超级管理员或具备 SECURITY 权限的用户操作角色） + +在IoTDB 表模型中，授权或撤销权限时需遵循以下原则： + +* 授权/撤销全局权限时，无需指定权限的范围。 +* 授予/撤销数据权限时，需要指定权限类型和权限范围。在撤销权限时只会撤销指定的权限范围，不会受权限范围包含关系的影响。 +* 允许对尚未创建的数据库或表提前进行权限规划和授权。 +* 允许重复授权/撤销权限。 +* WITH GRANT OPTION: 允许用户在授权范围内管理权限。用户可以授予或撤销其他用户在该范围内的权限。 + +## 4. 功能语法与示例 + +### 4.1 用户与角色相关 + +1. 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'passwd'; +``` + +2. 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD +eg: ALTER USER tempuser SET PASSWORD 'newpwd'; +``` + +3. 删除用户（需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +4. 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +5. 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +6. 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +7. 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +8. 列出所有用户（需 SECURITY 权限) + +```SQL +LIST USER; +``` + +9. 列出所有的角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +10. 列出指定角色下所有用户（需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +11. 列出指定用户下的所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +12. 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER +eg: LIST PRIVILEGES OF USER tempuser; +``` + +13. 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE +eg: LIST PRIVILEGES OF ROLE actor; +``` + +### 4.2 授权与取消授权 + +#### 4.2.1 授予权限 + +1. 给用户授予管理用户的权限 + +```SQL +GRANT SECURITY TO USER +eg: GRANT SECURITY TO USER TEST_USER; +``` + +2. 给用户授予创建数据库及在数据库范围内创建表的权限，且允许用户在该范围内管理权限 + +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +eg: GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION; +``` + +3. 给角色授予查询数据库的权限 + +```SQL +GRANT SELECT ON DATABASE TO ROLE +eg: GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE; +``` + +4. 给用户授予查询表的权限 + +```SQL +GRANT SELECT ON . TO USER +eg: GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER; +``` + +5. 给角色授予查询所有数据库及表的权限 + +```SQL +GRANT SELECT ON ANY TO ROLE +eg: GRANT SELECT ON ANY TO ROLE TEST_ROLE; +``` + +6. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地授予权限。 + +```SQL +GRANT ALL TO USER TESTUSER; +-- 将用户可以获取的所有权限授予给用户,包括全局权限和 ANY 范围的所有数据权限 + +GRANT ALL ON ANY TO USER TESTUSER; +-- 将 ANY 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在所有数据库上的所有数据权限 + +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER; +-- 将 DB 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该数据库上的所有数据权限 + +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER; +-- 将 TABLE 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该表上的所有数据权限 +``` + +#### 4.2.2 撤销权限 + +1. 取消用户管理用户的权限 + +```SQL +REVOKE SECURITY FROM USER +eg: REVOKE SECURITY FROM USER TEST_USER; +``` + +2. 取消用户创建数据库及在数据库范围内创建表的权限 + +```SQL +REVOKE CREATE ON DATABASE FROM USER +eg: REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER; +``` + +3. 取消用户查询表的权限 + +```SQL +REVOKE SELECT ON . FROM USER +eg: REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER; +``` + +4. 取消用户查询所有数据库及表的权限 + +```SQL +REVOKE SELECT ON ANY FROM USER +eg: REVOKE SELECT ON ANY FROM USER TEST_USER; +``` + +5. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地撤销权限。 + +```SQL +REVOKE ALL FROM USER TESTUSER; +-- 取消用户所有的全局权限以及 ANY 范围的所有数据权限 + +REVOKE ALL ON ANY FROM USER TESTUSER; +-- 取消用户 ANY 范围的所有数据权限，不会影响 DB 范围和 TABLE 范围的权限 + +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER; +-- 取消用户在 DB 上的所有数据权限,不会影响 TABLE 权限 + +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER; +-- 取消用户在 TABLE 上的所有数据权限 +``` + +### 4.3 查看用户权限 + +每个用户都有一个权限访问列表，标识其获得的所有权限。可使用 `LIST PRIVILEGES OF USER ` 语句查看某个用户或角色的权限信息，输出格式如下： + +| ROLE | SCOPE | PRIVIVLEGE | WITH GRANT OPTION | +| ------- |---------|------------| ------------------- | +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | UPDATE | TRUE | +| ROLE1 | DB3.\* | DELETE | FALSE | +| ROLE1 | \*.\* | UPDATE | TRUE | + +其中： + +* `ROLE` 列：如果为空，则表示为该用户的自身权限。如果不为空，则表示该权限来源于被授予的角色。 +* `SCOPE` 列：表示该用户/角色的权限范围，表范围的权限表示为`DB.TABLE`，数据库范围的权限表示为`DB.*`, ANY 范围的权限表示为`*.*`。 +* `PRIVIVLEGE` 列：列出具体的权限类型。 +* `WITH GRANT OPTION` 列：如果为 TRUE，表示用户可以将自己的权限授予他人。 +* 用户或者角色可以同时具有树模型和表模型的权限，但系统会根据当前连接的模型来显示相应的权限，另一种模型下的权限则不会显示。 + +## 5. 场景示例 + +以 [示例数据](../Reference/Sample-Data.md) 内容为例，两个表的数据可能分别属于 bj、sh 两个数据中心，彼此间不希望对方获取自己的数据库数据，因此我们需要将不同的数据在数据中心层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 `bj_write_user`, `sh_write_user`，密码均为 write_pwd。SQL 语句为： + +```SQL +CREATE USER bj_write_user 'write_pwd'; +CREATE USER sh_write_user 'write_pwd'; +``` + +使用展示用户的 SQL 语句： + +```SQL +LIST USER +``` + +可以看到这两个已经被创建的用户，结果如下： + +```SQL ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 赋予用户权限 + +虽然两个用户已经创建，但是不具有任何权限，因此并不能对数据库进行操作，例如使用 `bj_write_user` 用户对 table1 中的数据进行写入，SQL 语句为： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: database is not specified +IoTDB> use database1 +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +root 用户使用 `GRANT ON TO USER ` 语句赋予用户`bj_write_user`对 table1 的写入权限，例如： + +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +使用`bj_write_user`再尝试写入数据 + +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销`bj_write_user`和`sh_write_user`的权限： + +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +撤销权限后，`bj_write_user`就没有向table1写入数据的权限了。 + +```SQL +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_timecho.md b/src/zh/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..94334ce70 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,539 @@ + + +# 权限管理 + +IoTDB 提供了权限管理功能，用于对数据和集群系统执行精细的访问控制，保障数据与系统安全。本篇介绍了 IoTDB 表模型中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户 root，默认密码为 TimechoDB@2021。该用户为管理员用户，拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +* 4\~32个字符，支持使用英文大小写字母、数字、特殊字符`（!@#$%^&*()_+-=）`，用户无法创建和管理员用户同名的用户。 +* 如果用户名全是数字或包含特殊字符，则创建时需要使用双引号`""`括起来。 + +### 2.2 密码限制 + +12~32个字符，必须包含大写小写字母、至少一个数字、至少一个特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4\~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 表模型主要有两类权限：全局权限、数据权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY、AUDIT 三种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 +* AUDIT ：只具备维护审计规则、查看审计日志的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEM无允许用户创建、修改、删除数据库。
无允许用户创建、修改、删除表及表视图。
无允许用户创建、删除、查看用户自定义函数。
无允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
无允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
无允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER-允许用户创建、删除用户 允许用户修改用户密码 允许用户查看用户的权限信息 允许用户列出所有用户
MANAGE_ROLE-允许用户创建、删除角色 允许用户查看角色的权限信息 允许用户将角色授予某个用户或撤销 允许用户列出所有角色
AUDIT无允许用户维护审计日志的规则 允许用户查看审计日志
+ +### 3.2 数据权限 + +数据权限由权限类型和范围组成。 + +* 权限类型包括：CREATE（创建权限），DROP（删除权限），ALTER（修改权限），SELECT（查询数据权限），INSERT（插入/更新数据权限），DELETE（删除数据权限）。 +* 范围包括：ANY（系统范围内），DATABASE（数据库范围内），TABLE（单个表）。 + * 作用于 ANY 的权限会影响所有数据库和表。 + * 作用于数据库的权限会影响该数据库及其所有表。 + * 作用于表的权限仅影响该表。 +* 范围生效说明：执行单表操作时，数据库会匹配用户权限与数据权限范围。例如，用户尝试向 DATABASE1.TABLE1 写入数据时，系统会依次检查用户是否有对 ANY、DATABASE1或 DATABASE1.TABLE1 的写入权限，直到匹配成功或者匹配失败。 +* 权限类型、范围及效果逻辑关系如下表所示： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限类型权限范围（层级）权限效果
CREATEANY允许创建任意表、创建任意数据库
数据库允许用户在该数据库下创建表;允许用户创建该名称的数据库
表允许用户创建该名称的表
DROPANY允许删除任意表、删除任意数据库
数据库允许用户删除该数据库;允许用户删除该数据库下的表
表D允许用户删除该表
ALTERANY允许修改任意表的定义、任意数据库的定义
数据库允许用户修改数据库的定义，允许用户修改数据库下表的定义
表允许用户修改表的定义
SELECTANY允许查询系统内任意数据库中任意表的数据
数据库允许用户查询该数据库中任意表的数据
表允许用户查询该表中的数据。执行多表查询时，数据库仅展示用户有权限访问的数据。
INSERTANY允许任意数据库的任意表插入/更新数据
数据库允许用户向该数据库范围内任意表插入/更新数据
表允许用户向该表中插入/更新数据
DELETEANY允许删除任意表的数据
数据库允许用户删除该数据库范围内的数据
表允许用户删除该表中的数据
+ +### 3.3 权限授予与取消 + +IoTDB支持通过如下三种途径进行用户授权和撤销权限： + +* 超级管理员直接授予或撤销 +* 拥有GRANT OPTION权限的用户授予或撤销 +* 通过角色授予或撤销（由超级管理员或具备 SECURITY 权限的用户操作角色） + +在IoTDB 表模型中，授权或撤销权限时需遵循以下原则： + +* 授权/撤销全局权限时，无需指定权限的范围。 +* 授予/撤销数据权限时，需要指定权限类型和权限范围。在撤销权限时只会撤销指定的权限范围，不会受权限范围包含关系的影响。 +* 允许对尚未创建的数据库或表提前进行权限规划和授权。 +* 允许重复授权/撤销权限。 +* WITH GRANT OPTION: 允许用户在授权范围内管理权限。用户可以授予或撤销其他用户在该范围内的权限。 + +## 4. 功能语法与示例 + +### 4.1 用户与角色相关 + +1. 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'Passwd@202604'; +``` + +2. 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD +eg: ALTER USER tempuser SET PASSWORD 'Newpwd@202604'; +``` + +3. 删除用户（需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +4. 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +5. 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +6. 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +7. 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +8. 列出所有用户（需 SECURITY 权限) + +```SQL +LIST USER; +``` + +9. 列出所有的角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +10. 列出指定角色下所有用户（需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +11. 列出指定用户下的所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +12. 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER +eg: LIST PRIVILEGES OF USER tempuser; +``` + +13. 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE +eg: LIST PRIVILEGES OF ROLE actor; +``` + +### 4.2 授权与取消授权 + +#### 4.2.1 授予权限 + +1. 给用户授予管理用户的权限 + +```SQL +GRANT SECURITY TO USER +eg: GRANT SECURITY TO USER TEST_USER; +``` + +2. 给用户授予创建数据库及在数据库范围内创建表的权限，且允许用户在该范围内管理权限 + +```SQL +GRANT CREATE ON DATABASE TO USER WITH GRANT OPTION +eg: GRANT CREATE ON DATABASE TESTDB TO USER TEST_USER WITH GRANT OPTION; +``` + +3. 给角色授予查询数据库的权限 + +```SQL +GRANT SELECT ON DATABASE TO ROLE +eg: GRANT SELECT ON DATABASE TESTDB TO ROLE TEST_ROLE; +``` + +4. 给用户授予查询表的权限 + +```SQL +GRANT SELECT ON . TO USER +eg: GRANT SELECT ON TESTDB.TESTTABLE TO USER TEST_USER; +``` + +5. 给角色授予查询所有数据库及表的权限 + +```SQL +GRANT SELECT ON ANY TO ROLE +eg: GRANT SELECT ON ANY TO ROLE TEST_ROLE; +``` + +6. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地授予权限。 + +```SQL +GRANT ALL TO USER TESTUSER; +-- 将用户可以获取的所有权限授予给用户,包括全局权限和 ANY 范围的所有数据权限 + +GRANT ALL ON ANY TO USER TESTUSER; +-- 将 ANY 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在所有数据库上的所有数据权限 + +GRANT ALL ON DATABASE TESTDB TO USER TESTUSER; +-- 将 DB 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该数据库上的所有数据权限 + +GRANT ALL ON TABLE TESTTABLE TO USER TESTUSER; +-- 将 TABLE 范围内可以获取的所有权限授予给用户，执行该语句后，用户将拥有在该表上的所有数据权限 +``` + +#### 4.2.2 撤销权限 + +1. 取消用户管理用户的权限 + +```SQL +REVOKE SECURITY FROM USER +eg: REVOKE SECURITY FROM USER TEST_USER; +``` + +2. 取消用户创建数据库及在数据库范围内创建表的权限 + +```SQL +REVOKE CREATE ON DATABASE FROM USER +eg: REVOKE CREATE ON DATABASE TEST_DB FROM USER TEST_USER; +``` + +3. 取消用户查询表的权限 + +```SQL +REVOKE SELECT ON . FROM USER +eg: REVOKE SELECT ON TESTDB.TESTTABLE FROM USER TEST_USER; +``` + +4. 取消用户查询所有数据库及表的权限 + +```SQL +REVOKE SELECT ON ANY FROM USER +eg: REVOKE SELECT ON ANY FROM USER TEST_USER; +``` + +5. ALL 语法糖：ALL 表示对象范围内所有权限，可以使用 ALL 字段灵活地撤销权限。 + +```SQL +REVOKE ALL FROM USER TESTUSER; +-- 取消用户所有的全局权限以及 ANY 范围的所有数据权限 + +REVOKE ALL ON ANY FROM USER TESTUSER; +-- 取消用户 ANY 范围的所有数据权限，不会影响 DB 范围和 TABLE 范围的权限 + +REVOKE ALL ON DATABASE TESTDB FROM USER TESTUSER; +-- 取消用户在 DB 上的所有数据权限,不会影响 TABLE 权限 + +REVOKE ALL ON TABLE TESTDB FROM USER TESTUSER; +-- 取消用户在 TABLE 上的所有数据权限 +``` + +### 4.3 查看用户权限 + +每个用户都有一个权限访问列表，标识其获得的所有权限。可使用 `LIST PRIVILEGES OF USER ` 语句查看某个用户或角色的权限信息，输出格式如下： + +| ROLE | SCOPE | PRIVIVLEGE | WITH GRANT OPTION | +| ------- |---------|------------| ------------------- | +| | DB1.TB1 | SELECT | FALSE | +| | | SECURITY | TRUE | +| ROLE1 | DB2.TB2 | UPDATE | TRUE | +| ROLE1 | DB3.\* | DELETE | FALSE | +| ROLE1 | \*.\* | UPDATE | TRUE | + +其中： + +* `ROLE` 列：如果为空，则表示为该用户的自身权限。如果不为空，则表示该权限来源于被授予的角色。 +* `SCOPE` 列：表示该用户/角色的权限范围，表范围的权限表示为`DB.TABLE`，数据库范围的权限表示为`DB.*`, ANY 范围的权限表示为`*.*`。 +* `PRIVIVLEGE` 列：列出具体的权限类型。 +* `WITH GRANT OPTION` 列：如果为 TRUE，表示用户可以将自己的权限授予他人。 +* 用户或者角色可以同时具有树模型和表模型的权限，但系统会根据当前连接的模型来显示相应的权限，另一种模型下的权限则不会显示。 + +## 5. 场景示例 + +以 [示例数据](../Reference/Sample-Data.md) 内容为例，两个表的数据可能分别属于 bj、sh 两个数据中心，彼此间不希望对方获取自己的数据库数据，因此我们需要将不同的数据在数据中心层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 `bj_write_user`, `sh_write_user`，密码均为 write_Pwd@2026。SQL 语句为： + +```SQL +CREATE USER bj_write_user 'write_Pwd@2026'; +CREATE USER sh_write_user 'write_Pwd@2026'; +``` + +使用展示用户的 SQL 语句： + +```SQL +LIST USER; +``` + +可以看到这两个已经被创建的用户，结果如下： + +```SQL ++------+-------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+-------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000|bj_write_user| -1| -1| +| 10001|sh_write_user| -1| -1| ++------+-------------+-----------------+-----------------+ +``` + +### 5.2 赋予用户权限 + +虽然两个用户已经创建，但是不具有任何权限，因此并不能对数据库进行操作，例如使用 `bj_write_user` 用户对 table1 中的数据进行写入，SQL 语句为： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +``` + +系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: database is not specified +IoTDB> use database1 +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: DATABASE database1 +``` + +root 用户使用 `GRANT ON TO USER ` 语句赋予用户`bj_write_user`对 table1 的写入权限，例如： + +```SQL +GRANT INSERT ON database1.table1 TO USER bj_write_user +``` + +使用`bj_write_user`再尝试写入数据 + +```SQL +IoTDB> use database1 +Msg: The statement is executed successfully. +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销`bj_write_user`和`sh_write_user`的权限： + +```SQL +REVOKE INSERT ON database1.table1 FROM USER bj_write_user +REVOKE INSERT ON database1.table2 FROM USER sh_write_user +``` + +撤销权限后，`bj_write_user`就没有向table1写入数据的权限了。 + +```SQL +IoTDB:database1> INSERT INTO table1(region, plant_id, device_id, model_id, maintenance, time, temperature, humidity, status, arrival_time) VALUES ('北京', '1001', '100', 'A', '180', '2025-03-26 13:37:00', 190.0, 30.1, false, '2025-03-26 13:37:34') +Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 803: Access Denied: No permissions for this operation, please add privilege INSERT ON database1.table1 +``` diff --git a/src/zh/UserGuide/latest/User-Manual/Authority-Management-Upgrade_apache.md b/src/zh/UserGuide/latest/User-Manual/Authority-Management-Upgrade_apache.md new file mode 100644 index 000000000..b8e374776 --- /dev/null +++ b/src/zh/UserGuide/latest/User-Manual/Authority-Management-Upgrade_apache.md @@ -0,0 +1,474 @@ + + +# 权限管理 + +IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群系统的权限管理功能，保障数据与系统安全。本篇介绍IoTDB 中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码，作为用户成功登录。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。权限通常需要一个路径来限定其生效范围，可以使用[路径模式](../Basic-Concept/Operate-Metadata_apache.md)灵活管理权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户：root，默认密码为`root`。该用户为管理员用户，固定拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。 + +一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的用户。 + +### 2.2 密码限制 + +4~32个字符，可使用大写小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 树模型主要有两类权限：全局权限、序列权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY 两种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEMMANAGE_DATABASE允许用户创建、删除数据库.
USE_TRIGGER允许用户创建、删除、查看触发器。
USE_UDF允许用户创建、删除、查看用户自定义函数。
USE_PIPE允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
USE_CQ允许用户注册、开始、停止、卸载、查询流处理任务。允许用户注册、卸载、查询注册流处理任务插件。
EXTEND_TEMPLATE允许自动扩展模板。
MAINTAIN允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
USE_MODEL允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER允许用户创建、删除、修改、查看用户。
MANAGE_ROLE允许用户创建、删除、查看角色。允许用户将角色授予给其他用户,或取消其他用户的角色。
+ +关于模板权限： + +1. 模板的创建、删除、修改、查询、挂载、卸载仅允许管理员操作。 +2. 激活模板需要拥有激活路径的 WRITE\_SCHEMA 权限。 +3. 若开启了自动创建，在向挂载了模板的不存在路径写入时，数据库会自动扩展模板并写入数据，因此需要有 EXTEND\_TEMPLATE 权限与写入序列的 WRITE\_DATA 权限。 +4. 解除模板，需要拥有挂载模板路径的 WRITE\_SCHEMA 权限。 +5. 查询使用了某个元数据模板的路径，需要有路径的 READ\_SCHEMA 权限，否则将返回为空。 + +### 3.2 序列权限 + +序列权限约束了用户访问数据的范围与方式，支持对绝对路径与前缀匹配路径授权，可对timeseries 粒度生效。 + +下表描述了这类权限的种类与范围： + +| 权限名称 | 描述 | +| --------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| READ\_DATA | 允许读取授权路径下的序列数据。 | +| WRITE\_DATA | 允许读取授权路径下的序列数据。
允许插入、删除授权路径下的的序列数据。
允许在授权路径下导入、加载数据，在导入数据时，需要拥有对应路径的 WRITE\_DATA 权限，在自动创建数据库与序列时，需要有SYSTEM与 WRITE\_SCHEMA 权限。 | +| READ\_SCHEMA | 允许获取授权路径下元数据树的详细信息，包括：路径下的数据库、子路径、子节点、设备、序列、模版、视图等。 | +| WRITE\_SCHEMA | 允许获取授权路径下元数据树的详细信息。
允许在授权路径下对序列、模版、视图等进行创建、删除、修改操作。
在创建或修改 view 的时候，会检查 view 路径的 WRITE\_SCHEMA 权限、数据源的 READ\_SCHEMA 权限。
在对 view 进行查询、插入时，会检查 view 路径的 READ\_DATA 权限、WRITE\_DATA 权限。
允许在授权路径下设置、取消、查看TTL。
允许在授权路径下挂载或者接触挂载模板。 | + +### 3.3 权限授予与取消 + +在 IoTDB 中，用户可以由三种途径获得权限： + +1. 由超级管理员授予，超级管理员可以控制其他用户的权限。 +2. 由允许权限授权的用户授予，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者有 SECURITY 的用户授予某个角色进而获取权限。 + +取消用户的权限，可以由以下几种途径： + +1. 由超级管理员取消用户的权限。 +2. 由允许权限授权的用户取消权限，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者 SECURITY 的用户取消用户的某个角色进而取消权限。 + +* 在授权时，必须指定路径。全局权限需要指定为 root.\*\*, 而序列相关权限必须为绝对路径或者以双通配符结尾的前缀路径。 +* 当授予角色权限时，可以为该权限指定 with grant option 关键字，意味着用户可以转授其授权路径上的权限，也可以取消其他用户的授权路径上的权限。例如用户 A 在被授予`集团1.公司1.**`的读权限时制定了 grant option 关键字，那么 A 可以将`集团1.公司1`以下的任意节点、序列的读权限转授给他人， 同样也可以取消其他用户 `集团1.公司1` 下任意节点的读权限。 +* 在取消授权时，取消授权语句会与用户所有的权限路径进行匹配，将匹配到的权限路径进行清理，例如用户A 具有 `集团1.公司1.工厂1 `的读权限， 在取消 `集团1.公司1.** `的读权限时，会清除用户A 的 `集团1.公司1.工厂1` 的读权限。 + +## 4. 功能语法与示例 + +IoTDB 提供了组合权限，方便用户授权： + +| 权限名称 | 权限范围 | +| ---------- | ---------------------------- | +| ALL | 所有权限 | +| READ | READ\_SCHEMA、READ\_DATA | +| WRITE | WRITE\_SCHEMA、WRITE\_DATA | + +组合权限并不是一种具体的权限，而是一种简写方式，与直接书写对应的权限名称没有差异。 + +下面将通过一系列具体的用例展示权限语句的用法，非管理员执行下列语句需要提前获取权限，所需的权限标记在操作描述后。 + +### 4.1 用户与角色相关 + +* 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'passwd'; +``` + +* 删除用户 (需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +* 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +* 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +* 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +* 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +* 列出所有用户 (需 SECURITY 权限) + +```SQL +LIST USER; +``` + +* 列出所有角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +* 列出指定角色下所有用户 (需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +* 列出指定用户下所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +* 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER ; +eg: LIST PRIVILEGES OF USER tempuser; +``` + +* 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE ; +eg: LIST PRIVILEGES OF ROLE actor; +``` + +* 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD ; +eg: ALTER USER tempuser SET PASSWORD 'newpwd'; +``` + +### 4.2 授权与取消授权 + +用户使用授权语句对赋予其他用户权限，语法如下： + +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]； +eg: GRANT READ ON root.** TO ROLE role1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +eg: GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +用户使用取消授权语句可以将其他的权限取消，语法如下： + +```SQL +REVOKE ON FROM ROLE/USER ; +eg: REVOKE READ ON root.** FROM ROLE role1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +eg: REVOKE SECURITY ON root.** FROM USER user1; +eg: REVOKE ALL ON root.** FROM USER user1; +``` + +* **非管理员用户执行授权/取消授权语句时，需要对`` 有`` 权限，并且该权限是被标记带有 WITH GRANT OPTION 的。** +* 在授予取消全局权限时，或者语句中包含全局权限时(ALL 展开会包含全局权限），须指定 path 为 root.\*\*。 例如，以下授权/取消授权语句是合法的： + + ```SQL + GRANT SECURITY ON root.** TO USER user1; + GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; + GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; + REVOKE SECURITY ON root.** FROM USER user1; + REVOKE SECURITY ON root.** FROM ROLE role1; + REVOKE ALL ON root.** FROM ROLE role1; + ``` + + 下面的语句是非法的： + + ```SQL + GRANT READ, SECURITY ON root.t1.** TO USER user1; + GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; + REVOKE ALL ON root.t1.t2 FROM USER user1; + REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; + ``` +* `` 必须为全路径或者以双通配符结尾的匹配路径，以下路径是合法的: + + ```SQL + root.** + root.t1.t2.** + root.t1.t2.t3 + ``` + + 以下的路径是非法的： + + ```SQL + root.t1.* + root.t1.**.t2 + root.t1*.t2.t3 + ``` + +## 5. 场景示例 + +根据本文中描述的 [样例数据](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt) 内容，IoTDB 的样例数据可能同时属于 ln, sgcc 等不同发电集团，不同的发电集团不希望其他发电集团获取自己的数据库数据，因此我们需要将不同的数据在集团层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，我们可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 ln\_write\_user, sgcc\_write\_user，密码均为 write_pwd。建议使用反引号(\`)包裹用户名。SQL 语句为： + +```SQL +CREATE USER `ln_write_user` 'write_pwd'; +CREATE USER `sgcc_write_user` 'write_pwd'; +``` + +此时使用展示用户的 SQL 语句： + +```SQL +LIST USER; +``` + +我们可以看到这两个已经被创建的用户，结果如下： + +```SQL +IoTDB> CREATE USER `ln_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_pwd'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 赋予用户权限 + +此时，虽然两个用户已经创建，但是他们不具有任何权限，因此他们并不能对数据库进行操作，例如我们使用 ln\_write\_user 用户对数据库中的数据进行写入，SQL 语句为： + +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +此时，系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +现在，我们用 root 用户分别赋予他们向对应路径的写入权限. + +我们使用 `GRANT ON TO USER ` 语句赋予用户权限,例如： + +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +接着使用ln\_write\_user再尝试写入数据 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，我们可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销ln\_write\_user和sgcc\_write\_user的权限： + +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +撤销权限后，ln\_write\_user就没有向root.ln.\*\*写入数据的权限了。 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. 鉴权及其他 + +### 6.1 鉴权 + +用户权限主要由三部分组成：权限生效范围（路径）， 权限类型， with grant option 标记： + +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +每个用户都有一个这样的权限访问列表，标识他们获得的所有权限，可以通过 `LIST PRIVILEGES OF USER ` 查看他们的权限。 + +在对一个路径进行鉴权时，数据库会进行路径与权限的匹配。例如检查 `root.t1.t2` 的 read\_schema 权限时，首先会与权限访问列表的 `root.t1.**`进行匹配，匹配成功，则检查该路径是否包含待鉴权的权限，否则继续下一条路径-权限的匹配，直到匹配成功或者匹配结束。 + +在进行多路径鉴权时，对于多路径查询任务，数据库只会将有权限的数据呈现出来，无权限的数据不会包含在结果中；对于多路径写入任务，数据库要求必须所有的目标序列都获得了对应的权限，才能进行写入。 + +请注意，下面的操作需要检查多重权限 + +1. 开启了自动创建序列功能，在用户将数据插入到不存在的序列中时，不仅需要对应序列的写入权限，还需要序列的元数据修改权限。 +2. 执行 select into 语句时，需要检查源序列的读权限与目标序列的写权限。需要注意的是源序列数据可能因为权限不足而仅能获取部分数据，目标序列写入权限不足时会报错终止任务。 +3. View 权限与数据源的权限是独立的，向 view 执行读写操作仅会检查 view 的权限，而不再对源路径进行权限校验。 + +### 6.2 其他说明 + +角色是权限的集合，而权限和角色都是用户的一种属性。即一个角色可以拥有若干权限。一个用户可以拥有若干角色与权限（称为用户自身权限）。 + +目前在 IoTDB 中并不存在相互冲突的权限，因此一个用户真正具有的权限是用户自身权限与其所有的角色的权限的并集。即要判定用户是否能执行某一项操作，就要看用户自身权限或用户的角色的所有权限中是否有一条允许了该操作。用户自身权限与其角色权限，他的多个角色的权限之间可能存在相同的权限，但这并不会产生影响。 + +需要注意的是：如果一个用户自身有某种权限（对应操作 A），而他的某个角色有相同的权限。那么如果仅从该用户撤销该权限无法达到禁止该用户执行操作 A 的目的，还需要从这个角色中也撤销对应的权限，或者从这个用户将该角色撤销。同样，如果仅从上述角色将权限撤销，也不能禁止该用户执行操作 A。 + +同时，对角色的修改会立即反映到所有拥有该角色的用户上，例如对角色增加某种权限将立即使所有拥有该角色的用户都拥有对应权限，删除某种权限也将使对应用户失去该权限（除非用户本身有该权限）。 diff --git a/src/zh/UserGuide/latest/User-Manual/Authority-Management-Upgrade_timecho.md b/src/zh/UserGuide/latest/User-Manual/Authority-Management-Upgrade_timecho.md new file mode 100644 index 000000000..2733e772c --- /dev/null +++ b/src/zh/UserGuide/latest/User-Manual/Authority-Management-Upgrade_timecho.md @@ -0,0 +1,468 @@ + + +# 权限管理 + +IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群系统的权限管理功能，保障数据与系统安全。本篇介绍IoTDB 中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。 + +## 1. 基本概念 + +### 1.1 用户 + +用户即数据库的合法使用者。一个用户与一个唯一的用户名相对应，并且拥有密码作为身份验证的手段。一个人在使用数据库之前，必须先提供合法的（即存于数据库中的）用户名与密码，作为用户成功登录。 + +### 1.2 权限 + +数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。权限通常需要一个路径来限定其生效范围，可以使用[路径模式](../Basic-Concept/Operate-Metadata_timecho.md)灵活管理权限。 + +### 1.3 角色 + +角色是若干权限的集合，并且有一个唯一的角色名作为标识符。角色通常和一个现实身份相对应（例如交通调度员），而一个现实身份可能对应着多个用户。这些具有相同现实身份的用户往往具有相同的一些权限，角色就是为了能对这样的权限进行统一的管理的抽象。 + +### 1.4 默认用户与角色 + +安装初始化后的 IoTDB 中有一个默认用户：root，默认密码为`TimechoDB@2021`。该用户为管理员用户，固定拥有所有权限，无法被赋予、撤销权限，也无法被删除，数据库内仅有一个管理员用户。 + +一个新创建的用户或角色不具备任何权限。 + +## 2. 用户定义 + +拥有 SECURITY 的用户可以创建用户或者角色，需要满足以下约束： + +### 2.1 用户名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的用户。 + +### 2.2 密码限制 + +12~32个字符，必须包含大写小写字母、至少一个数字、至少一个特殊字符（`!@#$%^&*()_+-=`）且不能与用户名相同。 + +### 2.3 角色名限制 + +4~32个字符，支持使用英文大小写字母、数字、特殊字符（`!@#$%^&*()_+-=`）。用户无法创建和管理员用户同名的角色。 + +## 3. 权限管理 + +IoTDB 树模型主要有两类权限：全局权限、序列权限。 + +### 3.1 全局权限 + +全局权限包含 SYSTEM、SECURITY、AUDIT 三种类型： + +* SYSTEM：只具备运维操作、DDL（Data Definition Language）相关的权限。 +* SECURITY：只具备管理角色（Role）或用户（User）以及为其他账号授予权限的权限。 +* AUDIT ：只具备维护审计规则、查看审计日志的权限。 + +各权限详细描述见下表： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
权限名称原权限名称描述
SYSTEMMANAGE_DATABASE允许用户创建、删除数据库.
USE_TRIGGER允许用户创建、删除、查看触发器。
USE_UDF允许用户创建、删除、查看用户自定义函数。
USE_PIPE允许用户创建、开始、停止、删除、查看 PIPE。允许用户创建、删除、查看 PIPEPLUGINS。
USE_CQ允许用户注册、开始、停止、卸载、查询流处理任务。允许用户注册、卸载、查询注册流处理任务插件。
MAINTAIN允许用户查询、取消查询。允许用户查看变量。允许用户查看集群状态。
USE_MODEL允许用户创建、删除、查询深度学习模型
SECURITYMANAGE_USER允许用户创建、删除、修改、查看用户。
MANAGE_ROLE允许用户创建、删除、查看角色。允许用户将角色授予给其他用户,或取消其他用户的角色。
AUDIT无允许用户维护审计日志的规则 允许用户查看审计日志
+ +### 3.2 序列权限 + +序列权限约束了用户访问数据的范围与方式，支持对绝对路径与前缀匹配路径授权，可对timeseries 粒度生效。 + +下表描述了这类权限的种类与范围： + +| 权限名称 | 描述 | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| READ\_DATA | 允许读取授权路径下的序列数据。 | +| WRITE\_DATA | 允许读取授权路径下的序列数据。
允许插入、删除授权路径下的的序列数据。
允许在授权路径下导入、加载数据，在导入数据时，需要拥有对应路径的 WRITE\_DATA 权限，在自动创建数据库与序列时，需要有SYSTEM与 WRITE\_SCHEMA 权限。 | +| READ\_SCHEMA | 允许获取授权路径下元数据树的详细信息，包括：路径下的数据库、子路径、子节点、设备、序列、模版、视图等。 | +| WRITE\_SCHEMA | 允许获取授权路径下元数据树的详细信息。
允许在授权路径下对序列、模版、视图等进行创建、删除、修改操作。
在创建或修改 view 的时候，会检查 view 路径的 WRITE\_SCHEMA 权限、数据源的 READ\_SCHEMA 权限。
在对 view 进行查询、插入时，会检查 view 路径的 READ\_DATA 权限、WRITE\_DATA 权限。
允许在授权路径下设置、取消、查看TTL。
允许在授权路径下挂载或者接触挂载模板。
允许在授权路径下对序列进行全路径名称的修改操作。//V2.0.8.2 起支持该功能 | + +### 3.3 权限授予与取消 + +在 IoTDB 中，用户可以由三种途径获得权限： + +1. 由超级管理员授予，超级管理员可以控制其他用户的权限。 +2. 由允许权限授权的用户授予，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者有 SECURITY 的用户授予某个角色进而获取权限。 + +取消用户的权限，可以由以下几种途径： + +1. 由超级管理员取消用户的权限。 +2. 由允许权限授权的用户取消权限，该用户获得权限时被指定了 grant option 关键字。 +3. 由超级管理员或者 SECURITY 的用户取消用户的某个角色进而取消权限。 + +* 在授权时，必须指定路径。全局权限需要指定为 root.\*\*, 而序列相关权限必须为绝对路径或者以双通配符结尾的前缀路径。 +* 当授予角色权限时，可以为该权限指定 with grant option 关键字，意味着用户可以转授其授权路径上的权限，也可以取消其他用户的授权路径上的权限。例如用户 A 在被授予`集团1.公司1.**`的读权限时制定了 grant option 关键字，那么 A 可以将`集团1.公司1`以下的任意节点、序列的读权限转授给他人， 同样也可以取消其他用户 `集团1.公司1` 下任意节点的读权限。 +* 在取消授权时，取消授权语句会与用户所有的权限路径进行匹配，将匹配到的权限路径进行清理，例如用户A 具有 `集团1.公司1.工厂1 `的读权限， 在取消 `集团1.公司1.** `的读权限时，会清除用户A 的 `集团1.公司1.工厂1` 的读权限。 + +## 4. 功能语法与示例 + +IoTDB 提供了组合权限，方便用户授权： + +| 权限名称 | 权限范围 | +| ---------- | ---------------------------- | +| ALL | 所有权限 | +| READ | READ\_SCHEMA、READ\_DATA | +| WRITE | WRITE\_SCHEMA、WRITE\_DATA | + +组合权限并不是一种具体的权限，而是一种简写方式，与直接书写对应的权限名称没有差异。 + +下面将通过一系列具体的用例展示权限语句的用法，非管理员执行下列语句需要提前获取权限，所需的权限标记在操作描述后。 + +### 4.1 用户与角色相关 + +* 创建用户（需 SECURITY 权限) + +```SQL +CREATE USER +eg: CREATE USER user1 'Passwd@202604'; +``` + +* 删除用户 (需 SECURITY 权限) + +```SQL +DROP USER +eg: DROP USER user1; +``` + +* 创建角色 (需 SECURITY 权限) + +```SQL +CREATE ROLE +eg: CREATE ROLE role1; +``` + +* 删除角色 (需 SECURITY 权限) + +```SQL +DROP ROLE +eg: DROP ROLE role1; +``` + +* 赋予用户角色 (需 SECURITY 权限) + +```SQL +GRANT ROLE TO +eg: GRANT ROLE admin TO user1; +``` + +* 移除用户角色 (需 SECURITY 权限) + +```SQL +REVOKE ROLE FROM +eg: REVOKE ROLE admin FROM user1; +``` + +* 列出所有用户 (需 SECURITY 权限) + +```SQL +LIST USER; +``` + +* 列出所有角色 (需 SECURITY 权限) + +```SQL +LIST ROLE; +``` + +* 列出指定角色下所有用户 (需 SECURITY 权限) + +```SQL +LIST USER OF ROLE +eg: LIST USER OF ROLE roleuser; +``` + +* 列出指定用户下所有角色 + +用户可以列出自己的角色，但列出其他用户的角色需要拥有 SECURITY 权限。 + +```SQL +LIST ROLE OF USER +eg: LIST ROLE OF USER tempuser; +``` + +* 列出用户所有权限 + +用户可以列出自己的权限信息，但列出其他用户的权限需要拥有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF USER ; +eg: LIST PRIVILEGES OF USER tempuser; +``` + +* 列出角色所有权限 + +用户可以列出自己具有的角色的权限信息，列出其他角色的权限需要有 SECURITY 权限。 + +```SQL +LIST PRIVILEGES OF ROLE ; +eg: LIST PRIVILEGES OF ROLE actor; +``` + +* 修改密码 + +用户可以修改自己的密码，但修改其他用户密码需要具备 SECURITY 权限。 + +```SQL +ALTER USER SET PASSWORD ; +eg: ALTER USER tempuser SET PASSWORD 'Newpwd@202604'; +``` + +### 4.2 授权与取消授权 + +用户使用授权语句对赋予其他用户权限，语法如下： + +```SQL +GRANT ON TO ROLE/USER [WITH GRANT OPTION]； +eg: GRANT READ ON root.** TO ROLE role1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1; +eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1; +eg: GRANT SECURITY ON root.** TO USER user1 WITH GRANT OPTION; +eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION; +``` + +用户使用取消授权语句可以将其他的权限取消，语法如下： + +```SQL +REVOKE ON FROM ROLE/USER ; +eg: REVOKE READ ON root.** FROM ROLE role1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1; +eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1; +eg: REVOKE SECURITY ON root.** FROM USER user1; +eg: REVOKE ALL ON root.** FROM USER user1; +``` + +* **非管理员用户执行授权/取消授权语句时，需要对`` 有`` 权限，并且该权限是被标记带有 WITH GRANT OPTION 的。** +* 在授予取消全局权限时，或者语句中包含全局权限时(ALL 展开会包含全局权限），须指定 path 为 root.\*\*。 例如，以下授权/取消授权语句是合法的： + + ```SQL + GRANT SECURITY ON root.** TO USER user1; + GRANT SECURITY ON root.** TO ROLE role1 WITH GRANT OPTION; + GRANT ALL ON root.** TO role role1 WITH GRANT OPTION; + REVOKE SECURITY ON root.** FROM USER user1; + REVOKE SECURITY ON root.** FROM ROLE role1; + REVOKE ALL ON root.** FROM ROLE role1; + ``` + + 下面的语句是非法的： + + ```SQL + GRANT READ, SECURITY ON root.t1.** TO USER user1; + GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION; + REVOKE ALL ON root.t1.t2 FROM USER user1; + REVOKE READ, SECURITY ON root.t1.t2 FROM ROLE ROLE1; + ``` +* `` 必须为全路径或者以双通配符结尾的匹配路径，以下路径是合法的: + + ```SQL + root.** + root.t1.t2.** + root.t1.t2.t3 + ``` + + 以下的路径是非法的： + + ```SQL + root.t1.* + root.t1.**.t2 + root.t1*.t2.t3 + ``` + +## 5. 场景示例 + +根据本文中描述的 [样例数据](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt) 内容，IoTDB 的样例数据可能同时属于 ln, sgcc 等不同发电集团，不同的发电集团不希望其他发电集团获取自己的数据库数据，因此我们需要将不同的数据在集团层进行权限隔离。 + +### 5.1 创建用户 + +使用 `CREATE USER ` 创建用户。例如，我们可以使用具有所有权限的root用户为 ln 和 sgcc 集团创建两个用户角色，名为 ln\_write\_user, sgcc\_write\_user，密码均为 write_Pwd@2026。建议使用反引号(\`)包裹用户名。SQL 语句为： + +```SQL +CREATE USER `ln_write_user` 'write_Pwd@2026'; +CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +``` + +此时使用展示用户的 SQL 语句： + +```SQL +LIST USER; +``` + +我们可以看到这两个已经被创建的用户，结果如下： + +```SQL +IoTDB> CREATE USER `ln_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> CREATE USER `sgcc_write_user` 'write_Pwd@2026'; +Msg: The statement is executed successfully. +IoTDB> LIST USER; ++------+---------------+-----------------+-----------------+ +|UserId| User|MaxSessionPerUser|MinSessionPerUser| ++------+---------------+-----------------+-----------------+ +| 0| root| -1| 1| +| 10000| ln_write_user| -1| -1| +| 10001|sgcc_write_user| -1| -1| ++------+---------------+-----------------+-----------------+ +Total line number = 3 +It costs 0.005s +``` + +### 5.2 赋予用户权限 + +此时，虽然两个用户已经创建，但是他们不具有任何权限，因此他们并不能对数据库进行操作，例如我们使用 ln\_write\_user 用户对数据库中的数据进行写入，SQL 语句为： + +```SQL +INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +``` + +此时，系统不允许用户进行此操作，会提示错误： + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +现在，我们用 root 用户分别赋予他们向对应路径的写入权限. + +我们使用 `GRANT ON TO USER ` 语句赋予用户权限,例如： + +```SQL +GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +接着使用ln\_write\_user再尝试写入数据 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: The statement is executed successfully. +``` + +### 5.3 撤销用户权限 + +授予用户权限后，我们可以使用 `REVOKE ON FROM USER `来撤销已经授予用户的权限。例如，用root用户撤销ln\_write\_user和sgcc\_write\_user的权限： + +```SQL +REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +``` + +执行状态如下所示： + +```SQL +IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`; +Msg: The statement is executed successfully. +IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`; +Msg: The statement is executed successfully. +``` + +撤销权限后，ln\_write\_user就没有向root.ln.\*\*写入数据的权限了。 + +```SQL +IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true); +Msg: 803: No permissions for this operation, please add privilege WRITE_DATA on [root.ln.wf01.wt01.status] +``` + +## 6. 鉴权及其他 + +### 6.1 鉴权 + +用户权限主要由三部分组成：权限生效范围（路径）， 权限类型， with grant option 标记： + +```Plain +userTest1 : + root.t1.** - read_schema, read_data - with grant option + root.** - write_schema, write_data - with grant option +``` + +每个用户都有一个这样的权限访问列表，标识他们获得的所有权限，可以通过 `LIST PRIVILEGES OF USER ` 查看他们的权限。 + +在对一个路径进行鉴权时，数据库会进行路径与权限的匹配。例如检查 `root.t1.t2` 的 read\_schema 权限时，首先会与权限访问列表的 `root.t1.**`进行匹配，匹配成功，则检查该路径是否包含待鉴权的权限，否则继续下一条路径-权限的匹配，直到匹配成功或者匹配结束。 + +在进行多路径鉴权时，对于多路径查询任务，数据库只会将有权限的数据呈现出来，无权限的数据不会包含在结果中；对于多路径写入任务，数据库要求必须所有的目标序列都获得了对应的权限，才能进行写入。 + +请注意，下面的操作需要检查多重权限 + +1. 开启了自动创建序列功能，在用户将数据插入到不存在的序列中时，不仅需要对应序列的写入权限，还需要序列的元数据修改权限。 +2. 执行 select into 语句时，需要检查源序列的读权限与目标序列的写权限。需要注意的是源序列数据可能因为权限不足而仅能获取部分数据，目标序列写入权限不足时会报错终止任务。 +3. View 权限与数据源的权限是独立的，向 view 执行读写操作仅会检查 view 的权限，而不再对源路径进行权限校验。 + +### 6.2 其他说明 + +角色是权限的集合，而权限和角色都是用户的一种属性。即一个角色可以拥有若干权限。一个用户可以拥有若干角色与权限（称为用户自身权限）。 + +目前在 IoTDB 中并不存在相互冲突的权限，因此一个用户真正具有的权限是用户自身权限与其所有的角色的权限的并集。即要判定用户是否能执行某一项操作，就要看用户自身权限或用户的角色的所有权限中是否有一条允许了该操作。用户自身权限与其角色权限，他的多个角色的权限之间可能存在相同的权限，但这并不会产生影响。 + +需要注意的是：如果一个用户自身有某种权限（对应操作 A），而他的某个角色有相同的权限。那么如果仅从该用户撤销该权限无法达到禁止该用户执行操作 A 的目的，还需要从这个角色中也撤销对应的权限，或者从这个用户将该角色撤销。同样，如果仅从上述角色将权限撤销，也不能禁止该用户执行操作 A。 + +同时，对角色的修改会立即反映到所有拥有该角色的用户上，例如对角色增加某种权限将立即使所有拥有该角色的用户都拥有对应权限，删除某种权限也将使对应用户失去该权限（除非用户本身有该权限）。