本文主要介绍在使用声网 SDK 过程中使用 Channel Key 的方法。
开发者在我们官网注册后,可以创建多个项目,每一个项目对应的唯一标识就是 App ID。 如果有人非法获取了你的 App ID,他将可以在声网提供的 SDK 中使用你的 App ID,如果他知道你的频道名字,甚至有可能干扰你正常的通话。
所以建议仅在测试阶段或对安全性要求不高的场景里使用 App ID。
以用户 UID 123 加入某个房间 ABC 为例,Channel Key 的机制相当于门禁。Channel Key 相当于门卡, 以下简述签发 Channel Key 的过程:
用户向服务台请求签发门卡,并提供信息:
- 自己的身份证明信息 (UID):123
- 自己想要加入的房间号 (ChannelName):ABC
服务台确认请求来自合法的 App 用户,并根据要求现场签发用于该用户加入该频道号的门卡:
- 门卡从签发时间(当前时间戳)起五分钟是有效的;
- 门卡可以约定能在房间中待到什么时候(服务过期时间戳),到了时间点时间会被请出房间。也可以不约定,想待多久待多久(服务过期时间戳传 0);
用户加入频道的时候,门禁验证用户持有的卡是否在有效期内,是否是用于该房间的门卡(验证频道名),是否是该用户本人持有的卡(验证 UID);
用户在门卡签发的五分钟内离开房间(leavechannel 或断线),重新回来的时候需要通过门禁,持有的房卡有效,可以进入房间;
用户在门卡签发的五分钟后离开房间,重新回来的时候通过门禁,门卡已经失效,需要去服务台重新签发门卡,才可以重新加入;
用户一直待在房间内,到了门卡约定的服务到期时间,会被立即请出房间,此时需要去服务台重新签发门卡,才能重新加入;
服务到期时间为 0 的情况下,也即不限定用户在房间内停留的时间,只要用户不离开,就不需要重新签发门卡;
进入控制台,按照屏幕提示注册账号并登录控制台。详见注册与登录。
点击左侧导航栏的 图标进入项目管理页面。
点击创建按钮。
在弹出的对话框内输入项目名称,选择 APP ID 为鉴权机制,并点击提交。
项目创建成功后,你会在项目列表中看到刚刚创建的项目。点击 查看并复制该项目对应的 App ID。
在调用声网的 API 接口实现功能,如 SDK 初始化时,声网会需要你填入 App ID。将你获取到的 App ID 直接填入即可。
App 证书是声网控制台为开发项目生成的字符串。根据不同的安全需求,声网在项目中设置了两种 App 证书,区别如下:
如果你是第一次启用 App 证书,你需要先启用主要证书。
参考如下步骤启用主要证书:
你可以通过 generateMediaChannelKey
方法,以及声网提供的示例代码来获取 Channel Key。声网的示例代码涵盖 C++, Java, Python,node.js 等语言,你可以直接将相应的代码应用在你的程序中。
首先,请访问 https://github.com/AgoraIO/Tools/tree/master/DynamicKey/AgoraDynamicKey,下载相应编程语言的代码,并将代码部署到您的服务器上。
然后,在你所开发的程序中,输入如下字段的值。不同的编程语言,必须字段名称不完全相同:
字段 | C++ | Java | Python | Node.js | Go |
---|---|---|---|---|---|
App ID | appID | appID | appID | appID | appID |
App 证书 | appCertificate | appCertificate | appCertificate | appCertificate | appCertificate |
频道名 | channelName | channel | channelName | channel | channelName |
授权时间戳 [1] | unixTs | ts | unixTs | ts | unixTs |
随机数 | randomInt | r | randomInt | r | randomInt |
用户 ID | uid | uid | uid | uid | uid |
服务到期时间戳 [2] | expiredTs | expiredTs | expiredTs | expiredTs | expiredTs |
[1]: Channel Key 生成时的时间戳,自 1970.1.1 开始到当前时间的秒数。授权该 Channel Key 在生成后的 5 分钟内可以访问声网服务,如果 5 分钟内没有访问,则该 Channel Key 无法再使用。
[2]: 用户使用声网服务终止的时间戳,在此时间之后,将不能继续使用声网服务(比如进行的通话会被强制终止);如果对终止时间没有限制,设置为 0。设置服务到期时间并不意味着Dynamic Key 失效,而仅仅用于限制用户使用当前服务的时间。
输入完成后,服务端会最终返回对应的 Channel Key。
如需要验证用户 ID (User ID), 详见下表所列的 DynamicKey 与 SDK 的版本兼容。如不需验证 UID,则各版本 SDK 可使用任意 DynamicKey 版本:
DynamicKey 版本 | 用户 ID | SDK 版本 |
---|---|---|
DynamicKey4 | 某个用户的 uid | 1.3+ |
DynamicKey3 | 某个用户的 uid | 1.2.3+ |
DynamicKey | N/A | N/A |
每一次客户端加入频道前:
采用了 Channel Key 方案后,在用户进入频道时,Channel Key 将替换原来的 App ID。 Channel Key在一段时间后会失效,应用程序获知密钥失效(即当 onError 或 didOccurError 回调方法报告 ERR_CHANNEL_KEY_EXPIRED(109))时,需调用 renewChannelKey() 方法进行更新。 Channel Key 采用业界标准化的 HMAC_SHA256 加密方案,在 node.js, Java, Python, C++ 等绝大多数通用的服务器端开发平台上均可获得所需库。具体加密方案可参看以下网页:http://en.wikipedia.org/wiki/Hash-based_message_authentication_code