From 88f2a50188e5e949a1ddf832097f797a4bdf5f88 Mon Sep 17 00:00:00 2001 From: Dasun Nirmitha Date: Thu, 27 Jun 2024 00:32:54 +0530 Subject: [PATCH] ENDOC-283 Update token-authentication --- .../authentication-workflow/index.mdx | 45 ++++++++++++++++++- .../project-implementation/web.mdx | 4 +- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/shared/video-sdk/authentication-workflow/index.mdx b/shared/video-sdk/authentication-workflow/index.mdx index e26cef2ee..2d4c78aad 100644 --- a/shared/video-sdk/authentication-workflow/index.mdx +++ b/shared/video-sdk/authentication-workflow/index.mdx @@ -301,6 +301,36 @@ The user ID and channel name used to join a channel must be consistent with the ## Advanced authentication features This section presents advanced functions related to token authentication. + + +### Handle token expiration + +After joining a channel with a Token, 30 seconds before the Token expires, the SDK triggers the `token-privilege-will-expire` callback. After receiving this callback, the client needs to get a new Token from the server and call the `renewToken` method to pass the newly generated Token to the SDK. + +The sample code is as follows: + + ```javascript + // When the token-privilege-will-expire callback is received, re-request a Token from the server and call renewToken to pass the new Token to the SDK. + client.on("token-privilege-will-expire", async function () { + let token = await fetchToken(uid, options.channel, 1); + await client.renewToken(token); + }); + ``` + +When the Token expires, the SDK triggers the `token-privilege-did-expire` callback. After the client receives this callback, the client needs to get a new token from the server and call the `join` method to rejoin the channel with the new token as follows: + + ```javascript + // When the token-privilege-did-expire callback is received, request a new token from the server and call join to rejoin the channel. + client.on("token-privilege-did-expire", async function () { + console.log("Fetching the new Token") + let token = await fetchToken(uid, options.channel, 1); + console.log("Rejoining the channel with new Token") + await client.join(options.appId, options.channel, token, uid); + }); + ``` + + + ### Generate wildcard token​s In scenarios where users need to join multiple channels, or frequently switch between channels, they need to request a new token from the token server, each time they join a channel. To solve the problem of frequently requesting tokens when switching channels, enables you to generate wildcard tokens that set the user ID or channel name as a wildcard. Users reuse the same wildcard token to join different channels, which speeds up the process of switching and joining channels. It also helps reduce the pressure on your token server. @@ -665,6 +695,15 @@ if __name__ == "__main__": +### Microphone authentication + + supports fine control of the permissions of users posting different streams within a channel, which ensures that users posting streams within a channel are authorized, thereby preventing hackers from taking advantage of business loopholes or stealing tokens to bomb live broadcast rooms. + + +- Before setting up, please make sure you have enabled the microphone authentication function. +- Only users with the **host** role can send streams in the channel. Call the `setClientRole` method and set the role to **host**. + + ## Deployment and debugging​ This section shows you how to quickly deploy a token generator locally. After successful deployment, you can use the generated tokens to test and debug your project. @@ -839,7 +878,7 @@ Refer to the following steps to build and run a token generator locally to gener 1. Run the following command to install dependencies. ```go - $ go get + $ go get github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/rtctokenbuilder2 ``` 1. Run the following command to start the token generator: @@ -875,6 +914,8 @@ This section documents the core methods you use to generate tokens, using the Go - `BuildTokenWithUidAndPrivilege`: Generate a token with fine control over streaming permissions. Set the validity period of the token and the expiration time of permissions to join channels, publish audio, video, and data streams. +#### `BuildTokenWithUid` + To generate a token and set the expiration time for all permissions, use: ```go @@ -902,6 +943,8 @@ func BuildTokenWithUid( If the token expires but the permissions have not expired, the user remains in the channel and can continue to send streams. Any callbacks related to the token in the SDK are not triggered. Once disconnected from the channel, the user is not able to use the expired token to join the same channel. Best practice is to use consistent settings for the token expiration time and the permission expiration time. +#### `BuildTokenWithUidAndPrivilege` + To generate a token and set expiration time for different permissions, use: ```go diff --git a/shared/video-sdk/authentication-workflow/project-implementation/web.mdx b/shared/video-sdk/authentication-workflow/project-implementation/web.mdx index 4e2e3e51d..ee933beed 100644 --- a/shared/video-sdk/authentication-workflow/project-implementation/web.mdx +++ b/shared/video-sdk/authentication-workflow/project-implementation/web.mdx @@ -139,6 +139,8 @@ This section shows you how to integrate token authentication in your performs t * Obtains a token from your token server. * Joins the channel. -* Automatically renews the token when it is about to expire. +* Automatically renews the token when it is about to expire. \ No newline at end of file