使用 Token 鉴权

---

1 功能简介

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

2 前提条件

• 基础鉴权 Token 默认开通，权限认证 Token（即房间 ID 和推流 ID 权限位）请联系 ZEGO 技术支持开通。
• 已在项目中集成 ZEGO Express SDK，并实现了基本的音视频推拉流功能，详情请参考：
  • 微信小程序 - 集成 SDK 和 微信小程序 - 实现流程，微信小程序 SDK 需要在 2.10.0 或以上版本。
  • 支付宝小程序 - 集成 SDK 和 支付宝小程序 - 实现流程。

3 实现流程

使用 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 再将校验的结果直接返回给开发者客户端，没有权限的客户端将登录失败。

4 使用步骤

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

4.1 获取 AppId 和 ServerSecret

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

4.2 生成 Token

zego_server_assistant 插件中用于服务端生成 Token 的各语言参考信息如下：

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

ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件，支持使用 Go、C++、Java、Objective-C、Python、PHP、.NET、Node.js 语言，在开发者的服务端部署生成 Token。

zego_server_assistant 插件中提供了生成权限认证 Token 的示例代码，权限认证 Token 是在登录房间鉴权后，为了进一步提高安全性，开放房间 ID 和推流 ID 这两个权限位，可以验证登录房间的 ID 和推流 ID，此时 “payload” 字段需要按照规格生成。权限位校验规则如下：

• 只校验登录权限：登录时校验权限，推流时不校验权限。
• 同时校验登录和推流权限：登录和推流时均校验权限。

zego_server_assistant 插件中用于服务端生成 Token 的各语言参考信息如下：

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

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

生成 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
    roomId := "demo"
    userId := "demo"
    serverSecret := "fa94dd0f974cf2e293728a526b028271"
    var effectiveTimeInSeconds int64 = 3600
    privilege := make(map[int]int)
    privilege[token04.PrivilegeKeyLogin] = token04.PrivilegeEnable
    privilege[token04.PrivilegeKeyPublish] = token04.PrivilegeDisable

    payloadData := &RtcRoomPayLoad{
        RoomId:       roomId,
        Privilege:    privilege,
        StreamIdList: nil,
    }

    payload, err := json.Marshal(payloadData)
    if err != nil {
        fmt.Println(err)
        return
    }

    token, err := token04.GenerateToken04(appId, userId, serverSecret, effectiveTimeInSeconds, string(payload))
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(token)
}

临时 Token 获取方式

为方便开发者体验使用 Token 鉴权，ZEGO 控制台 提供生成临时 Token 的功能，开发者可直接获取临时 Token 来使用，详情请参考 控制台 - 开发辅助。但是在开发者自己的线上环境中，一定要通过自己的服务端生成 Token。

4.3 使用 Token

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

let roomID = 'xxx' // 要登录的房间 ID
let token = 'xxxxxxxxxx' // 请求开发者服务端获取 
let user = {userID : 'xxxx'} // 房间内用户唯一标识
let loginResult = zg.loginRoom(roomID, token, user): Promise<boolean>

如果开发者需要在登录房间后修改推流权限位，可以调用 renewToken 接口更新 Token，更新后会影响下一次登推流的权限，之前已经成功的推流不受影响。

let token = await getToken(); // 重新请求开发者服务端获取 Token;
zg.renewToken(token); 

4.4 Token 过期时的处理方式

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

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

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

zg.on('tokenWillExpire',(roomID: string)=>{
    let token = await getToken(); // 重新请求开发者服务端获取 Token
    zg.renewToken(token);
});

5 API 参考