Using Token Authentication

Feature Introduction

Authentication refers to verifying whether users have permission to access the system to avoid security risk issues caused by lack of permission control or improper operation. ZEGO authenticates users through Token (including basic authentication Token and privilege authentication Token).

Prerequisites

Process Overview

When using Token authentication, developers need to generate Token first, and then log into the room with Token. The ZEGO server verifies users with Token.

Taking using Token to determine whether users can log into the room as an example to introduce the usage process, as shown in the following figure:

1. The developer client initiates a request to apply for Token.
2. Generate Token on the developer's server and return it to the developer client.
3. The developer client carries the applied Token and userID, roomID information to log into the corresponding room.
4. ZEGO SDK will automatically send Token to the ZEGO server for verification.
5. The ZEGO server will return the verification result to the ZEGO SDK.
6. The ZEGO SDK then directly returns the verification result to the developer client, and clients without permission will fail to log in.

Generate Token and Use

This section will detail how developers generate Token through the server, how to use Token, and how to handle Token expiration.

1 Get AppID and ServerSecret

Generating Token requires the AppID, the unique identifier of the developer project, and the ServerSecret key. Please refer to "Project Information" in Console - Project Management to obtain them.

After the developer obtains the AppID and ServerSecret information of the project, they can generate Token on their own server according to actual business needs. The developer client sends a request to apply for Token to the developer server, and the developer server generates Token and returns it to the corresponding client.

2 Generate Token on Server

ZEGO provides an open source zego_server_assistant plugin on GitHub/Gitee. Please use the "token04" version in the plugin to generate Token. The plugin supports Go, C++, Java, Objective-C, Python, PHP, .NET, Node.js languages:

Taking Go language as an example, developers can refer to the following steps to use zego_server_assistant to generate Token:

1. Use the command git clone https://github.com/zegoim/zego_server_assistant to get the dependency package.
2. In your code, introduce the plugin through import "github.com/zegoim/zego_server_assistant/token/go/src/token04".
3. Call the GenerateToken04 method provided by the plugin to generate Token.

3 Use Token

Users carry the obtained Token and user, roomID information to log into the corresponding room.

let roomConfig = new ZegoRoomConfig()
roomConfig.token = 'xxxxxxxx' // Request from developer server to obtain

// Login room
this.engine.loginRoom('your_room_id', new ZegoUser('user_id'), roomConfig)

let roomConfig = new ZegoRoomConfig()
roomConfig.token = 'xxxxxxxx' // Request from developer server to obtain

// Login room
this.engine.loginRoom('your_room_id', new ZegoUser('user_id'), roomConfig)

If developers need to modify the user's publishing permission after the user logs into the room, they can also call the renewToken interface to update the permission. After updating, it will affect the next publishing permission. The previously successful publishing will not be affected.

let token = 'xxxxxxxx' // Re-request from developer server to obtain Token
this.engine.renewToken('your_room_id', token)

let token = 'xxxxxxxx' // Re-request from developer server to obtain Token
this.engine.renewToken('your_room_id', token)

4 Handling Token Expiration

30 seconds before Token expires, the SDK will send a notification through the onRoomTokenWillExpire callback; after Token expires, when logging into the room again, you will receive the 1002078 (Token expired) error code through onDebugError or onRoomStateChanged.

After receiving the Token expiration callback or Token expiration error code, developers need to obtain a new valid Token from their own server and call the renewToken interface provided by the SDK to update the Token.

If you have integrated ZEGO Express SDK version 2.17.0 or above, after Token expires, if you do not call the renewToken interface to update Token, when the permission expires:

• Logged in users will not be kicked out of the room.
• Currently successful publishing and playing will not be affected. However, after stopping publishing, you cannot publish again unless you update the Token.

onRoomTokenWillExpire(roomID: string, remainTimeInSecond: number): void {
  let token = 'xxxxxxxx' // Re-request from developer server to obtain Token
  this.engine.renewToken('your_room_id', token)
}

onRoomTokenWillExpire(roomID: string, remainTimeInSecond: number): void {
  let token = 'xxxxxxxx' // Re-request from developer server to obtain Token
  this.engine.renewToken('your_room_id', token)
}

Other

API Reference

Related Documentation

How to prevent ghost mic or room bombing in audio/video interaction?