鉴权是指验证用户是否拥有访问系统的权限,来避免因权限控制缺失或操作不当引发的安全风险问题,ZEGO 通过 Token(包括基础鉴权 Token 和权限认证 Token) 对用户进行鉴权。
鉴权方式 | 描述 | 应用场景 |
---|---|---|
基础鉴权 Token | 开发者在登录房间时必须带上 Token 参数,来验证用户的合法性。 | 基础鉴权 Token 为 Token 的基本能力,用于业务的简单权限验证场景,绝大多数情况下生成该 Token 即可。 |
权限认证 Token | 为了进一步提高安全性开放了房间 ID 和推流 ID 这两个权限位,可以验证登录房间的 ID 和推流 ID。 | 房间 ID 和推流 ID 权限位的一般使用场景如下:
|
若您集成的是 2.17.0 之前版本的 ZEGO Express SDK(使用 AppSign 鉴权),现在想升级到 2.17.0 版本且使用 Token 鉴权,可以通过 如何从 AppSign 鉴权升级为 Token 鉴权 文档了解 AppSign 鉴权和 Token 鉴权更多信息。
使用 Token 鉴权时,需要开发者先生成 Token,再携带 Token 登录房间。ZEGO 服务端对带着 Token 的用户进行校验。
以使用 Token 判断用户是否能登录房间为例介绍使用流程,如下图:
使用 Token 鉴权时,需要开发者先生成 Token,您再携带 Token 登录场景,ZEGO 服务端对带着 Token 的用户进行校验。
以使用 Token 判断用户是否能登录场景为例介绍使用流程,如下图:
本节将详细介绍开发者如何通过服务端生成 Token、如何使用 Token 和 Token 过期时的处理方式。
生成 Token 需要开发者项目的唯一标识 AppID 和密钥 ServerSecret,请参考 控制台 - 项目管理 中的 “项目信息”获取。
开发者获得项目的 AppID 和 ServerSecret 信息后,根据实际业务需求,即可在自己的服务端生成 Token。开发者客户端向开发者服务端发送申请 Token 请求,由开发者服务端生成 Token 后返回给对应客户端。
基础鉴权 Token:用于业务的简单权限验证的场景,生成基础鉴权 Token 时,“payload” 字段传空。
Token 临时获取方式:为方便开发者调试,ZEGO 控制台 提供生成临时 Token 的功能,开发者可直接获取临时 Token 来使用,详情请参考 控制台 - 开发辅助。但是在开发者自己的线上环境中,一定要通过自己的服务端生成 Token。
ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件,请使用插件中的 “token04” 版本来生成 Token。插件支持 Go、C++、Java、Objective-C、Python、PHP、.NET、Node.js 语言:
语言 | 支持版本 | 关键函数 | 代码库地址 | 基础鉴权 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 示例代码如下:
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 和 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。若未处理,不同版本对 Token 过期的处理机制有所不同:
若开启了房间 ID 权限位,用户登录房间时必须主动传入新的 Token。
@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 过期的处理机制如下:
若开启了登录权限校验,用户登录场景时必须主动传入新的 Token。
public void onSceneTokenWillExpire(ZegoRangeScene rangeScene, int remainTimeInSecond) {
super.onSceneTokenWillExpire(rangeScene, remainTimeInSecond);
String token = getToken(); // 重新请求开发者服务端获取 Token;
// 请切换线程调用 renewToken
rangeScene.renewToken(token);
}
权限认证 Token:为了进一步提高安全性,开放房间 ID 和推流 ID 这两个权限位,可以验证登录房间的 ID 和推流 ID,此时 “payload” 字段需要按照规则生成,权限位校验规则如下:
ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件,支持使用 Go、C++、Java、Objective-C、Python、PHP、.NET、Node.js 语言生成 Token:
语言 | 权限认证 Token |
---|---|
Go |
|
C++ |
|
Java |
|
Python |
|
PHP |
|
.NET |
|
Node.js |
以 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 的示例代码如下:
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 的 Java 源码时,如果出现 “java.security.InvalidKeyException:illegal Key Size” 异常提示,请参考 相关常见问题文档 解决。
若您在开发过程中还无法通过服务端下发 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 过期回调 |
联系我们
文档反馈