Token,也称动态密钥,是 app 用户在加入频道或登录服务系统时采用的一种鉴权方式。
本文展示如何使用 Agora 提供的代码在服务端生成 Token。
Token 在你的业务服务端生成。用户加入频道或登录服务时,客户端需要向服务端申请 Token;服务器生成 Token 后,再将其传给客户端。
开始前,请确保你的项目或使用的 Agora 产品满足如下条件:
你的 Agora 项目在控制台已开启 App 证书。
你所使用的 Agora 产品,满足如下版本要求:
产品 | 支持 Token 的版本 |
---|---|
RTC SDK |
|
本地服务端录制 SDK | v2.1.0 及以上 |
云端录制 | 无版本要求 |
实时码流 | 所有版本 |
互动游戏 SDK | v2.2.0 及以上 |
Agora 在 GitHub 提供一个开源的 AgoraDynamicKey 仓库,支持使用 C++、Java、Python、PHP、Ruby、Node.js、Go 等语言在你的服务端部署生成 Token。下图以 C++ 为例,展示生成 Token 代码的文件结构:
其中:
./sample/RtcTokenBuilderSample.cpp
文件包含用于生成 RTC Token 的示例代码。./src/RtcTokenBuilder.h
文件包含用于生成 RTC Token 的 API 源代码。Agora 在各语言的 sample 文件夹下提供了生成 Token 的示例代码供你参考。以 C++ 为例:
int main(int argc, char const *argv[]) {
// 请填入你的项目 App ID
std::string appID = "970Cxxxxxxxxxxxxxxxxxxxxxxx1b33";
// 请填入你的项目 App 证书
std::string appCertificate = "5CFdxxxxxxxxxxxxxxxxxxxxxxx5d3b";
// 请填入频道名
std::string channelName= "7d72xxxxxxxxxxxxxxxxxxxxxxbdda";
// 请填入 uid。如果填 0,则表示不对 uid 鉴权
uint32_t uid = 2882341273;
// Token 服务过期时间
uint32_t expirationTimeInSeconds = 3600;
uint32_t currentTimeStamp = time(NULL);
uint32_t privilegeExpiredTs = currentTimeStamp + expirationTimeInSeconds;
std::string result;
result = RtcTokenBuilder::buildTokenWithUid(
appID, appCertificate, channelName, uid, UserRole::Role_Publisher,
privilegeExpiredTs);
std::cout << "Token With Int Uid:" << result << std::endl;
你可以参考如下步骤,通过命令行直接使用上述示例代码生成 Token。开始前请确保已安装 OpenSSL 库。
将 AgoraDynamicKey 仓库下载或克隆至本地。
打开 AgoraDynamicKey/cpp/sample/RtcTokenBuilderSample.cpp
文件,使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。
进入 RtcTokenBuilderSample.cpp
所在路径,然后运行如下命令行。运行结束后,相同文件夹下会生成一个可执行文件 RtcTokenBuilderSample
。
g++ -std=c++0x -O0 -I../../ -L. RtcTokenBuilderSample.cpp -lz -lcrypto -o RtcTokenBuilderSample
运行如下命令行生成 Token。生成的 Token 会显示在 Terminal 中。
./RtcTokenBuilderSample
使用其他语言的示例代码在本地生成 Token 的步骤如下:
AgoraDynamicKey/java
文件。AgoraDynamicKey/java/src/io/agora/sample/RtcTokenBuilderSample.java
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。Python -V
AgoraDynamicKey/python/sample/RtcTokenBuilderSample.py
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。RtcTokenBuilderSample.py
所在路径,然后运行如下命令行生成 Token。 生成的 Token 会显示在 Terminal 中。
python RtcTokenBuilderSample.py
Python -V
AgoraDynamicKey/python/sample/RtcTokenBuilderSample.py
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。RtcTokenBuilderSample.py
所在路径,然后运行如下命令行生成 Token。 生成的 Token 会显示在 Terminal 中。
python RtcTokenBuilderSample.py
AgoraDynamicKey/sample/RtcTokenBuilderSample.php
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。RtcTokenBuilderSample.php
所在路径,然后运行如下命令行生成 Token。 生成的 Token 会显示在 Terminal 中。
php RtcTokenBuilderSample.php
npm install
AgoraDynamicKey/nodejs/sample/RtcTokenBuilderSample.js
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。RtcTokenBuilderSample.js
所在路径,然后运行如下命令行生成 Token。 生成的 Token 会显示在 Terminal 中。
node RtcTokenBuilderSample.js
AgoraDynamicKey/go/sample/RtcTokenBuilder/sample.go
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。sample.go
所在路径,然后运行如下命令行。 运行结束后,相同文件夹下会生成一个可执行文件 RtcTokenBuilder
。
go build
./RtcTokenBuilder
ruby -version
AgoraDynamicKey/ruby/sample/rtc_token_builder_sample.rb
文件。使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值,并注释掉示例代码中的 buildTokenWithUserAccount
代码片段。rtc_token_builder_sample.rb
所在路径,然后运行如下命令行生成 Token。生成的 Token 会显示在 Terminal 中。
ruby rtc_token_builder_sample.rb
下文以 C++ 的 API 为例,介绍生成 Token 的 API 参数含义。具体参数解释也适用于其他语言。
static std::string buildTokenWithUid(
const std::string& appId,
const std::string& appCertificate,
const std::string& channelName,
uint32_t uid,
UserRole role,
uint32_t privilegeExpiredTs = 0);
参数 | 描述 |
---|---|
appId |
你在 Agora 控制台创建项目时生成的 App ID。 |
appCertificate |
你的 App 证书。 |
channelName |
标识通话的频道名称,长度在 64 字节以内。以下为支持的字符集范围:
|
uid |
用户 ID,32 位无符号整数。建议设置范围:1 到 (232-1),并保证唯一性。如果不需要校验 uid,即客户端使用任何 uid 都可以加入频道或登录服务,请把 uid 设为 0。 |
role |
用户发流权限:
|
privilegeExpiredTs |
Token 过期的 Unix 时间戳,单位为秒。该值为当前时间戳和 Token 有效期的总和。比如,如果你将 privilegeExpiredTs 设为当前时间戳再加 600 秒,那么 Token 会在生成 10 分钟后过期。Token 的最大有效期为 24 小时。如果你设为 0,或超过 24 小时,则 Token 有效期依然是 24 小时。 |
buildTokenWithUserAccount
,但不推荐使用。生成 Token 时填入的频道名和用户 ID,需要和加入频道时填入的参数一致。
生成 Token 需要先在控制台启用对应项目的 App 证书。项目一旦开启了 App 证书,就必须使用 Token 鉴权。
Token 的最大有效期为 24 小时。为保证通信体验,Agora 会在 Token 即将过期或已经过期时,分别触发以下回调:
onTokenPrivilegeWillExpire
:该回调表示 Token 即将失效。onRequestToken
(Web 平台为 onTokenPrivilegeDidExpire
):该回调表示 Token 已经失效。收到任一回调后,你需要在服务端重新生成 Token,然后调用 renewToken
方法更新 Token。
生成 Token 过程中,你也可以参考如下文档: