Docs

Cloud Native Message Engine

Create client authentication

Create password-based authentication

This topic describes the steps for creating password-based authentication in the MQTT Dashboard.

Prerequisites

When using MySQL as the data source, please ensure the following:

Create a MySQL instance, database and account, and data table to store client authentication information. For detailed steps, see Create a MySQL instance and Create a database and account. For an example of the MySQL data table structure, see SQL table structure and query statements.

The target MySQL instance is running.

Note

For related cautions, see Caution.

Operation steps

In the Dashboard navigation bar, select Access Control > Client Authentication, then click Create in the upper right corner of the page.

Select the Password-Based authentication method, then click Next.

Select the data source, then click Next.

On the Configure parameters wizard page, configure the parameters, and after completing the parameter configuration, click Create.

The parameters to be configured vary depending on the selected data source.

Create built-in database authentication

Parameters	Description
Account type	Specify the field for client identity ID authentication; you may select username or clientid according to business requirements.
Password encryption method	Select the hash algorithm used to store the password, such as plain, md5, sha, bcrypt, pbkdf2, and many other. Selecting different encryption methods requires configuring different parameters. Select the plain, md5, or sha encryption method You need to configure the salting method to specify the combination method of salt and password. Generally, this does not need to be changed. Options include: disable: Do not enable prefix: Add salt to the beginning of the password suffix: Add salt to the end of the password Select the bcrypt encryption method You need to configure Salt Rounds to specify the number of computations required for hashing, also known as the cost factor. The higher the value, the greater the security of encryption, but the time required for user authentication will also increase. Please configure based on your business requirements. Select the pkbdf2 encryption method The following parameters need to be configured: Pseudorandom function: Specifies the hash function used to generate the key, such as sha256. Number of iterations: Specifies the number of hash iterations. The default value is 4096. Key length: Specifies the desired key length. If not specified, the key length will be determined by the pseudorandom function.

Create MySQL authentication

Parameters	Description
Service	Enter the private network access address of the MySQL instance to be queried. The format is {private domain}:{port}.
Database	Enter the name of the database to be queried.
Username	Enter the username. warning Ensure that the corresponding user has read and write permissions for the specified database.
Password	Enter the password.
Enable TLS	Configure whether to enable TLS verification and whether to verify the server certificate. If verification is required, configure Cert and Key separately.
Connection pool size	Configure the Connections number for MQTT to the specified MySQL database. The default value is 8; you may configure other integer values according to business requirements.
Query timeout	Specify the connection timeout duration. The default is 5 seconds. You can configure other integer values based on your business requirements. Available units: milliseconds, seconds, minutes, hours.
Password encryption method	Select the hash algorithm used to store the password, such as plain, md5, sha, bcrypt, pbkdf2, and many other. Selecting different encryption methods requires configuring different parameters.
Select the plain, md5, sha, sha256, or sha512 encryption method	Salting method: Used to specify the combination method of salt and password; generally, this option does not need to be changed. disable: Do not enable prefix: Add salt to the beginning of the password suffix: Add salt to the end of the password
Select the pbkdf2 encryption method	Pseudorandom function: Specifies the hash function used to generate the key, such as sha256. Iteration count: Specifies the number of hash iterations; the default value is 4096. Key length: Specifies the desired key length. If not specified, the key length will be determined by the pseudorandom function.
SQL	Based on the table structure, write the SQL query statement. For specific requirements, see SQL table structure and query statements.

SQL table structure and query statements

MQTT supports multiple MySQL table structures, joint queries across multiple table structures, or queries from views. You only need to provide a query SQL template, ensuring that the query result contains the following fields:

Field	Description
password_hash	Plaintext or hashed password field in the database.
salt (optional)	If empty or not present, it is considered as an empty salt (salt = "").
is_superuser (optional)	Indicate whether the current client is a superuser. The possible values are as follows: true: Superuser. false (default): Not a superuser.

Example table structure

Create the following table structure in the specified database:

CREATE TABLE `mqtt_user` (
`id` int(11) unsigned NOT NULL AUTO_INCREMENT,
`username` varchar(100) DEFAULT NULL,
`password_hash` varchar(100) DEFAULT NULL,
`salt` varchar(35) DEFAULT NULL,
`is_superuser` tinyint(1) DEFAULT 0,
`created` datetime DEFAULT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `mqtt_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

tip

In the above example, a UNIQUE index field (username) is created to facilitate queries. When there are a large number of users in the system, ensure that the table used for queries is optimized and uses effective indexes to improve data lookup speed for large numbers of connections and reduce MQTT load.

Add authentication information

The following is an example of adding authentication information to the mqtt_user table:

Authentication information: The username is mqtt_u1, the password is password0123, the salt value is slat_foo123, the hash method is sha256, and the superuser flag is true.

mysql> INSERT INTO mqtt_user(username, password_hash, salt, is_superuser) VALUES ('mqtt_u1', SHA2(concat('password0123', 'slat_foo123'), 256), 'slat_foo123', 1);
Query OK, 1 row affected (0,01 sec)

SQL query statement

Using {username} as the query condition, the following query statement retrieves client authentication information from the mqtt_acl table:

SELECT password_hash, salt, is_superuser FROM mqtt_user WHERE username = ${username} LIMIT 1

Last updated: 2026.01.26 16:15:20