Token 鉴权是什么?

Token 也称为动态密钥,是在加入频道时用于校验用户权限的一组字符串;鉴权是指在用户访问你的系统前,对其进行身份校验。用户在使用声网服务,如加入音视频通话或登录信令系统时,声网会使用 Token 对其鉴权。

我们为这种方式提供了一个较为形象的比喻,即:
某个展览馆需要游客实名认证后,获取专属入场券才可参观。游客在完成实名认证后可以获取到具备有效期限制的专属入场券,在进场时提供在有效期内的入场券,方能进场。其中:

声网的产品和服务中大部分采用 Token 鉴权的方式。下面,我们针对如何生成和使用 Token,以及 Token 鉴权中常见的问题进行详细的讲解。

如何生成和使用 Token?

1、Token 鉴权原理

在了解如何生成和使用 Token 前,需要先了解 Token 鉴权的原理。

如图所示,共分为 9 个步骤:

1.客户端根据需要,向 app 服务端申请 Token

2.App 服务端生成并返回 Token

3.客户端以 UID、频道名以及获取到的 Token 加入频道

4.声网平台读取该 Token 中包含的信息,并进行校验

5.客户端收到加入频道成功回调,并获取用户 UID

6.Token 最大有效期为 24 小时。当即将过期时,客户端会收到 Token 即将过期的回调

7.此时,如果客户端需要继续进行音视频互动,需要申请新的 Token

8.App 服务端生成并返回 Token

9.客户端更新 Token

这个过程中,用户需要自行实现步骤 1、2、3、7、8、9 的代码逻辑。
其中,对应的 Token 包含以下信息:

2、申请与生成 Token

可以看到,在用户加入频道前,客户端需要先向服务器申请 Token,并在 服务器 生成 Token,且 Token 必须与 需要加入频道的用户所对应的 AppID、频道名、用户 ID(UID)信息、用户权限 (是否能发流或收流) 一一对应,并且确保生成的 Token 在有效期内。然后才能以 UID、频道号 和 Token 加入对应频道。

向服务器申请 Token,可以通过向服务器发送 GET 请求等方式自行实现,以下文章以供参考:

https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_ios_ng?platform=iOS#%E9%83%A8%E7%BD%B2-token-%E6%9C%8D%E5%8A%A1%E5%99%A8

https://www.rtcdeveloper.cn/cn/community/blog/22929

https://www.rtcdeveloper.cn/cn/community/blog/24981

https://www.rtcdeveloper.cn/cn/community/blog/19790

https://www.rtcdeveloper.cn/cn/community/blog/20102

https://www.rtcdeveloper.cn/cn/community/blog/20024

https://www.rtcdeveloper.cn/cn/community/blog/20709

https://www.rtcdeveloper.cn/cn/community/blog/25430

生成 Token,可以使用声网提供的 Demo 实现,Demo 地址请参考:Token 生成器代码

请务必注意:例如用户使用 UID=123456(int 型)加入频道 ChannelName="test",那么生成 Token 时传入的参数 UID 和 ChannelName 必须是相对应的,即 UID=123456(int 型)且 ChannelName="test",否则会导致鉴权失败。

3、Token 过期处理

Token 最大有效期为 24 小时。当即将过期时,客户端会收到 Token 即将过期的回调;Token 过期时,SDK 会触发 Token 过期回调。具体处理方式如下:

一般来说,我们建议在 Token 过期前,及时更新 Token,即从服务器获取新的 Token 并调用 renewToken 将新生成的 Token 传给 SDK。

常见问题

当你的声网项目中不存在无证书并且启用了主要/次要证书,则表示你选择使用动态密钥 Token 对用户进行鉴权。

由于 Token 具有一定的时效性,因此 app 在运行过程中,你有可能会收到如下与 Token 相关的错误码或事件回调。本文对这些事件进行了梳理,提供触发的原因以及解决方法,帮助你在 App 出现异常时进行问题排查。

101:App ID 无效

问题描述:

问题原因:
不是有效的 App ID,一般是由于 App ID 的数据类型不对引起的。

解决方法:
建议检查 App ID 数据格式是否有效。声网的 App ID 为 String 型,请使用正确数据类型的 App ID,重新初始化声网服务。

109/118/2:Token 已过期

问题描述:

问题原因:

Token 过期。

解决方法:

Token 一旦过期,你就需要在服务端重新生成一个 Token,然后调用 renewToken 方法尝试重新加入频道。

110:Token 无效

问题描述:

问题原因:

生成的 Token 无效。一般有以下原因:

解决方法:

119:静态厂商使用动态密钥

该错误码仅适用于 RTC Web SDK。

问题描述:

Web 端调用 Client.join 方法加入频道时,Console 控制台打印错误码 ERR_STATIC_USE_DYNAMIC_KEY(119)。

问题原因:

表示静态厂商使用了动态密钥。一般是由于使用的 App ID 对应的声网项目未启用主要/次要证书,却试图使用 Token 加入频道引起。

解决方法:

对于未开启主要/次要证书的项目,你可以不使用 Token 加入频道。你也可以先启用主要/次要证书,然后在服务端生成 Token 后重新加入频道。

120:动态厂商使用静态密钥

该错误码仅适用于 RTC Web SDK。

问题描述:

Web 端调用 Client.join 方法加入频道时,Console 控制台打印错误码 ERR_DYNAMIC_USE_STATIC_KEY(120)。

问题原因:

表示动态厂商使用了静态密钥。一般是由于使用的 App ID 对应的声网项目中不存在无证书并且已启用主要/次要证书,加入频道时却没有传入 Token 引起。

解决方法:

如果 App ID 对应的项目中不存在无证书并且已启用主要/次要证书,则必须使用 Token 进行鉴权。你也可以换一个没有启用主要/次要证书的项目的 App ID,然后尝试重新加入频道。

Token 过期相关事件回调

为保证通信体验,声网提供如下两个回调,提醒用户 Token 即将过期或已经过期:

各语言 Token 错误码对照

附录


↙↙↙阅读原文可查看相关链接,并与作者交流