Message Queue for MQTT Provides MQTT clients with temporary access permissions through Token authentication. You can use the MQTT Token Service to issue temporary access credential to users managed by the local account system and restrict the access permission, thus realizing the single-client and single-resource fine-grained permission control. This topic describes the procedure and precautions.


Term Description
Token (temporary credential) Message Queue for MQTT Issues a temporary access credential to grant a single client the permission to access specific resources.
Application server The server where you manage the local account and apply for and manage the Token service application on behalf of the client.
MQTT broker Message Queue for MQTT The permission authentication and messaging server that processes Token-related requests and message sending and receiving services.


The Token authentication mode is more complex than the signature mode. You must follow the process shown in the following figure to deploy your application server. During initialization, the MQTT client must be able to interact with your application server to obtain and update tokens.
Figure 1. Authentication process

The procedure is as follows:

  1. The MQTT client connects to the application server to authenticate the application server before it starts.
  2. The client applies for the required permissions on all topics from the application server.
  3. The application server verifies whether the MQTT client is authorized to operate topics. If The MQTT client is authorized, Message Queue for MQTT the server applies for the Token for the corresponding resource.
  4. Message Queue for MQTT The server verifies the Token application request and returns the corresponding tokens if the request is valid.
  5. The app server performs local persistence of the returned tokens, and maps required permissions to other tokens. Caching a Token has the following advantages:
    • When the MQTT client is restarted, the application server returns the cached tokens to the MQTT client so that the permissions do not change.
    • When the client reapplies for a Token, if the MQTT broker is abnormal, the application server can try to return the previously applied Token to implement local disaster recovery.
  6. The MQTT client sets Token parameters based on the specifications to connect to the MQTT broker. The MQTT client can send and receive messages after being authenticated by the MQTT broker.
  7. The MQTT client sends and receives messages properly. If the MQTT broker determines that the token has expired, it triggers an authentication failure and disconnects the MQTT client. In this case, the MQTT client needs to re-apply for a token.

Client behavior limits

  • The MQTT client must set the token as a connection parameter in Password and upload the token when establishing a connection.
  • The MQTT client must know the validity period of the used token and ensure that it is within the validity period. If the token expires, the MQTT broker may disconnect the MQTT client.
  • The MQTT client can listen to the token expiration notifications that are pushed by the MQTT broker, but the MQTT broker does not guarantee that the push is always triggered. Those notifications are only for troubleshooting.
  • The MQTT client must perform persistence of the tokens that are returned by the application server to avoid applying for the same token during each reconnection. Otherwise, the application server may crash when receiving connection requests from many MQTT clients at the same time.
  • You can choose to close the old client connection and use the new Token to connect clients. You can also use the system-defined topics provided by MQTT to update the Token. If you select dynamic Token update, make sure that the local configurations are also updated for the next connection initialization.

Application server behavior limits

  • The application server must authenticate the MQTT client to prevent the MQTT client from applying for a token by using a forged identity.
  • The application server must manage the relationship between the Token and the client, the Distributed Token, the content of the corresponding permission, and the effective period to prevent the same client from calling them repeatedly.
  • The application server must implement local disaster recovery to prevent service blocking due to temporary unavailable access to the MQTT Server.

Related methods

You can call related methods to implement token authentication.

  • The application server manages the application and revocation of tokens, and Message Queue for MQTT servers use HTTPS APIs to communicate with each other.

    Each method requires authentication by using an AccessKey and a request signature. Currently, the methods for token application, revocation, and verification are available. For more information, see Application server-related methods in token authentication.

  • Message Queue for MQTT Clients provide three APIs for dynamic Token update, listening to Token expiration notifications, and listening to Token invalidity notifications, respectively. For more information, see Client-related methods in token authentication.