Authenticate with Token

Feature Overview

Authentication verifies whether a user has permission to access the system, so as to avoid security risks caused by missing permission control or improper operations. ZEGO authenticates users through Tokens (including the basic authentication Token and the privilege authentication Token).

The privilege authentication Token means that, to further improve security, the room ID privilege bit is opened, which can verify the ID of the room being logged in to.

Prerequisites

• The basic authentication Token is enabled by default. For the privilege authentication Token (that is, the room ID privilege bit), contact ZEGOCLOUD Technical Support to enable it.
• The ZEGOCLOUD Local Server Recording SDK has been integrated into your project. See Quick Start - Integration.

Implementation Process

When using Token authentication, the developer needs to generate the Token first, and the ZEGO server verifies users carrying the Token.

Taking using a Token to determine whether a user can log in to a room as an example, the process is as follows:

1. The developer's client sends a request to apply for a Token.
2. The Token is generated on the developer's server and returned to the developer's client.
3. The developer's client carries the obtained Token and roomID information, and passes them into the SDK through the SetToken (C++) / setToken (Java) API.
4. The ZEGO SDK automatically sends the Token to the ZEGO server for verification.
5. The ZEGO server returns the verification result to the ZEGO SDK.
6. The ZEGO SDK then directly returns the verification result to the developer's client. Clients without permission fail to log in.

Steps

This section describes in detail how developers generate a Token and how to use a Token.

Obtain the AppID and ServerSecret

