Upgrade from AccessToken to AccessToken2
This section introduces how to use AccessToken to authenticate your users and how to upgrade from AccessToken to AccessToken2.
Authenticate your users with AccessToken
Understand the tech
The following figure shows the steps in the authentication flow:
A token is a dynamic key generated on your app server that is valid for a maximum of 24 hours. When your users connect to an Agora channel from your app client, Agora Platform validates the token and reads the user and project information stored in the token. A token contains the following information:
- The App ID of your Agora project
- The channel name
- The user ID of the user to be authenticated
- The privilege of the user, either as a publisher or a subscriber
- The time after which the token expires
Prerequisites
In order to follow this procedure you must have the following:
- A valid Agora account.
- An Agora project with the App Certificate enabled.
- Golang 1.14+ with GO111MODULE set to on.
If you are using Go 1.16+, GO111MODULE is on by default. See this blog for details.
- npm and a supported browser.
Implement the authentication flow
This section shows you how to supply and consume a token that gives rights to specific functionality to authenticated users using the source code provided by Agora.
Get the App ID and App Certificate
This section shows you how to get the security information needed to generate a token, including the App ID and App Certificate of your project.
1. Get the App ID
Agora automatically assigns each project an App ID as a unique identifier.
To copy this App ID, find your project on the Project Management page in Agora Console, and click the copy icon in the App ID column.
2. Get the App Certificate
To get an App Certificate, do the following:
- On the Project Management page, click Config for the project you want to use.
- Click the copy icon under Primary Certificate.
Deploy a token server
Token generators create the tokens requested by your client app to enable secure access to Agora Platform. To serve these tokens you deploy a generator in your security infrastructure.
In order to show the authentication workflow, this section shows how to build and run a token server written in Golang on your local machine.
-
Create a file,
server.go
, with the following content. Then replace<Your App ID>
and<Your App Certificate>
with your App ID and App Certificate. -
A
go.mod
file defines this module’s import path and dependency requirements. To create thego.mod
for your token server, run the following command: -
Get dependencies by running the following command:
-
Start the server by running the following command:
Use tokens for user authentication
This section uses the Web client as an example to show how to use a token for client-side user authentication.
In order to show the authentication workflow, this section shows how to build and run a Web client on your local machine.
-
Create the project structure of the Web client with a folder including the following files.
index.html
: User interfaceclient.js
: App logic with Agora Video Calling Web SDK 4.x
-
In
index.html
, add the following code to include the app logic in the UI: -
Create the app logic by editing
client.js
with the following content. Then replace<Your App ID>
with your App ID. The App ID must match the one in the server. You also need to replace<Your Host URL and port>
with the host URL and port of the local Golang server you have just deployed, such as10.53.3.234:8082
.In the code example, you can see that token is related to the following code logic in the client:
- Call
join
to join the channel with token, uid, and channel name. The uid and channel name must be the same as the ones used to generate the token. - The
token-privilege-will-expire
callback occurs 30 seconds before a token expires. When thetoken-privilege-will-expire
callback is triggered,the client must fetch the token from the server and callrenewToken
to pass the new token to the SDK. - The
token-privilege-did-expire
callback occurs when a token expires. When thetoken-privilege-did-expire
callback is triggered, the client must fetch the token from the server and calljoin
to use the new token to join the channel.
- Call
-
Open
index.html
with a supported browser to perform the following actions:- Successfully joining a channel.
- Renewing a token every 10 seconds.
Reference
This section introduces token generator libraries, version requirements, and related documents about tokens.
Token generator libraries
Agora provides an open-source AgoraDynamicKey repository on GitHub, which enables you to generate tokens on your server with programming languages such as C++, Java, and Go.
Language | Algorithm | Core method | Sample code |
---|---|---|---|
C++ | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.cpp |
Go | HMAC-SHA256 | buildTokenWithUid | sample.go |
Java | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.java |
Node.js | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.js |
PHP | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.php |
Python | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.py |
Python3 | HMAC-SHA256 | buildTokenWithUid | RtcTokenBuilderSample.py |
API reference
This section introduces the parameters and descriptions for the method to generate a token. Take C++ as an example:
Parameter | Description |
---|---|
appId | The App ID of your Agora project. |
appCertificate | The App Certificate of your Agora project. |
channelName | The channel name. The string length must be less than 64 bytes. Supported character scopes are:
|
uid | The user ID of the user to be authenticated. A 32-bit unsigned integer with a value range from 1 to (2³² - 1). It must be unique. Set uid as 0, if you do not want to authenticate the user ID, that is, any uid from the app client can join the channel. |
role | The privilege of the user, either as a publisher or a subscriber. This parameter determines whether a user can publish streams in the channel.
|
privilegeExpiredTs | The Unix timestamp (s) when the token expires, represented by the sum of the current timestamp and the valid time of the token. For example, if you set privilegeExpiredTs as the current timestamp plus 600 seconds, the token expires in 10 minutes. A token is valid for 24 hours at most. If you set this parameter as 0 or a period longer than 24 hours, the token is still valid for 24 hours. |
Upgrade from AccessToken to AccessToken2
Update the token server
-
Replace the
rtctokenbuilder
import statement, and remove the"time"
import statement: -
Remove the timestamp generation statements. Add
tokenExpireTimeInSeconds
andprivilegeExpireTimeInSeconds
: -
Update the token builder function:
-
Remove unsupported roles:
Update the client
In the index.html
file, make the following changes:
Test the AccessToken2 server
To test the AccessToken2 server, open index.html
with a supported browser to perform the following actions:
- Successfully joining a channel.
- Renewing a token every 10 seconds.