Skip to main content

  • Core Products

  • Add-Ons

  • Extensions Marketplace

Secure authentication with tokens

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 doe.

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.

Understand the tech​

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 SignalingEngine, 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:

token authentication flow

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.

Prerequisites​

To follow this page, you must have:

  • Implemented the SDK quickstart
  • 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.

Implement the authentication workflow​

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:

  1. Create and run a token server
  2. Retrieve and use tokens from a token server

Create and run a token server​

This section shows you how to deploy a token server on a cloud platform.

  1. Start deploying the token server to your cloud platform: The cloud platform retrieves the project code and necessary files from Github, then takes you to the Deployment page.

  2. Fill in the information needed by your cloud platform:

    1. Blueprint name: A unique name for your deployment.

    2. Branch name: The branch of the repo or fork you want to deploy, default is main.

    3. APP_CERTIFICATE: The App Certificate obtained from Agora Console.

    4. APP_ID: The App ID obtained from Agora Console.

    5. Github account: The GitHub account where the cloud platform should clone the token server repository.

    6. Repository name: The name of the cloned repository, the default is agora-token-service.

    7. Private repository: Select this option to hide this repository.

  3. Click Deploy. The platform configures and builds the token server.

  4. 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 found in your browser. Follow the next steps and test your server.

  5. 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:


    _1
    /rtc/:channelName/:role/:tokentype/:uid/?expiry=expireTime

    For example: https://agora-token-service-production-1234.up.railway.app/rtc/MyChannel/1/uid/1/?expiry=300

    Your token server returns a JSON object containing an encrypted token:


    _1
    {"rtcToken":"ThisIsAnExampleTokenThisIsAnExampleTokenThisIsAnExampleTokenThisIsAnExampleTokenThisIsAnExampleToken"}

Authenticate your Signaling session​

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 SignalingEngine, ensure that the UID is the same one you used to create the token.

Test authentication​

To test authentication using a token server:

Reference​

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:

Signaling