Generating a Token requires the AppID (the unique identifier of the developer's project) and the ServerSecret key. For details on obtaining them, see "Project Information" in Console - Project Management.

Generate a Token

Generate a Token on the server (recommended)

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

ZEGO provides an open-source zego_server_assistant plugin on GitHub/Gitee, which supports generating and deploying Tokens on the developer's server or client using Go, C++, Java, Objective-C, Python, PHP, .NET, and Node.js.

The zego_server_assistant plugin provides sample code for generating the basic authentication Token and the privilege authentication Token. Their applicable scenarios are as follows, and developers can choose as needed:

• Basic authentication Token: used for scenarios that require simple permission verification, where the "payload" field can be empty.
• Privilege authentication Token: to further improve security, the room ID privilege bit is opened, which can verify the ID of the room being logged in to. In this case, the "payload" field needs to be generated according to the rules. See the sample code in the "Privilege authentication Token" column of the table below.

The reference information for generating a Token on the server in each language in the zego_server_assistant plugin is as follows:

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

1. Run the command go get github.com/zegoim/zego_server_assistant to get the dependency package.
2. In your code, import the plugin via import "github.com/zegoim/zego_server_assistant/token/go/src/token04".
3. Call the GenerateToken04 method provided by the plugin to generate the Token.

The Token can be generated in the following two ways.

• Method 1: Basic authentication Token

  The sample code for generating the basic authentication Token is as follows:

package main

import (
    "fmt"
    "github.com/zegoim/zego_server_assistant/token/go/src/token04"
)

/*
Sample code for generating the basic authentication token
*/

func main() {
    var appId uint32 = 1                               // The numeric ID issued by Zego, the unique identifier of each developer
    userId := "demo"                                   // User ID
    serverSecret := "fa94dd0f974cf2e293728a1234567890" // The key used for AES encryption when obtaining the token
    var effectiveTimeInSeconds int64 = 3600            // The validity period of the token, in seconds
    var payload string = ""                            // The business privilege extension of the token; leave it empty for the basic authentication token

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

package main

import (
    "fmt"
    "github.com/zegoim/zego_server_assistant/token/go/src/token04"
)

/*
Sample code for generating the basic authentication token
*/

func main() {
    var appId uint32 = 1                               // The numeric ID issued by Zego, the unique identifier of each developer
    userId := "demo"                                   // User ID
    serverSecret := "fa94dd0f974cf2e293728a1234567890" // The key used for AES encryption when obtaining the token
    var effectiveTimeInSeconds int64 = 3600            // The validity period of the token, in seconds
    var payload string = ""                            // The business privilege extension of the token; leave it empty for the basic authentication token

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

• Method 2: Privilege authentication Token

  The sample code for generating the privilege authentication Token is as follows:

package main

import (
    "encoding/json"
    "fmt"
    "github.com/zegoim/zego_server_assistant/token/go/src/token04"
)

/*
Sample code for generating the privilege authentication token
*/

//Token business extension: privilege authentication properties
type RtcRoomPayLoad struct {
    RoomId       string      `json:"room_id"`        //Room ID (required); used for strict verification of the room ID of the API
    Privilege    map[int]int `json:"privilege"`      //Privilege bit switch list; used for strict verification of the operation permissions of the API
    StreamIdList []string    `json:"stream_id_list"` //Stream list; used for strict verification of the stream IDs of the API; can be empty. If empty, stream IDs are not verified
}

func main() {
    var appId uint32 = 1                               // The numeric ID issued by Zego, the unique identifier of each developer
    roomId := "demo"                                   // Room ID
    userId := "demo"                                   // User ID
    serverSecret := "fa94dd0f974cf2e293728a526b028271" // The key used for AES encryption when obtaining the token
    var effectiveTimeInSeconds int64 = 3600            // The validity period of the token, in seconds

    //Refer to the definition in github.com/zegoim/zego_server_assistant/token/go/src/token04/token04.go
    ////Privilege bit definition
    //const (
    //	PrivilegeKeyLogin   = 1 // Login privilege bit authentication
    //	PrivilegeKeyPublish = 2 // Publish privilege bit authentication
    //)

    ////Privilege switch definition
    //const (
    //	PrivilegeEnable     = 1 // With privilege
    //	PrivilegeDisable    = 0 // Without privilege
    //)

    //Business privilege authentication configuration, multiple privilege bits can be configured
    privilege := make(map[int]int)
    privilege[token04.PrivilegeKeyLogin] = token04.PrivilegeEnable    // With room login privilege
    privilege[token04.PrivilegeKeyPublish] = token04.PrivilegeDisable // Without publish privilege

    //Token business extension configuration
    payloadData := &RtcRoomPayLoad{
	RoomId:       roomId,
	Privilege:    privilege,
	StreamIdList: nil,
	}

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

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

package main

import (
    "encoding/json"
    "fmt"
    "github.com/zegoim/zego_server_assistant/token/go/src/token04"
)

/*
Sample code for generating the privilege authentication token
*/

//Token business extension: privilege authentication properties
type RtcRoomPayLoad struct {
    RoomId       string      `json:"room_id"`        //Room ID (required); used for strict verification of the room ID of the API
    Privilege    map[int]int `json:"privilege"`      //Privilege bit switch list; used for strict verification of the operation permissions of the API
    StreamIdList []string    `json:"stream_id_list"` //Stream list; used for strict verification of the stream IDs of the API; can be empty. If empty, stream IDs are not verified
}

func main() {
    var appId uint32 = 1                               // The numeric ID issued by Zego, the unique identifier of each developer
    roomId := "demo"                                   // Room ID
    userId := "demo"                                   // User ID
    serverSecret := "fa94dd0f974cf2e293728a526b028271" // The key used for AES encryption when obtaining the token
    var effectiveTimeInSeconds int64 = 3600            // The validity period of the token, in seconds

    //Refer to the definition in github.com/zegoim/zego_server_assistant/token/go/src/token04/token04.go
    ////Privilege bit definition
    //const (
    //	PrivilegeKeyLogin   = 1 // Login privilege bit authentication
    //	PrivilegeKeyPublish = 2 // Publish privilege bit authentication
    //)

    ////Privilege switch definition
    //const (
    //	PrivilegeEnable     = 1 // With privilege
    //	PrivilegeDisable    = 0 // Without privilege
    //)

    //Business privilege authentication configuration, multiple privilege bits can be configured
    privilege := make(map[int]int)
    privilege[token04.PrivilegeKeyLogin] = token04.PrivilegeEnable    // With room login privilege
    privilege[token04.PrivilegeKeyPublish] = token04.PrivilegeDisable // Without publish privilege

    //Token business extension configuration
    payloadData := &RtcRoomPayLoad{
	RoomId:       roomId,
	Privilege:    privilege,
	StreamIdList: nil,
	}

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

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

Generate a Token on the client (not recommended)

If you cannot distribute the Token from the server yet during development, you can first use client-side code to generate the Token, and complete the integration after the server-side development is done.

The reference information for generating a Token on the client in each language in the zego_server_assistant plugin is as follows:

Set the Token

LIVEROOM::SetToken("Token", "roomID"); // Replace the Token and roomID with the actually obtained information

LIVEROOM::SetToken("Token", "roomID"); // Replace the Token and roomID with the actually obtained information

public void setToken(String token, String roomID); // Replace the Token and roomID with the actually obtained information

public void setToken(String token, String roomID); // Replace the Token and roomID with the actually obtained information