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