How do I manage users and permissions in LindormTSDB - Lindorm

You can control the permissions of users on specific databases to prevent your data being maliciously accessed or tampered by unauthorized users. This way, the security of the databases can be improved. By default, the user authentication and permission verification feature is disabled for LindormTSDB. You must manually enable the user authentication and permission verification feature. After you enable this feature, you must include user credentials in the request when you connect to LindormTSDB. Otherwise, the request fails the authentication. This topic describes how to enable the user authentication and permission verification feature, how to include user credentials in connection information, and the permissions required to execute common SQL statements and to call common API operations.

Access control in LindormTSDB

Lindorm provides a multilayer access control system to ensure the security of enterprise-level applications. Access control is performed at the following three layers:

RAM provided by Alibaba Cloud
Instances at the physical layer
For more information, see Configure whitelists.
Engines at the logical layer
Access control is implemented for engines based on user authentication and permission verification.

Usage notes

By default, an initial user is created after a Lindorm instance is created. The default username and password of the initial user are both root_tsdb. If you use LindormTSDB 3.4.30 or earlier versions, the default username and password of the initial user are both root. Change the password of the initial user immediately after the instance is created to avoid security risks.
After the user authentication and permission verification feature is enabled, running services may fail to access LindormTSDB if the requests sent by the services do not include user credentials. In this case, you must add user credentials to the requests and restart the services. Therefore, we recommend that you carefully plan and fully evaluate the impacts before you enable the feature.

Enable the user authentication and permission verification feature

By default, the user authentication and permission verification feature is disabled. You must log on to the database to enable this feature.

Procedure

ALTER SYSTEM SET USER_AUTH=TRUE;

Note

After the user authentication and permission verification feature is enabled, you can execute the ALTER SYSTEM SET USER_AUTH=FALSE; statement to disable this feature. If you disable this feature, user authentication and permission verification are not performed, which poses security risks. Therefore, we recommend that you do not disable this feature.

Check whether the user authentication and permission verification feature is enabled

SHOW PARAMETER USER_AUTH;

Add user credentials to connection information

After you enable the user authentication and permission verification feature, requests sent by applications to access LindormTSDB must include the username and password. You must have permissions on the object that you want to access when you write data to or query data from the object in LindormTSDB. This way, LindormTSDB can strictly control the access to your business and isolate required permissions.

Examples

lindorm-cli

lindorm-cli -url <Endpoint for LindormTSDB SQL> -username <Username> -password <Password> -database <Database name>

For more information, see Use Lindorm-cli to connect to and use LindormTSDB.

JDBC

String url = "<Endpoint for LindormTSDB SQL>";
String username = "<Username>";
String password = "<Password>";
Connection conn = null;

try {
    conn = DriverManager.getConnection(url, username, password);
    // Perform operations after the client is connected to LindormTSDB.
} catch (SQLException e) {
    e.printStackTrace();
}

For more information about how to use JDBC to connect to LindormTSDB, see Tutorial: Use the JDBC driver for Lindorm to connect to and use LindormTSDB.

Druid

dataSource.setDriver(DriverManager.getDriver("<Endpoint for LindormTSDB SQL>"))
dataSource.setUrl("<Endpoint for LindormTSDB SQL>")
dataSource.setUsername("<Username>")
dataSource.setPassword("<Password>")

For more information about how to use Druid to connect to LindormTSDB, see Tutorial: Use the Druid connection pool to connect to LindormTSDB.

HTTP API

If your application calls OpenTSDB-compatible HTTP API operations to access LindormTSDB, when the user authentication and permission verification feature is enabled, the requests that are sent by calling the API operations must include user credentials.

Method of specifying user credentials when calling OpenTSDB-compatible API operations to access LindormTSDB

Include Base64-encoded user credentials in HTTP request headers. The method is similar to calling common API operations to send SQL requests. For more information, see Specify user credentials for authentication.

Note

For applications that use Time Series Database (TSDB) SDKs, you can specify the username and password by calling the basicAuth method when you create a TSDBConfig object.

url = "<HTTP Endpoint for LindormTSDB>/api/v2/sql"
username = "<Username>"
password = "<Password>"
auth = HTTPBasicAuth(username, password)


headers = {
    "Content-Type": "text/plain",
    "Authorization": f"Basic {base64.b64encode(f'{username}:{password}'.encode()).decode()}"
}

For more information about how to use HTTP API operations to connect to LindormTSDB, see Request content.

For more information about the permissions that are required to call HTTP API operations, see Permissions required to call OpenTSDB-compatible API operations to access LindormTSDB.

User and permissions

Permission model

Permission type

In LindormTSDB, permissions are classified into four types. The following table describes the four types of permissions.

Permission name	Description
READ	Read permissions. To query data in tables, you must have read permissions on the tables.
WRITE	Write permissions. To write data to tables, you must have write permissions on the tables.
ADMIN	Administrative permissions. To manage data objects in LindormTSDB, you must have administrative permissions on the data objects that you want to manage.
SYSTEM	System permissions. You must have system permissions to perform operations that may affect the entire instance.

