This topic describes how ApsaraMQ for MQTT authenticates clients and classifies authentication modes. Use this information to select the appropriate authentication method.
How authentication works
When an ApsaraMQ for MQTT client sends or receives messages, the broker authenticates the client using the UserName and Password parameters. These parameters have different meanings depending on the authentication mode. Select the appropriate authentication mode for your use case and calculate UserName and Password according to that mode’s rules.
The following table shows how to calculate UserName and Password for each authentication mode and when to use each mode.
Authentication mode | Mode name | UserName | Password | Scenario |
Token-based authentication | Token | It consists of three parts: the authentication mode name, AccessKey ID, and Instance ID. These parts are separated by a vertical line (|). For example, if a client has ClientId GID_Test@@@0001, uses instance ID mqtt-xxxxx, and AccessKey ID YYYYY, set UserName to Token|YYYYY|mqtt-xxxxx. | For more information about the content of the uploaded Token, see Token authentication mode. | Temporary authorization. Use this mode when clients are untrusted. |
Unique-certificate-per-device authentication | DeviceCredential | It consists of three parts separated by a vertical line (|): the authentication mode name, the DeviceAccessKeyId, and the instance ID. For example, if a client has ClientId GID_Test@@@0001, uses instance ID mqtt-xxxxx, and DeviceAccessKeyId YYYYY, set UserName to DeviceCredential|YYYYY|mqtt-xxxxx. DeviceAccessKeyId is a parameter in the access credential issued by the ApsaraMQ for MQTT broker for the device. For more information, see Unique-certificate-per-device authentication. | Password is the Base64-encoded result of signing the Client ID with the DeviceAccessKey secret. For more information, see Unique-certificate-per-device authentication. | Permanent authorization. Use this mode when clients are secure and trusted, and the broker must update or disable issued device access credentials at any time. |
AccessKey ID and AccessKey secret are sensitive information. They directly affect how UserName and Password are calculated. To prevent leakage, do not embed them in client code. Instead, store them in your backend application. Let the backend calculate UserName and Password, then send the results to the client.
Authentication modes
This section describes the authentication methods supported by ApsaraMQ for MQTT and their applicable scenarios: token-based authentication, and unique-certificate-per-device authentication.
Token-based authentication (temporary permissions)
Use token-based authentication when you require fine-grained control over individual client permissions—or when you need to grant temporary, time-limited access. With tokens, you define exactly which resources a client can access, what permission level it has, and when the permission expires.
For the token-based authentication flow and important considerations, see Token-based authentication.
Scenario
Your business uses its own local account system. You need to split permissions across Alibaba Cloud accounts or RAM users—or even assign unique accounts and permissions to individual MQTT clients. The Alibaba Cloud RAM system cannot meet this requirement.
Even though all MQTT clients belong to the same Alibaba Cloud account, they must assume distinct roles tied to local accounts—such as departments or individual devices. Signature authentication, which operates at the Alibaba Cloud account level, cannot support this. Fixed permissions also fall short on mobile devices, where risks such as cracking or hijacking demand tighter, per-client control. Temporary permissions let you manage access at the finest level—down to a single resource—and expire automatically.
Using tokens
Token-based authentication is more complex. Your business must manage accounts—or devices—and track each device’s permissions and expiration times. Issue tokens from a secure, trusted management node, then deliver them to MQTT clients. For details, see Token-based authentication.
Unique-certificate-per-device authentication
Unique-certificate-per-device authentication lets each MQTT client authenticate with its own username and password. This prevents token spoofing when clients are untrusted. In this mode, usernames and passwords bind to specific Client IDs, so you can manage each client separately.
Scenario
Your business has high security requirements. In IoT-like environments where real-time token updates are impractical, this mode provides persistent authentication without frequent, passive credential updates.
Using device access credentials
In this mode, your application server requests a unique device access credential for each MQTT client. When a client connects to ApsaraMQ for MQTT, it computes connection parameters from the credential, following the defined rules. For details, see Unique-certificate-per-device authentication.