Docs

Cloud Native Message Engine

Client authentication

Client authentication overview

This document describes the client authentication methods supported by MQTT, considerations for creating authentication, and information about authentication chains.

Authentication methods

MQTT Dashboard provides out-of-the-box client authentication and permission management functionality. You can quickly configure the client authentication and authorization mechanism in the Dashboard visual interface, without writing code or manually editing configuration files, and seamlessly connect to various data sources and authentication services.

Currently, MQTT offers three client authentication methods, which you can select according to your business needs.

Password-Based

Authentication using client ID or username + password. When an MQTT client attempts to connect to an MQTT instance, it must provide identity credential information. MQTT will initiate a query in the specified data source and match the returned password with the identity information provided by the client. If the match is successful, the client request will be accepted.

The Password-Based authentication method supports integration with data sources including built-in database and MySQL.

Token-based authentication mechanism. With the JWT authentication method, no additional data source is required to store client authentication information,

The client can carry a JWT token in the username or password field, and MQTT verifies the JWT signature using a preconfigured secret key or public key.

SCRAM

MQTT enhanced authentication method, supports storing authentication data in the built-in database, and enables mutual authentication between client and server.

MQTT authenticators

Based on authentication method and data source, MQTT provides the following four built-in authenticators. You can click the links in the table below to view the creation steps for each authenticator.

Authentication method	Data source	Authenticator creation steps
Password-Based	Built-in database	Create Password-Based authentication
Password-Based		Create Password-Based authentication	MySQL
JWT	-	Create JWT authentication
SCRAM	Built-in database	Create SCRAM authentication

Note

By default, MQTT authentication is not enabled, which allows all clients to connect. However, there may be some unauthorized clients, so it is recommended to configure at least one authentication method in advance.

A single MQTT instance supports creating up to two authenticators.

The types of authenticators created in a single MQTT instance cannot be duplicated.

After creating an authenticator, the MQTT client must configure the corresponding authentication information in order to securely connect to MQTT.

The authentication data source must be in the same VPC as the MQTT instance.

Authentication process

A single MQTT instance allows the creation of up to two authenticators to form an authentication chain. Authenticators are executed in the order of their position in the chain. If identity credentials are not retrieved in the current authenticator, the process will switch to the next enabled authenticator in the chain to continue authentication.

Using Password-Based authentication as an example, the authentication process is typically as follows:

When the current authenticator is executed and matching authentication information is retrieved, such as a matching username:

If the password matches exactly, the client is authenticated and allowed to connect.

If the password does not match, client authentication fails and the connection is denied.

When the current authenticator is executed and no matching authentication information is retrieved, such as no data found in the data source:

If there are additional authenticators after the current one: skip this authenticator and let the next authenticator continue authentication.

If the current authenticator is the last one in the chain: client authentication fails and the connection is denied.

Last updated: 2026.01.26 16:15:20