Permission scopes

LindormTSDB allows you to specify the scope of the permissions that you grant to users based on different business requirements. LindormTSDB supports the following two permission scopes:

GLOBAL
You can grant and revoke permissions on all resources globally.
If a user is granted permissions on all resources globally, the user can perform the corresponding operations on all data objects in LindormTSDB. For example, if a user is granted the READ permission on all resources globally, the user can query data in all time series tables in all databases.
DATABASE
You can grant and revoke permissions on a specified database.
If a user is granted permissions on a database, the user can perform the corresponding operations on all data objects in the database. For example, if a user is granted the READ permission on a database named DB1, the user can query data in all time series tables in the database.

Authorization rules

The scope of the SYSTEM permission is GLOBAL.
Only users that have the ADMIN permission on the GLOBAL scope or the SYSTEM permission can create, delete, and authorize users or revoke permissions from users.
The permissions of a user are the union of all permissions that are granted to the user. For example, if you have the READ permission on the GLOBAL scope and the READ permission on the DATABASE scope at the same time, you can query data in all LindormTSDB databases.

Manage users and permissions

LindormTSDB allows you to use SQL and the cluster management system of LindormTable to manage users and permissions.

Use SQL to manage users and permissions

For more information about the SQL syntax used to create a user, see CREATE USER.
For more information about the SQL syntax used to delete a user, see DROP USER.
For more information about the SQL syntax used to modify the password of a user, see ALTER USER.
For more information about the SQL syntax used to view all users, see SHOW.
For more information about the SQL syntax used to grant permissions to a user, see GRANT.
For more information about the SQL syntax used to revoke permissions from a user, see REVOKE.

Use the cluster management system to manage users and permissions

The user and permission data are shared in LindormTSDB and LindormTable. If you activate LindormTable, you can log on to the cluster management system of LindormTable to manage users and permissions. For more information about how to use the cluster management system, see Log on to the cluster management system.

Important

The cluster management system of LindormTable supports the TRASH permission. This permission is not used in LindormTSDB.
If a namespace in LindormTable has the same name as a database in LindormTSDB and a user is granted permissions on the namespace, the user has permissions to access the database with the same name in LindormTSDB by default.

Permissions required for executing common SQL statements

The following table describes the permissions required to execute common SQL statements.

Note

In the following table, ○ indicates that the permission is required, and × indicates that the permissions is not required.

SQL statements	GLOBAL				DATABASE			Description
SQL statements	READ	WRITE	ADMIN	SYSTEM	READ	WRITE	ADMIN	Description
SELECT...FROM...	○	×	×	×	○	×	×	-
INSERT INTO...VALUES...	×	○	×	×	×	○	×	-
INSERT INTO...SELECT...	○	○	×	×	○	○	×	The WRITE permission on the table to which data is inserted is required. The READ permission on the table from which data is queried is required.
DESCRIBE DATABASE ...	×	×	○	×	×	×	○	-
CREATE DATABASE...	×	×	○	×	×	×	×	-
ALTER DATABASE...	×	×	○	×	×	×	○	-
DROP DATABASE...	×	×	○	×	×	×	○	-
SHOW DATABASES	×	×	○	×	×	×	×	-
DESCRIBE TABLE ...	○	×	×	×	○	×	×	-
CREATE TABLE...	×	×	○	×	×	×	○	-
DROP TABLE...	×	×	○	×	×	×	○	-
CREATE USER	×	×	○	○	×	×	×	-
ALTER USER...	×	×	○	○	×	×	×	-
DROP USER...	×	×	○	○	×	×	×	-
SHOW USERS	×	×	○	○	×	×	×	-
GRANT...	×	×	○	○	×	×	×	-
REVOKE...	×	×	○	○	×	×	×	-
SHOW PRIVILEGES...	×	×	○	○	×	×	×	-
ALTER SYSTEM...	×	×	×	○	×	×	×	-
SHOW PARAMETER...	×	×	×	○	×	×	×	-

Permissions required to call OpenTSDB-compatible HTTP API operations

To call OpenTSDB-compatible HTTP API operations, you must have corresponding permissions on the GLOBAL scope.

The following table describes the permissions that are required to call each HTTP API operation.

Note

In the following table, ○ indicates that the permission is required, and × indicates that the permissions is not required.

API operation	GLOBAL WRITE	GLOBAL READ	GLOBAL ADMIN
/api/put	○	×	×
/api/query	×	○	×
/api/query/last	×	○	×
/api/mput	○	×	×
/api/mquery	×	○	×
/api/query/mlast	×	○	×
/api/suggest	×	○	×
/api/dump_meta	×	○	×
/api/search/lookup	×	○	×
/api/ttl	×	×	○
/api/truncate	×	×	○