Authentication is the act of validating the identity of each user before they access a system. Agora
uses digital tokens to authenticate users and their privileges before they access Signaling. Each token is valid
for a limited period and works for a specific UID only. For example, you cannot use a token generated for UID
john for UID
This page shows you how to quickly set up an authentication token server, retrieve a token from the server, and use it to connect securely to Signaling as a specific user. You use this server for development purposes. To see how to develop your own token generator and integrate it into your production IAM system, read Token generators.
An authentication token is a dynamic key that is valid for a maximum of 24 hours. On request, a token server returns an authentication token that is valid for a specific user. A token server generates two types of tokens:
- To initialize the Signaling Engine, you use an RTM token. An RTM token is valid only for the user Id that you use to generate it.
- To join a stream channel, you use an RTC token. An RTC token is valid only for the channel name and the user Id that you use to generate it.
The following figure shows the call flow you need to implement to create step-up-authentication with Signaling:
To initiate the Signaling engine, your app retrieves an RTM token from the token server in your security infrastructure. Your app then sends this token to Agora SD-RTN™ for authentication. Agora SD-RTN™ validates the token and reads the user and project information stored in the token.
To join a stream channel you request an RTC token from the server by supplying a user Id and a channel name. You do not need an authentication token to subscribe to a message channel.
A token contains the following information:
The App ID of your Agora project
The App certificate of your Agora project
The User Id of the user to be authenticated
The Unix timestamp showing when the token will expire
The channel name (only for RTC tokens)
When the token is about to expire, Agora SD-RTN™ sends an event to your app and you renew the session with a new token.
To follow this page, you must have:
- Set up the Signaling SDK reference app.
- Created a cloud platform account that is verified through your GitHub account. The following platforms are currently supported:
To integrate a token generator directly into your security infrastructure, see Token generators.
In the SDK quickstart, the app uses an authentication token obtained manually to join a channel. In a production environment, your app retrieves this token from a token server. This section shows you how to:
This section shows you how to deploy a token server on a cloud platform.
To start deploying the token server to your cloud platform, choose one of the following links:
The cloud platform retrieves the project code and necessary files from Github, then takes you to the Deployment page.
Fill in the information needed by your cloud platform:
Blueprint name: A unique name for your deployment.
Branch name: The branch of the repo or fork you want to deploy, default is main.
APP_CERTIFICATE: The App Certificate obtained from Agora Console.
Github account: The GitHub account where the cloud platform should clone the token server repository.
Repository name: The name of the cloned repository, the default is
Private repository: Select this option to hide this repository.
Click Deploy. The platform configures and builds the token server.
Click the URL.
You are notified of a URL where your server is deployed. Click the link and open the token server in your browser. Don’t worry if you see
404 page not foundin your browser. Follow the next steps and test your server.
Test your server
To retrieve a token, send a request to the token server using a URL based on the Token server GET request structure:
Your token server returns a JSON object containing an encrypted token:
In Signaling, each authentication token you create is specific for a user ID in your app. You create a token for each user who logs in to Signaling. When you initiate the Signaling Engine, ensure that the UID is the same one you used to create the token.
In order to make HTTPS calls to a token server and interpret the JSON return parameters, the axios HTTP client is integrated into the reference .
To retrieve tokens from the token server and use them to authenticate your app with Signaling using Signaling SDK:
Use a GET request to retrieve an RTM authentication token for initializing the Signaling engine.
fetchToken to get a fresh RTM token. Use the token in the config to initiate the Signaling Engine.
To join a stream channel you retrieve an RTC token from the token server by specifying the
Create a stream channel using the channel name and call
join with the RTC token.
A token expires after the
tokenExpiryTime specified in the call to the token server. If the expiry time is not specified the default timeout is 24 hours. The
TokenPrivilegeWillExpire event receives a callback when the current token is about to expire so that a fresh token may be retrieved and used.
You persist the existing session by retrieving a fresh token and calling
To test authentication using a token server:
Configure the project
- Setup an Authentication server
Open the file
tokento an empty string.
serverUrlto the base URL for your token server. For example:
Run the reference app
- In Android Studio, connect a physical Android device to your development machine.
- Click Run to start the app.
- A moment later you see the project installed on your device.
Test server authentication:
For each user you want to add to the conversation:
- Launch an instance of the app.
- Enter a numeric user ID, then press Login.
- Enter a channel name, then press Subscribe to join a channel.
- Send and receive messages between users.
This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.
For more information, see: