To avoid unauthorized service access or operations, ZEGOCLOUD uses digital Tokens to verify user identity, control and validate user privileges. You will need to pass a Token when you log in to a room.
Currently, ZEGOCLOUD supports validating the following:
To improve business security, we recommend you enable the room login and stream publishing privilege validation for all scenarios. In particular:
Before you start to implement user privilege authentication in your app, make sure you complete the following steps:
Contact ZEGOCLOUD Technical Support to enable the Room ID and Published stream ID authentication features.
Integrate the ZEGO Express SDK (version 2.14.0 or later) into your project and implement the basic audio and video features. For details, see Getting started - Integration and Getting started - Implementation.
Your app clients request Tokens from your app server and provide the Token for privilege validation when logging in to a room.
The following diagram shows the process of room login privilege validation:
Go to ZEGOCLOUD Admin Console to get the App ID and ServerSecret of your project.
After getting your AppID and ServerSecret, you can define the validation rules on your app server or client based on your business requirements.
Upon request from your app clients, your app server generates Tokens and sends the Tokens to the corresponding app clients.
ZEGOCLOUD provides an open-source Token generator plug-in on GitHub, which you can use to generate Tokens on your app server using different programming languages such as Go, C++, Java, Python, PHP,.NET, and Node.js.
For business security, you must generate Tokens on your app server; Otherwise, there is a risk of ServerSecret being stolen.
Language | Supported version | Core function | Code base | Sample code | |
---|---|---|---|---|---|
User identity Token | User privilege Token | ||||
Go |
Go 1.14.15 or later |
GenerateToken04 |
|||
C++ |
C++ 11 or later |
GenerateToken04 |
|||
Java |
Java 1.8 or later |
generateToken04 |
|||
Python |
Python 3.6.8 or later |
generate_token04 |
|||
PHP |
PHP 7.0 or later |
generateToken04 |
|||
.NET |
.NET Framework 3.5 or later |
GenerateToken04 |
|||
Node.js |
Node.js 8 or later |
generateToken04 |
Take Go language as an example, you can do the following steps to generate a Token:
GenerateToken04
method to generate a Token.The following code shows how to generate a Token:
package main
import (
"encoding/json"
"fmt"
"github.com/zegoim/zego_server_assistant/token/go/src/token04"
)
/*
Sample code for generating a user privilege Token:
*/
//Token-based business logic: RTC room-related authentication property
type RtcRoomPayLoad struct {
RoomId string `json:"room_id"` //Room ID: required parameter, used to to validate the room.
Privilege map[int]int `json:"privilege"` //User privilege authentication control list: used to validate user privileges
StreamIdList []string `json:"stream_id_list"` //Stream list: used to validate the stream. This value can be null, and no stream will be validated if it is null.
}
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)
}
To make it easier for you to try and test the user authentication feature, ZEGOCLOUD Admin Console provides a tool for generating temporary Tokens, which you can use directly in a testing environment. In production, you must generate Tokens on your app server.
When logging in to a room, you need to pass the Token, user, and roomID to the loginRoom
method. Otherwise, the login will fail.
The userID you used for room login (loginRoom
) must be the same with that of you used for generating Tokens.
let roomID = 'xxx' // The room ID of the room to log in to.
let token = 'xxxxxxxxxx' // The Token you get from your app server.
let user = {userID : 'xxxx'} // The unique identifier of the user.
let loginResult = zg.loginRoom(roomID, token, user): Promise<boolean>
If you need to modify the stream publishing privilege of a user after the user logged in to a room, call the renewToken
method to renew the Token. The updated privileges will take effect for the next stream publishing, but will not affect the current streams being published (if any).
let token = await getToken(); // Request a new Token from app server.
zg.renewToken(token);
30 seconds before a Token expires, the SDK sends out a notification through the tokenWillExpire
callback.
Upon receiving this callback, you need to get a new Token from your app server first, and then pass the new Token to the renewToken
method.
If the Token is not renewed, different SDK versions handle the Token expiration differently:
If the version of the ZEGO Express SDK you integrated is 2.6.0 - 2.10.0, and when your Token is expired:
If the version of the ZEGO Express SDK you integrated is 2.11.0 or later, and when your Token is expired:
If you enabled the room login privilege authentication (by validating the roomID), you must pass a new Token when logging in to a room.
zg.on('tokenWillExpire',(roomID: string)=>{
let token = await getToken(); // Request a new token from app server.
zg.renewToken(token);
});