鉴权是指验证用户是否拥有访问系统的权限,来避免因权限控制缺失或操作不当引发的安全风险问题,ZEGO 通过 Token(包括基础鉴权 Token 和权限认证 Token) 对用户进行鉴权。
鉴权方式 | 描述 | 应用场景 |
---|---|---|
基础鉴权 Token | 开发者在登录房间时必须带上 Token 参数,来验证用户的合法性。 | 基础鉴权 Token 为 Token 的基本能力,用于业务的简单权限验证场景,绝大多数情况下生成该 Token 即可。 |
权限认证 Token | 为了进一步提高安全性开放了房间 ID 和推流 ID 这两个权限位,可以验证登录房间的 ID 和推流 ID。 | 房间 ID 和推流 ID 权限位的一般使用场景如下:
|
基础鉴权 Token 默认开通,权限认证 Token(即房间 ID 和推流 ID 权限位)请联系 ZEGO 技术支持开通。
使用 Token 鉴权时,需要开发者先生成 Token,再携带 Token 登录房间。ZEGO 服务端对带着 Token 的用户进行校验。
以使用 Token 判断用户是否能登录房间为例介绍使用流程,如下图:
使用 Token 鉴权时,需要开发者先生成 Token,您再携带 Token 登录场景,ZEGO 服务端对带着 Token 的用户进行校验。
以使用 Token 判断用户是否能登录场景为例介绍使用流程,如下图:
本节将详细介绍开发者如何通过服务端生成 Token、如何使用 Token 和 Token 过期时的处理方式。
生成 Token 需要开发者项目的唯一标识 AppID 和密钥 ServerSecret,请参考 控制台 - 项目管理 中的 “项目信息”获取。
开发者获得项目的 AppID 和 ServerSecret 信息后,根据实际业务需求,即可在自己的服务端生成 Token。开发者客户端向开发者服务端发送申请 Token 请求,由开发者服务端生成 Token 后返回给对应客户端。
Token 临时获取方式:为方便开发者调试,ZEGO 控制台 提供生成临时 Token 的功能,开发者可直接获取临时 Token 来使用,详情请参考 控制台 - 开发辅助。但是在开发者自己的线上环境中,一定要通过自己的服务端生成 Token。
ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件,请使用插件中的 “token04” 版本来生成 Token。插件支持 Go、C++、Java、Objective-C、Python、PHP、.NET、Node.js 语言:
语言 | 支持版本 | 关键函数 | 插件下载地址 | 使用示例 | |
---|---|---|---|---|---|
基础鉴权 Token | 权限认证 Token | ||||
Go |
Go 1.14.15 或以上版本 |
GenerateToken04 |
|||
C++ |
C++ 11 或以上版本 |
GenerateToken04 |
|||
Java |
Java 1.8 或以上版本 |
generateToken04 |
|||
Python |
Python 3.6.8 或以上版本 |
generate_token04 |
|||
PHP |
PHP 5.6 或以上版本 |
generateToken04 |
|||
.NET |
.NET Framework 3.5 或以上版本 |
GenerateToken04 |
|||
Node.js |
Node.js 8 或以上版本 |
generateToken04 |
以 Go 语言为例,开发者可参考以下步骤使用 zego_server_assistant 生成 Token:
go get github.com/zegoim/zego_server_assistant
获取依赖包。import "github.com/zegoim/zego_server_assistant/token/go/src/token04"
引入插件。范围场景模块暂不支持权限认证 Token。
生成基础鉴权 Token 时,“payload” 字段传空,具体示例代码如下:
package main
import (
"fmt"
"github.com/zegoim/zego_server_assistant/token/go/src/token04"
)
/*
基础鉴权token生成示例代码
*/
func main() {
var appId uint32 = 1 // Zego派发的数字ID, 各个开发者的唯一标识
userId := "demo" // 用户 ID
serverSecret := "fa94dd0f974cf2e293728a526b028271" // 在获取 token 时进行 AES 加密的密钥
var effectiveTimeInSeconds int64 = 3600 // token 的有效时长,单位:秒
var payload string = "" // token业务认证扩展,基础鉴权token此处填空
//生成token
token, err := token04.GenerateToken04(appId, userId, serverSecret, effectiveTimeInSeconds, payload)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(token)
}
生成权限认证 Token 时必须传入 “RoomId”。
package main
import (
"encoding/json"
"fmt"
"github.com/zegoim/zego_server_assistant/token/go/src/token04"
)
/*
权限认证token生成示例代码
*/
//token业务扩展:权限认证属性
type RtcRoomPayLoad struct {
RoomId string `json:"room_id"` //房间 id(必填);用于对接口的房间 id 进行强验证
Privilege map[int]int `json:"privilege"` //权限位开关列表;用于对接口的操作权限进行强验证
StreamIdList []string `json:"stream_id_list"` //流列表;用于对接口的流 id 进行强验证;允许为空,如果为空,则不对流 id 验证
}
func main() {
var appId uint32 = 1 // Zego派发的数字ID, 各个开发者的唯一标识
roomId := "demo" // 房间 ID
userId := "demo" // 用户 ID
serverSecret := "fa94dd0f974cf2e293728a526b028271" // 在获取 token 时进行 AES 加密的密钥
var effectiveTimeInSeconds int64 = 3600 // token 的有效时长,单位:秒
//请参考 github.com/zegoim/zego_server_assistant/token/go/src/token04/token04.go 定义
////权限位定义
//const (
// PrivilegeKeyLogin = 1 // 登录权限位认证
// PrivilegeKeyPublish = 2 // 推流权限位认证
//)
////权限开关定义
//const (
// PrivilegeEnable = 1 // 有权限
// PrivilegeDisable = 0 // 无权限
//)
//业务权限认证配置,可以配置多个权限位
privilege := make(map[int]int)
privilege[token04.PrivilegeKeyLogin] = token04.PrivilegeEnable // 有房间登录权限
privilege[token04.PrivilegeKeyPublish] = token04.PrivilegeDisable // 无推流权限
//token业务扩展配置
payloadData := &RtcRoomPayLoad{
RoomId: roomId,
Privilege: privilege,
StreamIdList: nil,
}
payload, err := json.Marshal(payloadData)
if err != nil {
fmt.Println(err)
return
}
//生成token
token, err := token04.GenerateToken04(appId, userId, serverSecret, effectiveTimeInSeconds, string(payload))
if err != nil {
fmt.Println(err)
return
}
fmt.Println(token)
}
用户携带获取到的 Token 和 user、roomID 信息,通过 loginRoom 接口登录对应的房间。
调用 loginRoom 接口登录房间时使用的 userID,必须和 “4.2 在服务端生成 Token” 时使用的 userID 保持一致。
String roomID = "xxx" // 要登录的房间ID
ZegoUser user = new ZegoUser("xxxx");
ZegoRoomConfig config = new ZegoRoomConfig();
config.token = "xxxxxxxxxx"; // 请求开发者服务端获取
engine.loginRoom(roomID, user, config);
如果开发者需要在登录房间后修改权限位,也可以调用 renewToken 接口更新 Token,更新后会影响下一次登录某些房间和推某些流的权限,之前已经成功的房间登录和推流不受影响。
String token = getToken(); // 重新请求开发者服务端获取 Token;
engine.renewToken(roomID, token);
用户携带获取到的 Token 和 user、sceneID 信息,登录对应的场景。
调用 loginScene 接口登录场景时使用的 userID,必须和 “4.2 在服务端生成 Token” 时使用的 userID 保持一致。
long sceneID = 123L; // 要登录的场景 ID
ZegoUser user = new ZegoUser("xxxx");
ZegoSceneParam config = new ZegoSceneParam();
param.sceneID = sceneID;
param.user = user;
param.token = @"xxxxxxxx"; // 请求开发者服务端获取
rangeScene.loginScene(param, new IZegoRangeSceneLoginSceneCallback() {
@Override
public void onLoginSceneCallback(int errorCode, ZegoSceneConfig config) {
}
});
Token 过期可能导致推拉流异常等问题,请严格按照以下说明,及时处理过期 Token。
在 Token 过期前 30 秒,SDK 会通过 onRoomTokenWillExpire 回调发出通知。
收到该回调后,开发者需要从自己的服务端获取新的有效 Token,并调用 SDK 提供的 renewToken 接口更新 Token。
若您接入的是 2.17.0 及以上版本的 ZEGO Express SDK,在 Token 过期后,未调用 renewToken 接口更新 Token,则当权限过期时:
ZEGO 还提供了另一种 Token 过期处理方式,您可以联系 ZEGO 技术支持配置:
@Override
public void onRoomTokenWillExpire(String roomID, int remainTimeInSecond){
String token = getToken(); // 重新请求开发者服务端获取 Token;
engine.renewToken(roomID, token);
}
在 Token 过期前 30 秒,SDK 会通过 onSceneTokenWillExpire 回调发出通知。
收到该回调后,开发者需要从自己的服务端获取新的有效 Token,并调用 SDK 提供的 ZegoRangeScene.renewToken 接口更新 Token。若未处理,Token 过期的处理机制如下:
public void onSceneTokenWillExpire(ZegoRangeScene rangeScene, int remainTimeInSecond) {
super.onSceneTokenWillExpire(rangeScene, remainTimeInSecond);
String token = getToken(); // 重新请求开发者服务端获取 Token;
// 请切换线程调用 renewToken
rangeScene.renewToken(token);
}
若您在开发过程中还无法通过服务端下发 Token 时,可以先使用客户端代码生成 Token,待服务端开发完后,再完成对接。
zego_server_assistant 插件中用于客户端生成 Token 的各语言参考信息如下:
语言 | 支持版本 | 关键函数 | 具体地址 |
---|---|---|---|
C++ |
C++ 11 或以上版本 |
GenerateToken04 |
|
Java |
Java 1.8 或以上版本 |
generateToken04 |
|
Objective-C |
- |
GenerateToken04 |
如需使用客户端生成 Token,请参考 4.3 使用 Token。
若 Token 过期,请参考 4.4 Token 过期时的处理方式 进行处理。
方法 | 描述 |
---|---|
loginRoom | 登录房间 |
renewToken | 更新 Token |
onRoomTokenWillExpire | Token 过期回调 |
联系我们
文档反馈