This topic describes how a ApsaraMQ for MQTT client uploads and updates tokens and how it listens to notifications about token expiration and invalidity in token-based authentication mode.
Set parameters for Message Queue for MQTT client connection in token-based authentication mode
Message Queue for MQTT supports three token types. Each Message Queue for MQTT client can apply for one token per type at most, and may apply for and use one or more types as needed. The following table lists the token types.
| Type identifier | Description |
|---|---|
| R | A read-only token that has only the read permission for the specified resources. |
| W | A write-only token that 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, AccessKey ID, and instance ID, which are separated with vertical bars (|). The authentication mode is Token in token-based authentication mode.
- Example
If a Message Queue for MQTT client whose client ID is GID_Test@@@0001 uses the instance ID mqtt-xxxxx and the AccessKey ID YYYYY, the Username parameter for connecting this Message Queue for MQTT client must be set to Token|YYYYY|mqtt-xxxxx.
- Password:
The Password parameter indicates the content of the token to be used by the Message Queue for 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 a Message Queue for MQTT client has only the read-only token 123 in the string format, the Password parameter must be set to R|123.
Example 2: If a Message Queue for MQTT client has two token types (123 as the read-only token and abcd as the write-only token), the Password parameter must be set to R|123|W|abcd.
Note Ensure that the token parameters of Message Queue for MQTT client connections are set based on the preceding rules and that all the tokens are valid. If some tokens are invalid, the Message Queue for MQTT broker may determine that the token settings are invalid.
Update tokens for clients
In normal cases, to update the token of a Message Queue for MQTT client, disconnect the Message Queue for MQTT client and then connect the Message Queue for MQTT client by using the new token. If you want to avoid client disconnection during token update, you can replace the token data of the Message Queue for MQTT broker session by calling the operation for token update.
During token update, a Message Queue for MQTT client sends a special message by using a predefined system topic to update the new token content to the Message Queue for MQTT broker. The Message Queue for MQTT client must ensure that the local token configuration is updated along with the token update. Otherwise, the old token data may still be used during the next connection initialization.
- Topic used for token update: $SYS/uploadToken
- Content: JSONString
- Content description
Parameter Type Description token String The Message Queue for MQTT client must upload the token string if token-based authentication is used. type String The token type, which can be W, R, or RW, corresponding to three permission types. A Message Queue for MQTT client can have the three types of tokens at most. An invalid token type may result in a permission verification error. - Return value
A common PubAck message is returned. The Message Queue for MQTT client must wait for the response before the publish or subscribe operation. Otherwise, the Message Queue for 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 Message Queue for MQTT broker pushes notifications to the Message Queue for MQTT client by using system topics to notify the client of tokens that will soon expire. The Message Queue for MQTT client can listen to such notifications to determine 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 Message Queue for MQTT client is typically notified of the token expiration time once five minutes in advance. However, the Message Queue for MQTT broker does not guarantee that a notification is always sent. type String The type of the token uploaded by a client, which can be W, R, or RW, corresponding to three permission types. - Response
After a Message Queue for MQTT client receives a notification about imminent token expiration, it must apply for a new token as soon as possible to avoid messaging failure.
Listen to notifications about invalid tokens (subscription not required)
To facilitate service debugging and monitoring, the Message Queue for MQTT broker pushes notifications to the Message Queue for MQTT client by using system topics to notify the client of token-based authentication errors. The Message Queue for 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 type of the token uploaded by a client, which can be W, R, or RW, corresponding to three permission types. - Response
Authentication may fail when the Message Queue for MQTT broker encounters a token verification error, and then the Message Queue for MQTT broker proactively disconnects the Message Queue for MQTT client. The Message Queue for MQTT broker pushes an error code to the Message Queue for MQTT client before it disconnects the Message Queue for MQTT client. The Message Queue for MQTT client can identify the cause based on the error code.
type code Error type 1 The token is forged and cannot be parsed. 2 The token has expired. 3 The token has been revoked. 4 The resource and token do not match. 5 The permission type and token do not match. 8 The signature is invalid. -1 The account permission is invalid.