logoUIKit
On this page

Use Tokens for authentication

Introduction

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.

Understand the process

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:

  1. Your app client requests a Token from your app server.
  2. Your app server generates a Token and passes it to the client.
  3. Your app client logs in to a room with userID, roomID, and the Token.
  4. The ZEGOCLOUD SDK sends the Token to the ZEGO server for validation.
  5. The ZEGOCLOUD server returns the validation result to the ZEGO Express SDK.
  6. The ZEGOCLOUD SDK returns the validation result to the app client. If the validation passes, the user logs in to the room successfully; otherwise, the login fails.

Get the AppID and ServerSecret

Go to ZEGOCLOUD Admin Console to get the App ID and ServerSecret of your project.

Generate a Token on your app server

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.

Currently, the Token generator we provided supports generating the following two types of Tokens:

Token typeDescriptionUse Cases
User identity TokenDevelopers must include the Token parameter when logging into a room to verify the user's legitimacy.The user identity Token is used for simple permission verification in most business scenarios. In most cases, generating this Token is sufficient.
User privilege TokenTo further enhance security, room ID and stream ID privileges are opened to verify the logged-in room ID and stream ID.The general use cases for room ID and stream ID privileges are as follows:
- Distinguishing between regular rooms and member rooms, and controlling non-member users from logging into member rooms.
- In voice chat rooms or live streaming scenarios, ensuring consistency between streaming users and users on the microphone to prevent "ghost microphone" phenomenon, where non-microphone users' voices are heard in the room.
- In games like Werewolf, preventing hackers from using other user IDs to log into the same room after cracking the application, obtaining game information, and cheating, which affects the gaming experience of normal users.

When generating two types of tokens, the payload requirements are as follows:

  • User identity Token: To check the user's identity, you can pass null to the payload field.
  • User privilege Token: To check the user's permissions based on the room ID and the streamed ID, you need to generate a valid payload field according to the following validation rules:
    • Validate room login permission only: Add the enable room validation configuration and disable stream publishing permission configuration to the privilege field of the payload. Set room_id to a valid room ID.
    • Validate stream publishing permission only: Add the disable room validation configuration and enable stream publishing permission configuration to the privilege field of the payload. Set stream_id_list to a valid list of stream IDs.
    • Validate both room login and stream publishing permissions: Add the enable room validation configuration and enable stream publishing permission configuration to the privilege field of the payload. Set room_id to a valid room ID and stream_id_list to a valid list of stream IDs.
Warning

For business security, you must generate Tokens on your app server; Otherwise, there is a risk of ServerSecret being stolen.

LanguageSupported versionCore functionCode baseExample - User identity TokenExample - User privilege Token
GoGo 1.14.15 or laterGenerateToken04
C++C++ 11 or laterGenerateToken04
JavaJava 1.8 or latergenerateToken04
PythonPython 3.6.8 or latergenerate_token04
PHPPHP 7.0 or latergenerateToken04
.NET.NET Framework 3.5 or laterGenerateToken04
Node.jsNode.js 8 or latergenerateToken04

How to get a temporary 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.

Use a Token

If you need to use a token instead of appsign, you can call newInstanceWithToken to finish the initialization.

Untitled
ZegoUIKitPrebuiltLiveAudioRoomFragment.newInstanceWithToken(appID, token, userID, userName, roomID, config)
1
Copied!

Renew a Token

In most cases, the token retrieval approach mentioned above should work fine. However, in certain extreme situations, it may be unreliable.

To ensure the reliability of the token, you can make the following modifications:

  1. The validity period of the token should be set as long as possible, for example, 3 days.
  2. Listen to onTokenWillExpire callback and call renewToken to update new token.
Untitled
ZegoUIKit.setTokenWillExpireListener(new ZegoUIKitTokenExpireListener() {
    @Override
    public void onTokenWillExpire(int second) {
        // ...
        ZegoUIKit.renewToken(token);
    }
});
1
Copied!
  1. Renew the token at the appropriate time, such as when the application enters the foreground.
Untitled
// ...
ZegoUIKit.renewToken(token)
1
Copied!

Previous

Send virtual gifts

Next

Migrating to zegocloud maven