Message Queue for MQTT provides Message Queue for MQTT clients with temporary access permissions with a limited validity period in token-based authentication mode. The Message Queue for MQTT token service issues temporary credentials to users that are managed by the local account system, and limits the users' access permission. This implements refined permissions control on a per-client and per-resource basis. This topic describes the procedure and precautions.

Terms

Term Description
Token (temporary credential) The temporary credential that Message Queue for MQTT issues to grant a single Message Queue for MQTT client the permission to access specific resources.
Application server The server that you use to manage local accounts and apply for and manage token services on behalf of clients.
Message Queue for MQTT broker The Message Queue for MQTT broker for permission authentication and messaging, which processes token-related requests and message sending and receiving.

Authentication process

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

Perform the following steps for authentication:

  1. When the Message Queue for MQTT client is started, it connects to the application server for authentication.
  2. The Message Queue for MQTT client applies for the required permissions for all the topics from the application server.
  3. The application server verifies whether the Message Queue for MQTT client is authorized to operate the topics. If the Message Queue for MQTT client is authorized, the application server applies for the resource-related tokens from the Message Queue for MQTT broker.
  4. The Message Queue for MQTT broker verifies the token application request and returns the corresponding tokens if the request is valid.
  5. The application server persistently stores the tokens that are returned, and maps required permissions to the tokens. Token caching provides the following advantages:
    • When the Message Queue for MQTT client is restarted with the same permissions for access, the application server returns the cached tokens to the Message Queue for MQTT client. This avoids repeated token application.
    • If the Message Queue for MQTT broker cannot process the client's token application request due to an error, the application server returns the previously applied token for local disaster recovery.
  6. The Message Queue for MQTT client sets the token as a parameter based on the specifications to connect to the Message Queue for MQTT broker. The Message Queue for MQTT client can send and receive messages after it is authenticated by the Message Queue for MQTT broker.
  7. The Message Queue for MQTT client sends and receives messages properly. If the Message Queue for MQTT broker determines that the token has expired, it triggers an authentication failure and disconnects the Message Queue for MQTT client. In this case, the Message Queue for MQTT client must re-apply for a token.

Required client behaviors

  • The Message Queue for MQTT client must obtain the token and token expiration time from the application server to calculate the time for refreshing the token.
  • The Message Queue for MQTT client must set the token as a connection parameter in Password and upload the token upon each connection.
  • The Message Queue for MQTT client must know the validity period of the used token and ensure that it does not expire. If the token expires, the Message Queue for MQTT broker may disconnect the Message Queue for MQTT client.
  • The Message Queue for MQTT client can listen to the token expiration notifications that are pushed by the Message Queue for MQTT broker, but the Message Queue for MQTT broker does not guarantee that the push is always triggered. These notifications are only for troubleshooting.
  • The Message Queue for MQTT client must persistently store the tokens that are returned by the application server to avoid applying for the same token upon each reconnection. Otherwise, the application server may quits unexpectedly when it receives connection requests from many Message Queue for MQTT clients at the same time.
  • When a token is updated, you can close the old client connection and use the new token to establish connections. You can also use the system-defined topics provided by Message Queue for MQTT to dynamically update the token. If you select dynamic token update, make sure that the local configurations are also updated for the next connection initialization.

Required application server behaviors

  • The application server must authenticate the Message Queue for MQTT client to prevent the Message Queue for MQTT client from applying for a token by using a forged identity.
  • The application server must manage token-client relationships, distributed tokens, content of the corresponding permissions, and the validity period to prevent the same Message Queue for MQTT client from calling a token repeatedly.
  • When the application server returns a token to the Message Queue for MQTT client, it must inform the client of the operation permission and expiration time of the token, so that the client can refresh the token in advance.
  • The application server must implement local disaster recovery to prevent service blocking due to temporary unavailable access to the Message Queue for MQTT broker.

Related API operations

You can call related operations to implement token-based authentication.

  • The application server is responsible for token application and revocation, and interacts with the Message Queue for MQTT broker by calling HTTPS operations.

    Each operation requires authentication by using an AccessKey pair and a request signature. The token application, revocation, and verification operations are available. For more information, see Application server-related operations in token-based authentication.

  • Message Queue for MQTT clients provide three operations for dynamically updating tokens, listening to token expiration notifications, and listening to token invalidity notifications, respectively. For more information, see Client-related operations in token-based authentication.