Token client interfaces
This topic describes how an ApsaraMQ for MQTT client can upload and update tokens, and listen for token expiration and invalid token notifications in token mode.
Connection parameters for an ApsaraMQ for MQTT client in token mode
MQTT supports three types of tokens. Each client can request a maximum of one token of each type. You can request and use one or more types of tokens as needed. The following table describes the token types.
| Type flag | Description |
| R | A read-only token. It grants read-only permissions on specified resources. |
| W | A write-only token. It grants write-only permissions on specified resources. |
| RW | A read/write token. It grants both read and write permissions on specified resources. |
- Username
The username consists of the authentication mode, AccessKey ID, and instance ID, separated by vertical bars (|). For token mode, set the authentication mode to "Token".
- Example
If a client has the ClientId GID_Test@@@0001, uses the instance ID mqtt-xxxxx, and uses the AccessKey ID YYYYY, set the username for token mode to "Token|YYYYY|mqtt-xxxxx".
- Password
The content of the token for the client is a single string created by concatenating the type and content of each token. A vertical line (|) separates the tokens, and their order does not matter.
Example 1: If a client has only one read-type token with the token string "123", the password is "R|123".
Example 2: If a client has two types of tokens, a read-type token "123" and a write-type token "abcd", the password is "R|123|W|abcd".
Note When you set token parameters, ensure that you follow the required conventions and that all tokens are valid. If any of the tokens are invalid, the server-side considers the entire request invalid.
Update client token credentials
To change a token, the client normally must disconnect and then reconnect using the new token. If your business scenario cannot tolerate connection interruptions, you can use the dynamic token update interface to replace the token data in the server-side session without disconnecting.
To perform a dynamic token update, the ApsaraMQ for MQTT client sends a special message to a designated system topic to update the token content on the server-side. When you replace a token, you must also update the local configuration. This prevents the client from using the old token data the next time it initializes a connection.
- Topic for sending token updates: $SYS/uploadToken
- Content: JSONString
- Content information:
Name Type Description token String If the client uses token mode, upload the token string. type String The token type. Valid values are W, R, and RW, which correspond to the three permission types. A client can have a maximum of these three tokens. Setting an incorrect type causes a permission verification error. - Return value
The server returns a standard PubAck message. The client must wait for this response before it performs the next Pub or Sub operation. Otherwise, the server-side may use the old token for authentication, which can cause an authentication failure and a disconnection.
Listen for notifications about expiring tokens (no subscription required)
For debugging and monitoring purposes, the server-side pushes a notification message to the ApsaraMQ for MQTT client through a system topic when a token is about to expire. The client can monitor these messages to determine when a token is about to expire.
- Topic for receiving notifications: $SYS/tokenExpireNotice
- Content: JSONString
- Content information:
Name Type Description expireTime Long The time when the token will expire, in the format of a millisecond UNIX timestamp. The notification is typically sent 5 minutes in advance and only once. However, the server-side does not guarantee that a notification will be sent. type String The token type. Valid values are W, R, and RW, which correspond to the three permission types uploaded by the client. - Response
After the client receives a token expiration notification, you must request a new token as soon as possible to prevent message sending and receiving failures.
Listen for notifications about invalid tokens (no subscription required)
For debugging and monitoring purposes, the server-side pushes a notification message to the ApsaraMQ for MQTT client through a system topic when a token authentication error occurs. The client can monitor these messages to identify permission errors, such as a token mismatch.
Topic for receiving notifications: $SYS/tokenInvalidNotice
Content: JSONString
- Content information:
Name Type Description code int The type of token verification failure. type String The token type. Valid values are W, R, and RW, which correspond to the three permission types uploaded by the client. - Response:
If the server-side determines that a token is invalid, authentication fails and the server-side disconnects the client. Before disconnecting the client, the server-side pushes a failure code to the client. The client can use this code to determine the cause of the failure.
type code Error type 1 Forged token. Cannot be parsed. 2 The token has expired. 3 The token has been revoked. 4 Resource and token mismatch. 5 Permission type and token mismatch. 8 Invalid signature. -1 Invalid account permissions.