使用 Token 鉴权

功能介绍

鉴权是指验证用户是否拥有访问系统的权限，来避免因权限控制缺失或操作不当引发的安全风险问题，ZEGO 通过 Token（包括基础鉴权 Token 和权限认证 Token） 对用户进行鉴权。

前提条件

流程概述

场景 1：登录房间场景

使用 Token 鉴权时，需要开发者先生成 Token，再携带 Token 登录房间。ZEGO 服务端对带着 Token 的用户进行校验。

以使用 Token 判断用户是否能登录房间为例介绍使用流程，如下图：

1. 开发者客户端发起申请 Token 的请求。
2. 在开发者的服务端上生成 Token，并返回给开发者客户端。
3. 开发者客户端携带申请到的 Token 和 userID、roomID 信息，登录对应的房间。
4. ZEGO SDK 会自动将 Token 发送到 ZEGO 服务端进行校验。
5. ZEGO 服务端会将校验结果返回给 ZEGO SDK。
6. ZEGO SDK 再将校验的结果直接返回给开发者客户端，没有权限的客户端将登录失败。

场景 2：登录万人音视频的范围场景

生成并使用 Token 登录万人音视频的范围场景

使用 Token 鉴权时，需要开发者先生成 Token，您再携带 Token 登录场景，ZEGO 服务端对带着 Token 的用户进行校验。

以使用 Token 判断用户是否能登录场景为例介绍使用流程，如下图：

1. 开发者客户端发起申请 Token 的请求。
2. 在开发者的服务端上生成 Token，并返回给开发者客户端。
3. 开发者客户端携带申请到的 Token 和 userID、sceneID 信息，登录对应的场景。
4. ZEGO SDK 会自动将 Token 发送到 ZEGO 服务端进行校验。
5. ZEGO 服务端会将校验结果返回给 ZEGO SDK。
6. ZEGO SDK 再将校验的结果直接返回给开发者客户端，没有权限的客户端将登录失败。

生成 Token 与使用

本节将详细介绍开发者如何通过服务端生成 Token、如何使用 Token 和 Token 过期时的处理方式。

1 获取 AppID 和 ServerSecret

生成 Token 需要开发者项目的唯一标识 AppID 和密钥 ServerSecret，请参考 控制台 - 项目管理 中的 “项目信息”获取。

开发者获得项目的 AppID 和 ServerSecret 信息后，根据实际业务需求，即可在自己的服务端生成 Token。开发者客户端向开发者服务端发送申请 Token 请求，由开发者服务端生成 Token 后返回给对应客户端。

2 在服务端生成 Token

ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件，请使用插件中的 “token04” 版本来生成 Token。插件支持 Go、C++、Java、Objective-C、Python、PHP、.NET、Node.js 语言：

以 Go 语言为例，开发者可参考以下步骤使用 zego_server_assistant 生成 Token：

1. 使用命令 git clone https://github.com/zegoim/zego_server_assistant 获取依赖包。
2. 在您的代码中，通过 import "github.com/zegoim/zego_server_assistant/token/go/src/token04" 引入插件。
3. 调用插件提供的 GenerateToken04 方法生成 Token。

3 使用 Token

场景 1：登录房间场景

用户携带获取到的 Token 和 user、roomID 信息，通过 loginRoom 接口登录对应的房间。

String roomID = "xxx" // 要登录的房间ID
ZegoUser user = new ZegoUser("xxxx");
ZegoRoomConfig config = new ZegoRoomConfig();
config.token = "xxxxxxxxxx"; // 请求开发者服务端获取
engine.loginRoom(roomID, user, config);

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);

String token = getToken(); // 重新请求开发者服务端获取 Token;
engine.renewToken(roomID, token);

场景 2：登录万人音视频的范围场景

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) {
    }
});

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) {
    }
});

4 Token 过期处理机制

场景 1：登录房间场景

在 Token 过期前 30 秒，SDK 会通过 onRoomTokenWillExpire 回调发出通知。

收到该回调后，开发者需要从自己的服务端获取新的有效 Token，并调用 SDK 提供的 renewToken 接口更新 Token。

若您接入的是 2.17.0 及以上版本的 ZEGO Express SDK，在 Token 过期后，未调用 renewToken 接口更新 Token，则当权限过期时：

• 已登录的用户不会被踢出房间。
• 当前已成功的推拉流不受影响。但是停止推流后无法再推流，除非更新 Token。

@Override
public void onRoomTokenWillExpire(String roomID, int remainTimeInSecond){
    String token = getToken(); // 重新请求开发者服务端获取 Token;
    engine.renewToken(roomID, token);
}

@Override
public void onRoomTokenWillExpire(String roomID, int remainTimeInSecond){
    String token = getToken(); // 重新请求开发者服务端获取 Token;
    engine.renewToken(roomID, token);
}

场景 2：范围场景模块

public void onSceneTokenWillExpire(ZegoRangeScene rangeScene, int remainTimeInSecond) {
    super.onSceneTokenWillExpire(rangeScene, remainTimeInSecond);
    String token = getToken(); // 重新请求开发者服务端获取 Token;
    // 请切换线程调用 renewToken
    rangeScene.renewToken(token);
}

public void onSceneTokenWillExpire(ZegoRangeScene rangeScene, int remainTimeInSecond) {
    super.onSceneTokenWillExpire(rangeScene, remainTimeInSecond);
    String token = getToken(); // 重新请求开发者服务端获取 Token;
    // 请切换线程调用 renewToken
    rangeScene.renewToken(token);
}

其他

API 参考

相关文档

如何防止音视频互动中的幽灵麦或炸房的现象？