Building a Token Server for Agora Applications Using Node.js

Note: This article was updated on 20-Dec-21 to use v2.0.0 of the Node.js token server.

Security in video chat applications is a hot topic at the moment. As remote working and virtual events become more widespread, the need for security will increase.

In the Agora platform, one layer of security comes in the form of token authentication. A token is a dynamic key that is generated using a set of given inputs. The Agora platform uses tokens to authenticate users.

Agora offers token security for its RTC and RTM SDKs. This guide will explain how to build a simple microservice using Node.js and Express to generate these tokens.

Prerequisites

• An Agora developer account (It’s free! Sign up here)
• A basic understanding of JavaScript ES6, Node.js, and NPM
• An basic of how Express web servers function (minimal knowledge needed)

Project Setup

To start our project, we’ll create a new folder and open a terminal window in this folder. In the terminal, we’ll run npm init to set up the node project. The create project prompt will appear. I used the default settings, but feel free to customize this portion.

Now that the project has been created, we can add our NPM dependencies (express, agora-access-token, and dotenv) using:

npm install express agora-access-token dotenv

Build the Express Server

Now that the project is set up, open the folder in your favorite code editor. Looking at the package.json, you’ll notice that the entry file is index.js. This file doesn’t exist in our project, so we’ll have to create a new file and name it index.js.

In the index.js we’ll start by requiring our modules. From Express, we’ll need the Express object, and from agora-access-token we’ll extract references to the RtcTokenBuilder and RtcRole objects. We’ll also use dotenv from its package for our environment variables:

Let’s define our constants by creating a .env file and adding our Agora credentials and the port we’re going to use to listen for requests:

Back in our index.js, we’ll access these values using environment variables. The dotenv package loads up environment variables from our .env file. We can specify a default port in case it’s not defined:

Next, we’ll define our app constant that will instantiate our Express object and allow us to set up our server:

Before we can set up the GET endpoint for our Express server, we’ll need to define the functions that are invoked when the endpoint is accessed. The first function (nocache) will apply the response headers, which force the browser to never cache the response, ensuring that we always get a fresh token. You’ll notice we call the next() method at the end because this function is a middleware function that is the first in the series, so we need to call next() to let Express know to continue to the next function in the series:

The second function (generateRTCToken) will handle the request and return the JSON response. We’ll define the function now and add the body once we finish setting up the Express server. This is the last function in the series, so we don’t need the next parameter/function:

Let’s define a GET endpoint /rtc, passing in the nochache and generateRTCToken functions:

You’ll notice the route contains :<path>. The colon (:) marks the path as a variable, and the user can pass in values like channel name, user role, type of token, and user UID to the route. We can access this data in our application.

As the last step in creating our Express server, we’ll implement the listen() method and pass in the port and a callback once the server is ready and listening on the given port:

Generate the Agora RTC Token

Now that we have our Express server set up, we are ready to add the functionality to the generateRTCToken function. We’ll start by setting the response header to ensure that we don’t run into any CORS issues:

Get the Request Parameters

Next, we’ll check for the channel in our request parameters. This is a required parameter, so if channelName is undefined, we need to return an error with a 500 response code and a JSON object with the error:

For uid and role we'll perform similar checks:

Note: The only privilege enforced by the Agora platform by default is the join channel privilege. To enable the enforcement of other privileges, you need to make a request through Agora Support.

The user can optionally pass in an expiry query parameter that will set the time for the token to expire. We can access the value and check whether it exists. Otherwise, we set a suitable default of 3600 seconds:

We’ll calculate the expiration time. It needs to be an integer that represents the time since Jan 1, 1970. We’ll use the current time and add our expiration time to it:

Build the Token

Now that we have all the elements for our token, we are ready to use the RtcTokenBuilder object to generate the token. We’ll check the tokenType and call the appropriate method on the object, passing in the required values:

Return the Response

The last step in generating our token is returning the JSON response that contains the token:

Test the Token Server

Let’s go back to our package.json and add a start command in the scripts object. The start command will execute the node index.js command so that we can run our server instance:

Start the server

Let’s go back to our Command Prompt window and use our new command: npm start

Once the server instance is listening, we’ll see “Listening on port: 8080” (or the port in your .env file) in our terminal window.

Test the endpoint

Now that our server instance is running, let’s open our web browser and test.

For example, pass “test” as the channel, “publisher” as the role, and “uid” as the tokenType with the UID of “1” :

localhost:8080/rtc/test/publisher/uid/1

This will display:

{"rtcToken":"0062ec0d84c41c4442d88ba6f5a2beb828bIAD9qg4N4hd04MvaY6A72m4BjYmO/7+xnRMinaI0ncLzkAx+f9gAAAAAEACS0zcn9gASXwEAAQCGvRBf"}

Other examples produce a similar output:

localhost:8080/rtc/test/publisher/uid/1
localhost:8080/rtc/test/publisher/uid/1?expiry=1000
localhost:8080/rtc/test/subscriber/userAccount/ekaansh

RTM Tokens

We can use the same process to configure a route to generate RTM tokens. You can look at the generateRTMToken function in the finished project for generating RTM tokens. The /rtm route looks like this, passing in a UID as “1”:

localhost:8080/rtm/1

The response looks like:

{"rtmToken":"0062ec0d84c41c4442d88ba6f5a2beb828bIAD9qg4N4hd04MvaY6A72m4BjYmO/7+xnRMinaI0ncLzkAx+f9gAAAAAEACS0zcn9gASXwEAAQCGvRBf"}

Conclusion

And just like that, we are done! In case you weren’t coding along or want to see the finished product all together, you can find it on GitHub. You can deploy it to Heroku in two clicks using the button in the Readme.

There’s also a version written in Typescript available on the typescript branch. If you see any room for improvement, feel free to fork the repo and make a pull request!

Other Resources

For more information about tokens for Agora applications, you can take a look at the Set up Authentication guide. We also have a token server built with Golang and Gin that you can find here.

If you have any questions, I invite you to join the Agora Developer Slack community and ask them there.