Introduction ApsaraMQ for MQTT how the client uploads, updates, and listens to Token expiration notifications and Token invalidity notifications in Token authentication mode.
Set parameters for MQTT client connection in token authentication mode
MQTT supports three token types. Each MQTT client can apply for one token per type at most, and may apply for and use one or more types as needed. The specific types are shown in the following table.
| Type identifier | Description |
|---|---|
| R | A read-only Token that has only the read permission for the specified resources. |
| W | A write-only Token has only the write permission for the specified resources. |
| RW | A read-write Token that has the read and write permissions for the specified resources. |
- Username
The username parameter consists of the authentication mode, AccessKeyId, and InstanceId, which are separated by vertical bars (|). The authentication mode is Token in token authentication mode.
- Example
If the client ID is GID_Test @, the value is timestamp, and the value is yyyyyyy if the accesskey ID is used. In Token mode, the value of UserName must be set to Token | YYYYY | Timestamp.
- Password:
The content of the Token to be used by the MQTT client. The parameter value is a complete string that consists of all the tokens concatenated in sequence by Token type and Token content that are connected by vertical bars (|). Different types of tokens are concatenated in no particular order.
Example 1: If an MQTT client has only the read-only Token 123 in the string format, then Password must be set to R | 123.
Example 2: If an MQTT client has two Token types (123 as the read-only Token and abcd as the write-only Token), then Password must be set to R | 123 | W | abcd.
Note Ensure that the Token parameters of MQTT client connection are set based on the preceding rules and that all the tokens are valid. If some tokens are invalid, the MQTT broker may determine that the Token settings are invalid.
Update tokens for clients
In normal cases, to update the Token of an MQTT client, disconnect the MQTT client first and then connect the MQTT client using the new Token. If you want to avoid client disconnection during Token update, you can replace the Token data of the MQTT broker session through dynamic Token update.
During dynamic Token update, an MQTT client sends a special message by using a predefined system Topic to update the new Token content to the MQTT broker. The MQTT client must ensure that the local Token configuration is updated along with the dynamic Token update. Otherwise, the old Token data may still be used during the next connection initialization.
- Topic sent for Token update:$SYS/uploadToken
- Content: JSONString
- Content description:
Parameter Type Description token String The MQTT client must upload the token string if token authentication is used. type String The Token type, which can be W, R, or RW, corresponding to three permission types. An MQTT client can have the three types of tokens at most. An incorrect Token type may result in a permission verification error. - Response parameters
A common PubAck message is returned. The MQTT client must wait for the response before performing the publish or subscribe operation. Otherwise, the MQTT broker may still use the old Token data for authentication, causing an authentication failure and a disconnection.
Listen to notifications about imminent token expiration (subscription not required)
To facilitate service debugging and monitoring, the MQTT broker pushes notifications to the MQTT client by using system topics to notify the client of tokens that will soon expire. The MQTT client can listen to such notifications to detect whether tokens are about to expire.
- Received topic: $SYS/tokenExpireNotice
- Content: JSONString
- Content description:
Parameter Type Description expireTime Long The Token expiration time, in the timestamp format and precise to milliseconds. The MQTT client is typically notified of the Token expiration time once five minutes in advance. However, the MQTT broker does not guarantee that a notification is always sent. type String The Token type, which can be W, R, or RW, corresponding to the three permission types uploaded by the client. - Responses
After receiving a notification about imminent token expiration, the MQTT client needs to apply for a new token as soon as possible to avoid failed transmission of messages.
Listen to notifications about invalid tokens (subscription not required)
To facilitate service debugging and monitoring, the MQTT broker pushes notifications to the MQTT client by using system topics to notify the client of Token authentication errors. The MQTT client can listen to such notifications to detect Token mismatch and other permission errors.
Received topic: $SYS/tokenInvalidNotice
Content: JSONString
- Content description:
Parameter Type Description code int The type of a token verification error. type String The Token type, which can be W, R, or RW, corresponding to the three permission types uploaded by the client. - Response:
Authentication may fail when the MQTT broker encounters a token verification error, and then the MQTT broker proactively disconnects the MQTT client. The MQTT broker pushes an error Code to the MQTT client before disconnecting the MQTT client. The MQTT client can identify the cause based on the error Code.
Type code Error type 1 The Token used to forge the Token, which cannot be parsed. 2 The Token has expired. 3 The Token has been revoked. 4 The error message returned because the resource and Token do not match. 5 The permission type and Token do not match. 8 The signature is invalid. -1 The account permissions are invalid.