本文介紹云消息隊列 MQTT 版客戶端在Token模式下如何上傳Token、更新Token、監聽Token失效信息和監聽Token非法信息。

Token模式MQTT客戶端連接參數設置

MQTT支持三種模式的Token，每個客戶端每個類型至多申請一個Token，根據實際需要可能申請其中的一種或者多種，并使用。具體的類型如下表所示。

類型標志說明
R只讀類型的Token，只擁有指定資源的讀權限。
W只寫類型的Token，只擁有指定資源的寫權限。
RW讀寫類型的Token，對指定資源既可以讀也可以寫。
Token模式下MQTT客戶端的連接參數設置如下：
  • Username

    由鑒權模式名稱、AccessKey ID、InstanceId三部分組成，以 “|” 分隔。Token模式下鑒權模式設置為”Token”。

  • 舉例

    一個客戶端的ClientId是GID_Test@@@0001，使用了實例ID是mqtt-xxxxx，使用了AccessKey ID是YYYYY，則Token模式的Username應該設置成“Token|YYYYY|mqtt-xxxxx”。

  • Password

    客戶端需要使用的Token內容。具體設置方法是將所有的Token按照Token類型和Token內容依次使用“|”連接符拼接成一個完整的字符串，不同類型之間的Token拼接順序無要求。

    舉例1：客戶端只有一個讀類型的Token，Token字符串為“123”，則Password為“R|123”。

    舉例2：客戶端擁有2個類型的Token，讀類型的Token是“123”，寫類型的Token是“abcd”，則Password為“R|123|W|abcd”。

    說明 客戶端設置Token參數時需要保證嚴格按照約定規則，且需要保證所有Token有效，如果僅用部分Token合法，服務端仍然會判定非法。

客戶端更新Token憑證

正常情況下客戶端更換Token時需要斷開連接重新使用新的Token來連接，如果業務場景中不希望由于更換Token中斷客戶端的連接，可以使用動態更新Token的接口來動態替換服務端session內的Token數據。

動態更新Token本質上是由MQTT客戶端以約定的系統Topic發送一個特殊的消息，將新的Token內容更新到服務端，客戶端需要保證在動態替換的同時，本地配置也要替換，防止下次連接初始化又使用了舊的Token數據。

  • 更新Token發送Topic：$SYS/uploadToken
  • 內容：JSONString
  • 內容信息：
    名稱類型說明
    tokenString如果客戶端選用Token模式，則需要上傳Token字符串。
    typeStringToken類型，分為W、R、RW共三種，對應三種權限類型的Token。一個客戶端最多擁有這3個Token，設置錯誤的類型會導致權限校驗錯誤。
  • 返回值：

    普通的PubAck報文。客戶端必須等到該響應才能進行下一步Pub或者Sub操作，否則服務端仍然有可能使用舊的Token數據來做鑒權，可能會鑒權失敗導致連接斷開。

客戶端監聽即將失效的Token信息（無需訂閱）

服務端為方便業務調試和監控，會在Token即將失效的時候以系統Topic的形式推送通知消息到MQTT客戶端，客戶端可以監控該消息來判斷是否有出現過Token即將到期的情況。

  • 接收Topic：$SYS/tokenExpireNotice
  • 內容：JSONString
  • 內容信息：
    名稱類型說明
    expireTimeLong該Token即將于什么時候失效，格式為毫秒時間戳，一般提前5分鐘通知，只通知一次，但服務端不保證一定會有通知。
    typeStringToken類型，分為W、R、RW共三種，對應客戶端上傳的三種權限類型的Token。
  • 響應：

    客戶端收到Token即將失效的消息后，需要盡快處理重新申請Token的動作，以免造成收發消息失敗。

客戶端監聽Token非法的通知（無需訂閱）

服務端為方便業務調試和監控，會在Token鑒權錯誤時以系統Topic的形式推送通知消息到MQTT客戶端，客戶端可以監控該消息來判斷是否有出現過Token不匹配等錯誤權限的情況。

  • 接收Topic：$SYS/tokenInvalidNotice

  • 內容：JSONString

  • 內容信息：
    名稱類型說明
    codeintToken校驗失敗的類型。
    typeStringToken類型，分為W、R、RW共三種，對應客戶端上傳的三種權限類型的Token。
  • 響應：

    服務端校驗Token失效，會導致鑒權失敗，服務端會主動斷開鏈接。斷開鏈接之前，服務端會給客戶端推送失敗的Code，客戶端根據Code即可判斷原因。

    type code錯誤類型
    1偽造Token，不可解析。
    2Token已經過期。
    3Token已經被吊銷。
    4資源和Token不匹配。
    5權限類型和Token不匹配。
    8簽名不合法。
    -1賬號權限不合法。