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:

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.

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 will need to set appsign to empty during initialization.

ZegoUIKitPrebuiltCallService.init(
  KeyCenter.appID,
  '', // appsign
  userID,
  userName,
  [ZIM, ZPNs],
  ......
}

And then you need to listen to the ZegoUIKit.onTokenProvide callback at the appropriate place, and then return the token.

import ZegoUIKit from '@zegocloud/zego-uikit-rn'

ZegoUIKitPrebuiltCallService.useSystemCallingUI([ZIM, ZPNs]);

ZegoUIKit.onTokenProvide(async () => {
  try {
    // Request token from your serve.
    const response = await fetch('your url');
    const token = await response.text();
    console.log('token: ', token);

    // return the token.
    return token;
  } catch (error) {
    console.error('error:', error);
    return '';
  }
});

AppRegistry.registerComponent(appName, () => App);

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. Renew the token at the appropriate time, such as when the application enters the foreground.

Here is the reference code:

AppState.addEventListener('change', async nextState => {
  // 1. When the application comes to the foreground.
  if (nextState === 'active') {
    const oldTokenTimestamp = 123;
    const currentTimestamp = Date.now();

    // 2. Determine if the token will expire within a certain period of time (e.g., within 1 day).
    if (currentTimestamp - oldTokenTimestamp < 1000 * 24 * 60 * 60) {

      // 3. Retrieve the latest token from your server.
      const response = await fetch('your url');
      const token = await response.text();

      // 4. call `renewToken`
      ZegoUIKit.renewToken(token);

      // 5. save the current timestamp.
    }
  }
});