鉴权是指在用户访问你的系统前,对其进行身份校验。用户在使用声网服务,如加入音视频通话或登录信令系统时,声网使用 Token 对其鉴权。
为提供更好的鉴权体验和安全性保障,声网自 2022 年 8 月 18 日推出新版 Token:AccessToken2。如需从 AccessToken 升级至 AccessToken2,请参考 AccessToken 升级指南。
本文展示如何为 AccessToken2 在服务端部署一个 Token 生成器,以及如何搭建一个使用 Token 鉴权的客户端。
下图展示了鉴权的基本流程:
你需要自行实现步骤 1、2、3、7、8、9 的代码逻辑。
Token 包含以下信息:
开始前,请确保你的项目或使用的声网产品满足如下条件:
一个有效的声网账户。
已开启 App 证书的声网项目。
Golang 1.14 或以上版本,GO111MODULE 设置为开启。
本节介绍如何使用声网提供的代码生成并提供 Token,对用户及其权限进行校验。
本节介绍如何获取生成 Token 所需的安全信息,如你的项目的 App ID 及 App 证书。
声网会给每个项目自动分配一个 App ID 作为项目唯一标识。
在声网控制台的项目管理页面,找到你的项目,点击 App ID 右侧的 图标,即可获取项目的 App ID。
参考以下步骤获取 App 证书:
在声网控制台的项目管理页面,找到你的项目,点击配置。
点击主要证书下面的复制图标,即可获取项目的 App 证书。
Token 需要在你的服务端部署生成。当客户端发送请求时,服务端部署的 Token Generator 会生成相应的 Token,再发送给客户端。
本节展示如何使用 Golang 在你的本地设备上搭建并运行一个 Token 服务器。
此示例服务器使用 BuildTokenWithUid
[1/2]。
server.go
文件,然后贴入如下代码。将其中的 <Your App ID>
和 <Your App Certificate>
替换为你的 App ID 和 App 证书。package main
import (
rtctokenbuilder "github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/rtctokenbuilder2"
"fmt"
"log"
"net/http"
"encoding/json"
"errors"
"strconv"
)
type rtc_int_token_struct struct{
Uid_rtc_int uint32 `json:"uid"`
Channel_name string `json:"ChannelName"`
Role uint32 `json:"role"`
}
var rtc_token string
var int_uid uint32
var channel_name string
var role_num uint32
var role rtctokenbuilder.Role
// 使用 RtcTokenBuilder 来生成 RTC Token
func generateRtcToken(int_uid uint32, channelName string, role rtctokenbuilder.Role){
appID := "<Your App ID>"
appCertificate := "<Your App Certificate>"
// AccessToken2 过期的时间,单位为秒
// 当 AccessToken2 过期但权限未过期时,用户仍在频道里并且可以发流,不会触发 SDK 回调。
// 但一旦用户和频道断开连接,用户将无法使用该 Token 加入同一频道。请确保 AccessToken2 的过期时间晚于权限过期时间。
tokenExpireTimeInSeconds := uint32(40)
// 权限过期的时间,单位为秒。
// 权限过期30秒前会触发 token-privilege-will-expire 回调。
// 权限过期时会触发 token-privilege-did-expire 回调。
// 为作演示,在此将过期时间设为 40 秒。你可以看到客户端自动更新 Token 的过程
privilegeExpireTimeInSeconds := uint32(40)
result, err := rtctokenbuilder.BuildTokenWithUid(appID, appCertificate, channelName, int_uid, role, tokenExpireTimeInSeconds, privilegeExpireTimeInSeconds)
if err != nil {
fmt.Println(err)
} else {
fmt.Printf("Token with uid: %s\n", result)
fmt.Printf("uid is %d\n", int_uid )
fmt.Printf("ChannelName is %s\n", channelName)
fmt.Printf("Role is %d\n", role)
}
rtc_token = result
}
func rtcTokenHandler(w http.ResponseWriter, r *http.Request){
w.Header().Set("Content-Type", "application/json; charset=UTF-8")
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "POST, OPTIONS");
w.Header().Set("Access-Control-Allow-Headers", "*");
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
if r.Method != "POST" && r.Method != "OPTIONS" {
http.Error(w, "Unsupported method. Please check.", http.StatusNotFound)
return
}
var t_int rtc_int_token_struct
var unmarshalErr *json.UnmarshalTypeError
int_decoder := json.NewDecoder(r.Body)
int_err := int_decoder.Decode(&t_int)
if (int_err == nil) {
int_uid = t_int.Uid_rtc_int
channel_name = t_int.Channel_name
role_num = t_int.Role
switch role_num {
case 1:
role = rtctokenbuilder.RolePublisher
case 2:
role = rtctokenbuilder.RoleSubscriber
}
}
if (int_err != nil) {
if errors.As(int_err, &unmarshalErr){
errorResponse(w, "Bad request. Wrong type provided for field " + unmarshalErr.Value + unmarshalErr.Field + unmarshalErr.Struct, http.StatusBadRequest)
} else {
errorResponse(w, "Bad request.", http.StatusBadRequest)
}
return
}
generateRtcToken(int_uid, channel_name, role)
errorResponse(w, rtc_token, http.StatusOK)
log.Println(w, r)
}
func errorResponse(w http.ResponseWriter, message string, httpStatusCode int){
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Access-Control-Allow-Origin", "*")
w.WriteHeader(httpStatusCode)
resp := make(map[string]string)
resp["token"] = message
resp["code"] = strconv.Itoa(httpStatusCode)
jsonResp, _ := json.Marshal(resp)
w.Write(jsonResp)
}
func main(){
// 使用 int 型 uid 生成 RTC Token
http.HandleFunc("/fetch_rtc_token", rtcTokenHandler)
fmt.Printf("Starting server at port 8082\n")
if err := http.ListenAndServe(":8082", nil); err != nil {
log.Fatal(err)
}
}
go.mod
文件定义导入路径及依赖项。运行如下命令行来为你的 Token 服务器创建 go.mod
文件:
$ go mod init sampleServer
运行如下命令行安装依赖。你可以使用 Go 镜像进行加速,例如 https://goproxy.cn/ 。
$ go get
运行如下命令行启动服务器:
$ go run server.go
本节以 Web 客户端为例,展示如何使用 Token 对客户端的用户进行鉴权。
创建一个项目文件夹,其中包含如下文件:
index.html
:用户界面client.js
:使用声网 RTC Web SDK 4.x(必须为 4.8.0 或更高版本)的 app 逻辑|
|-- index.html
|-- client.js
在 index.html
中加入以下代码,创建用户界面:
<html>
<head>
<title>Token demo</title>
</head>
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<body>
<h1>Token demo</h1>
<script src="https://download.agora.io/sdk/release/AgoraRTC_N-4.8.0.js"></script>
<script src="./client.js"></script>
</body>
</html>
将如下代码贴入 client.js
文件中,实现客户端鉴权逻辑。
<Your App ID>
替换为你的 App ID。该 App ID 必须与 Token 生成代码中的 App ID 一致。<Your Host URL and port>
替换为你部署好的本地 Golang 服务器的主机 URL 和端口,如 10.53.3.234:8082
。var rtc = {
// 设置本地音频轨道和视频轨道。
localAudioTrack: null,
localVideoTrack: null,
};
var options = {
// 传入 App ID。
appId: "<Your app ID>",
// 传入频道名。
channel: "ChannelA",
// 设置用户为 host (可发流) 或 audience(仅可收流)。
role: "host"
};
// 从 Golang 服务器获取 Token。
function fetchToken(uid, channelName, tokenRole) {
return new Promise(function (resolve) {
axios.post('http://<Your Host URL and port>/fetch_rtc_token', {
uid: uid,
channelName: channelName,
role: tokenRole
}, {
headers: {
'Content-Type': 'application/json; charset=UTF-8'
}
})
.then(function (response) {
const token = response.data.token;
resolve(token);
})
.catch(function (error) {
console.log(error);
});
})
}
async function startBasicCall() {
const client = AgoraRTC.createClient({ mode: "live", codec: "vp8" });
client.setClientRole(options.role);
const uid = 123456;
// 将获取到的 Token 赋值给 join 方法中的 token 参数,然后加入频道。
let token = await fetchToken(uid, options.channel, 1);
await client.join(options.appId, options.channel, token, uid);
rtc.localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack();
rtc.localVideoTrack = await AgoraRTC.createCameraVideoTrack();
await client.publish([rtc.localAudioTrack, rtc.localVideoTrack]);
const localPlayerContainer = document.createElement("div");
localPlayerContainer.id = uid;
localPlayerContainer.style.width = "640px";
localPlayerContainer.style.height = "480px";
document.body.append(localPlayerContainer);
rtc.localVideoTrack.play(localPlayerContainer);
console.log("publish success!");
client.on("user-published", async (user, mediaType) => {
await client.subscribe(user, mediaType);
console.log("subscribe success");
if (mediaType === "video") {
const remoteVideoTrack = user.videoTrack;
const remotePlayerContainer = document.createElement("div");
remotePlayerContainer.textContent = "Remote user " + user.uid.toString();
remotePlayerContainer.style.width = "640px";
remotePlayerContainer.style.height = "480px";
document.body.append(remotePlayerContainer);
remoteVideoTrack.play(remotePlayerContainer);
}
if (mediaType === "audio") {
const remoteAudioTrack = user.audioTrack;
remoteAudioTrack.play();
}
client.on("user-unpublished", user => {
const remotePlayerContainer = document.getElementById(user.uid);
remotePlayerContainer.remove();
});
});
// 收到 token-privilege-will-expire 回调时,从服务器重新申请一个 Token,并调用 renewToken 将新的 Token 传给 SDK。
client.on("token-privilege-will-expire", async function () {
let token = await fetchToken(uid, options.channel, 1);
await client.renewToken(token);
});
// 收到 token-privilege-did-expire 回调时,从服务器重新申请一个 Token,并调用 join 重新加入频道。
client.on("token-privilege-did-expire", async function () {
console.log("Fetching the new Token")
let token = await fetchToken(uid, options.channel, 1);
console.log("Rejoining the channel with new Token")
await client.join(options.appId, options.channel, token, uid);
});
}
startBasicCall()
在上述代码示例中,你可以看到 Token 与客户端的以下代码逻辑有关:
join
方法,使用 Token、用户 ID 和频道名加入频道。用户 ID 和频道名必须和用于生成 Token 的用户 ID 和频道名一致。token-privilege-will-expire
回调。收到该回调后,客户端需要从服务器获取新的 Token 并调用 renewToken
方法将新生成的 Token 传给 SDK。token-privilege-did-expire
回调。收到该回调后,客户端需要从服务器获取新的 Token 并调用 join
方法,再使用新的 Token 重新加入频道。index.html
文件,可以看到客户端执行以下操作:本节提供与 Token 鉴权相关的参考文档。
AccessToken2 支持以下版本的声网 RTC SDK (不包括客户端旁路推流功能):
SDK | 版本 |
---|---|
RTC Native SDK | >= 3.6.0 |
RTC Electron SDK | >= 3.6.0 |
RTC Unity SDK | >= 3.6.0 |
RTC React Native SDK | >= 3.6.0 |
RTC Flutter SDK | >= 5.10 |
RTC Web SDK | >= 4.8.0 |
使用 AccessToken2 的 RTC SDK 可与使用 AccessToken 的 RTC SDK 互通。支持 AccessToken2 的 RTC SDK 也支持 AccessToken。
声网在 GitHub 上提供一个开源的 AgoraDynamicKey 仓库,支持使用 C++、Java、Go 等语言在你自己的服务器上生成 Token。
语言 | 算法 | 核心方法 | 示例代码 |
---|---|---|---|
C++ | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.cpp |
Go | HMAC-SHA256 | buildTokenWithUid | sample.go |
Java | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.java |
Node.js | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.js |
PHP | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.php |
Python | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.py |
Python3 | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.py |
本节介绍生成 AccessToken2 的核心方法 BuildTokenWithUid
。AccessToken2 生成器代码中提供两个 BuildTokenWithUid
方法:
BuildTokenWithUid
[1/2]:生成 AccessToken2,并设置 AccessToken2 和所有权限的过期时间。BuildTokenWithUid
[2/2]:生成 AccessToken2,并设置如下过期时间:该方法使用 token_expire
参数设置 AccessToken2 的过期时间,使用 privilege_expire
参数设置所有权限的过期时间。
// 以 C++ 为例
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 |
你在声网控制台创建项目时生成的 App ID。 |
appCertificate |
你的项目的 App 证书。 |
channelName |
频道名称,长度在 64 个字节以内。以下为支持的字符集范围:
|
uid |
待鉴权用户的用户 ID 32 位无符号整数,范围为1到 (2³² - 1), 并保证唯一性。 如不需对用户 ID 进行鉴权,即客户端使用任何 uid 都可加入频道,请把 uid 设为 0。 |
role |
用户权限,分为发流用户和接收用户。参数决定用户是否能在频道中发流。
|
token_Expire |
AccessToken2 从生成到过期的时间长度,单位为秒。例如,如果你将 token_Expire 设为 600 ,则 AccessToken2 会在生成后 10 分钟过期。AccessToken2 的最大有效期为 24 小时。 如果你将此参数设为超过 24 小时的时间,AccessToken2 有效期依然为 24 小时。如果你将此参数设为 0,AccessToken2 立即过期。 |
privilege_Expire |
从 AccessToken2 生成到所有权限过期的时间长度,单位为秒。例如,如果你将 privilege_Expire 设为 600 ,则权限会在生成后 10 分钟过期。如果你将此参数设为 0(默认值),则权限永不过期。 |
为支持在权限级别设置过期时间,声网还提供 BuildTokenWithUid
的同名重载方法。支持你设置 AccessToken2 的过期时间以及以下权限的过期时间:
// 以 C++ 为例
static std::string BuildTokenWithUid(
const std::string& app_id,
const std::string& app_certificate,
const std::string& channel_name,
uint32_t uid,
uint32_t token_expire,
uint32_t join_channel_privilege_expire = 0,
uint32_t pub_audio_privilege_expire = 0,
uint32_t pub_video_privilege_expire = 0,
uint32_t pub_data_stream_privilege_expire = 0);
该方法生成 RTC AccessToken2,支持你设置 AccessToken2 的过期时间以及以下权限的过期时间:
一个用户可以设置多个权限。每个权限的最大有效时间为 24 小时。权限即将过期或已经过期后,SDK 会分别触发 onTokenPriviegeWillExpire
或 onRequestToken
回调。你需要在 app 逻辑中添加如下操作:
renewToken
以更新 AccessToken2。你需要根据实际业务场景设置合理的过期时间。例如,如果加入频道的权限过期时间早于发布音频流权限的过期时间,则在加入频道的权限过期后,用户就会被踢出 RTC 频道;即便发布音频流的权限没有过期,对用户来讲这个权限是没有意义的。
参数 | 描述 |
---|---|
token_Expire |
AccessToken2 从生成到过期的时间长度,单位为秒。例如,如果你将 token_Expire 设为 600 ,则 AccessToken2 会在生成后 10 分钟过期。AccessToken2 的最大有效期为 24 小时。 如果你将此参数设为超过 24 小时的时间,AccessToken2 有效期依然为 24 小时。如果你将此参数设为 0,AccessToken2 立即过期。 |
join_channel_privilege_expire |
从 AccessToken2 生成到加入频道权限过期的时间长度,单位为秒。例如,如果你将此参数为 600 ,则加入频道权限会在 AccessToken2 生成后 10 分钟过期。如果你将此参数设为 0(默认值),则加入频道权限永不过期。 |
pub_audio_privilege_expire |
从 AccessToken2 生成到在频道内发布音频流的权限过期的时间长度,单位为秒。例如,如果你将此参数为 600 ,则发布语音流权限会在 AccessToken2 生成后 10 分钟过期。如果你将此参数设为 0(默认值),则发布语音流权限永不过期。 |
pub_video_privilege_expire |
从 AccessToken2 生成到在频道内发布视频流的权限过期的时间长度,单位为秒。例如,如果你将此参数为 600 ,则发布视频流权限会在 AccessToken2 生成后 10 分钟过期。如果你将此参数设为 0(默认值),则发布视频流权限永不过期。 |
pub_data_stream_privilege_expire |
从 AccessToken2 生成到在频道内发布数据流的权限过期的时间长度,单位为秒。例如,如果你将此参数为 600 ,则发布数据流权限会在 AccessToken2 生成后 10 分钟过期。如果你将此参数设为 0(默认值),则发布数据流权限永不过期。 |
请参考以下步骤在声网控制台开启连麦鉴权服务:
在控制台启用连麦鉴权后,该服务会在约 5 分钟后生效。
项目一旦开启了连麦鉴权服务,则用户在频道中发流需要同时满足两个条件:
setClientRole
中设置的 role
参数为 host
。BuildTokenWithUid
中设置的 role
参数为 kRolePublisher
)。声网提供 AccessToken 升级指南向你介绍如何使用 AccessToken 鉴权,如何升级至 AccessToken2。