ApsaraMQ for MQTT provides temporary access permissions to ApsaraMQ for MQTT clients in token-based authentication mode. You can use tokens provided by ApsaraMQ for MQTT to issue temporary credentials to users that are managed by your on-premises account system and manage their access permissions. This helps implement fine-grained access control for a single client and a single resource. This topic describes the process and usage notes for token-based authentication.
Terms
Term | Description |
Token (temporary credential) | A temporary credential that ApsaraMQ for MQTT issues to grant a single ApsaraMQ for MQTT client permissions to access specific resources. |
Application server | A server that you use to manage on-premises accounts and apply for and manage tokens for ApsaraMQ for MQTT clients. |
ApsaraMQ for MQTT broker | A server that is used to authenticate permissions and send and receive messages in ApsaraMQ for MQTT. You can use an ApsaraMQ for MQTT broker to process token-related requests that are initiated by application servers and send and receive messages. |
Process
Compared with the signature authentication mode, the token-based authentication mode is more difficult to use. You must deploy your application server based on the process that is described in the following figure. In addition, you must make sure that your ApsaraMQ for MQTT client can interact with your application server to obtain and update tokens during initialization.
Figure 1. Authentication process
The following items describe the authentication process:
When the ApsaraMQ for MQTT client is started, it connects to the application server for authentication.
The ApsaraMQ for MQTT client applies for all permissions required to access a specific topic from the application server.
The application server verifies whether the ApsaraMQ for MQTT client is granted permissions to perform operations on the topic. If the verification is passed, the application server applies for the resource-related token from the ApsaraMQ for MQTT broker.
The ApsaraMQ for MQTT broker verifies the token application request and returns the corresponding token if the request is valid.
The application server persistently stores the token that is returned and maps the required permissions to the token. Token caching provides the following benefits:
When the ApsaraMQ for MQTT client uses the same permissions to reconnect to the ApsaraMQ for MQTT broker after restarts, the application server returns the cached token to the client to help prevent repeated token application.
If the ApsaraMQ for MQTT broker cannot process the token application request from the ApsaraMQ for MQTT client due to an error, the application server returns the previously applied token for local disaster recovery.
The ApsaraMQ for MQTT client specifies the token as a parameter based on the specifications to connect to the ApsaraMQ for MQTT broker. The client can send and receive messages after it is authenticated by the broker.
The ApsaraMQ for MQTT client sends and receives messages as expected. If the ApsaraMQ for MQTT broker determines that the token is expired, the broker triggers an authentication failure and disconnects the ApsaraMQ for MQTT client. In this case, the client must re-apply for a token.
Limits on ApsaraMQ for MQTT clients
An ApsaraMQ for MQTT client must specify a token as a connection parameter in the Password field and upload the token each time a connection is established.
An ApsaraMQ for MQTT client must know the validity period of the used token and ensure that the token is not expired. If the token is expired, the ApsaraMQ for MQTT broker disconnects the client.
An ApsaraMQ for MQTT client can listen to the token expiration notifications that are pushed by an ApsaraMQ for MQTT broker. However, the broker does not guarantee that a push is always triggered. You can use the notifications only for troubleshooting.
An ApsaraMQ for MQTT client must persistently store the token that is returned by an application server to avoid applying for the same token upon each reconnection. If an application server receives connection requests from a large number of ApsaraMQ for MQTT clients at the same time, the application server unexpectedly quits.
To update a token for an ApsaraMQ for MQTT client, you can close the existing client connection and use a new token to establish connections. You can also use the system-defined topic provided by ApsaraMQ for MQTT to dynamically update a token. If you use the system-defined topic provided by ApsaraMQ for MQTT to dynamically update a token, make sure that the on-premises configurations are also updated for the next connection initialization.
Limits on application servers
An application server must authenticate the corresponding ApsaraMQ for MQTT client to prevent the client from applying for a token by using a forged identity.
An application server must manage token-client relationships, distributed tokens, the content of the corresponding permissions, and the validity period to prevent the same ApsaraMQ for MQTT client from repeatedly applying for a token.
An application server must implement on-premises disaster recovery. This can ensure business continuity in scenarios in which the ApsaraMQ for MQTT broker becomes temporarily unavailable.
Related API operations
You can call the related API operations to implement token-based authentication.
An application server is responsible for token application and revocation and interacts with an ApsaraMQ for MQTT broker by calling API operations over HTTPS.
Each API operation requires identity verification that is performed by using an AccessKey pair and a request signature. The token application, revocation, and verification operations are supported. For more information, see Application server-related methods in token authentication.
ApsaraMQ for MQTT clients provide operations for dynamically updating tokens, listening to token expiration notifications, and listening to token invalidity notifications. For more information, see Client-related methods in token authentication.