本文介绍云消息队列 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账号权限不合法。