本文介绍云消息队列 MQTT 版客户端在Token模式下如何上传Token、更新Token、监听Token失效信息以及监听Token非法信息。
Token模式MQTT客户端连接参数设置
MQTT支持三种模式的Token,每个客户端每个类型至多申请一个Token,根据实际需要可申请其中的一种或者多种并使用。具体的类型如下表所示。
类型标志 | 说明 |
---|---|
R | 只读类型的Token,只拥有指定资源的读权限。 |
W | 只写类型的Token,只拥有指定资源的写权限。 |
RW | 读写类型的Token,对指定资源既可以读也可以写。 |
- 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
- 内容信息:
名称 类型 说明 token String 如果客户端选用Token模式,则需要上传Token字符串。 type String Token类型,分为W、R、RW共三种,对应三种权限类型的Token。一个客户端最多拥有这3个Token,设置错误的类型会导致权限校验错误。 - 返回值
普通的PubAck报文。客户端必须等到该响应才能进行下一步Pub或者Sub操作,否则服务端仍然有可能使用旧的Token数据来做鉴权,可能会鉴权失败导致连接断开。
客户端监听即将失效的Token信息(无需订阅)
服务端为方便业务调试和监控,会在Token即将失效的时候以系统Topic的形式推送通知消息到MQTT客户端,客户端可以监控该消息来判断是否有出现过Token即将到期的情况。
- 接收Topic:$SYS/tokenExpireNotice
- 内容:JSONString
- 内容信息:
名称 类型 说明 expireTime Long 该Token即将于什么时候失效,格式为毫秒时间戳,一般提前5分钟通知,只通知一次,但服务端不保证一定会有通知。 type String Token类型,分为W、R、RW共三种,对应客户端上传的三种权限类型的Token。 - 响应
客户端收到Token即将失效的消息后,需要尽快处理重新申请Token的动作,以免造成收发消息失败。
客户端监听Token非法的通知(无需订阅)
服务端为方便业务调试和监控,会在Token鉴权错误时以系统Topic的形式推送通知消息到MQTT客户端,客户端可以监控该消息来判断是否有出现过Token不匹配等错误权限的情况。
接收Topic:$SYS/tokenInvalidNotice
内容:JSONString
- 内容信息:
名称 类型 说明 code int Token校验失败的类型。 type String Token类型,分为W、R、RW共三种,对应客户端上传的三种权限类型的Token。 - 响应:
服务端校验Token失效,会导致鉴权失败,服务端会主动断开链接。断开链接之前,服务端会给客户端推送失败的Code,客户端根据Code即可判断原因。
type code 错误类型 1 伪造Token,不可解析。 2 Token已经过期。 3 Token已经被吊销。 4 资源和Token不匹配。 5 权限类型和Token不匹配。 8 签名不合法。 -1 账号权限不合法。