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.
- An Agora developer account (It’s free! Sign up here)
- An basic of how Express web servers function (minimal knowledge needed)
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.
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 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
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:
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
/rtc, passing in the
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:
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:
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” :
This will display:
Other examples produce a similar output:2
localhost:8080/rtc/test/publisher/uid/1 localhost:8080/rtc/test/publisher/uid/1?expiry=1000 localhost:8080/rtc/test/subscriber/userAccount/ekaansh
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”:
The response looks like:
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!
If you have any questions, I invite you to join the Agora Developer Slack community and ask them there.