ApsaraMQ for MQTT supports two authentication modes: token-based authentication and unique-certificate-per-device authentication. Select the mode that matches your security model and credential lifecycle requirements.
AccessKey ID and AccessKey secret directly affect how UserName and Password are computed. Do not embed them in client-side code. Store these credentials in your backend application, compute UserName and Password server-side, and pass the results to the client.
Choose an authentication mode
| Mode | Best for | Credential lifetime | Access control granularity |
|---|---|---|---|
| Token-based authentication | Untrusted or mobile clients that need temporary, scoped permissions | Temporary (auto-expires) | Per-client, per-resource |
| Unique-certificate-per-device authentication | Trusted devices in IoT environments that need persistent access | Permanent (revocable by broker) | Per-client (bound to Client ID) |
How authentication works
When an MQTT client connects, ApsaraMQ for MQTT authenticates it using the UserName and Password fields in the MQTT CONNECT packet. Both fields are computed differently depending on the authentication mode.
Mode | Mode name | UserName format | Password |
| Token-based | Token | Token|<AccessKey ID>|<Instance ID> | Uploaded token content. For details, see Token-based authentication. |
| Unique-certificate-per-device | DeviceCredential | DeviceCredential|<DeviceAccessKeyId>|<Instance ID> | Base64-encoded signature of the Client ID, signed with the DeviceAccessKey secret. For details, see Unique-certificate-per-device authentication. |
UserName examples
Token mode
For a client with ClientId GID_Test@@@0001, instance ID mqtt-xxxxx, and AccessKey ID YYYYY:
Token|YYYYY|mqtt-xxxxxDeviceCredential mode
For a client with ClientId GID_Test@@@0001, instance ID mqtt-xxxxx, and DeviceAccessKeyId YYYYY:
DeviceCredential|YYYYY|mqtt-xxxxxToken-based authentication
Token-based authentication grants temporary, scoped access to individual clients. Tokens define which resources a client can access, the permission level, and when the access expires.
When to use token-based authentication
Use this mode when:
Your application has its own account system and needs to map local accounts (departments, devices, or individual users) to distinct MQTT permissions.
The Alibaba Cloud RAM system cannot provide per-client permission granularity. Signature authentication operates at the Alibaba Cloud account level, while token-based authentication controls access down to individual resources.
Clients run on mobile devices or other environments vulnerable to cracking or hijacking, where fixed credentials pose a security risk.
Permissions must expire automatically after a set period.
How to use tokens
Your backend manages accounts or devices, tracks permissions and expiration times, and delivers tokens to clients:
Issue tokens from a secure, trusted management node.
Deliver each token to the corresponding MQTT client.
The client authenticates with the ApsaraMQ for MQTT broker using the token.
For the full token authentication flow, including how to upload and manage tokens, see Token-based authentication.
Unique-certificate-per-device authentication
Unique-certificate-per-device authentication assigns each MQTT client its own username and password, bound to a specific Client ID. The broker can update or revoke any device's credentials at any time, giving you full lifecycle control.
When to use unique-certificate-per-device authentication
Use this mode when:
Clients are secure and trusted, and persistent authentication is preferred over token rotation.
Your environment resembles IoT deployments where real-time token updates are impractical.
You need to prevent token spoofing by binding credentials directly to each Client ID.
Each device must authenticate independently with its own credentials.
How to use device access credentials
Your application server requests a unique device access credential for each MQTT client from the ApsaraMQ for MQTT broker. The credential contains a DeviceAccessKeyId that the client uses to compute its UserName and Password at connection time.
For the full credential workflow and computation rules, see Unique-certificate-per-device authentication.