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 Agora SD-RTN™ to join a channel. Each token is valid for a limited period and works for specific and wildcard channel names. For example, you use a Agora* token to join AgoraChannel or AgoraAwesome. However, you cannot use it to join the AppTest channel.

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 a IoT SDK channel. 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 to join a specific channel or wildcard channels.

When users attempt to connect to an Agora channel, your app retrieves a 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. A token contains the following information:

• The App ID of your Agora project

• The App certificate of your Agora project

• The name of an individual channel, or a wildcard string for multiple channels

• The user ID of the user to be authenticated (optional)

• The privilege of the user, either as a publisher or a subscriber

• The Unix timestamp showing when the token will expire

The following figure shows the call flow you need to implement to create step-up-authentication with Agora IoT SDK:

To follow this procedure, 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:

  • Render
  • Railway
  • Heroku

  To integrate a token generator directly into your security infrastructure, see Token generators.

• Android Studio 4.1 or higher.
• Android SDK API Level 24 or higher.
• A mobile device that runs Android 4.1 or higher.

• An Agora account and project.

• A computer with Internet access.

  Ensure that no firewall is blocking your network communication.

To integrate token authentication into your app, do the following:

1. Open the project you created in the:
   • UI Kit quickstart
   • SDK quickstart

2. Log in to your cloud platform.

In the SDK quickstart project you implemented, the app uses an authentication token obtained manually from Agora Console 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. Authenticate using the SDK

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.

   • Render
   • Railway
   • Heroku

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-server-l2yj.onrender.com/rtc/MyChannel/1/uid/1/?expiry=300

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

   
   

   _1

   {"rtcToken":"ThisIsAnExampleTokenThisIsAnExampleTokenThisIsAnExampleTokenThisIsAnExampleTokenThisIsAnExampleToken"}

   
   

1. Specify the token server URL

   In the MainActivity class, declare the following variable to hold the token server URL.

   
   

   _3

   // The base URL to your token server.

   _3

   // For example, "https://agora-token-service-production-92ff.up.railway.app"

   _3

   private String serverUrl = "<Token Server URL>";

   
   

   Make sure you specify the token-server URL in exactly the same format as shown in the example.

2. Set the token URL for AgoraVideoViewer

   To set the token URL, you create an AgoraSettings object, set its TokenURL property and pass this object to the constructor when initializing AgoraVideoViewer. To do this, replace the code in the try {…​} block of the initializeAndJoinChannel() method with the following:

   
   

   _4

   AgoraSettings settings = new AgoraSettings();

   _4

   settings.setTokenURL(serverUrl);

   _4

   agView = new AgoraVideoViewer(this, new AgoraConnectionData(appId, null),

   _4

   AgoraVideoViewer.Style.FLOATING, settings, null);

   
   

3. Fetch a token from the server when you join a channel

   In the joinChannel() method, replace the agView.join call with the following:

   
   

   _1

   agView.join(channelName, true, Constants.CLIENT_ROLE_BROADCASTER, 0);

   
   

To retrieve tokens from the token server and use them to authenticate your app with Agora SD-RTN™ using IoT SDK:

1. Add the necessary dependencies

   In order to make HTTPS calls to a token server and interpret the JSON return parameters, integrate the OkHttp client and Gson library into your Android project. In /Gradle Scripts/build.gradle (Module: <projectname>.app), add the following lines under dependencies.

   
   

   _7

   dependencies

   _7

   {

   _7

   ...

   _7

   implementation 'com.squareup.okhttp3:okhttp:4.9.3'

   _7

   implementation 'com.google.code.gson:gson:2.9.0'

   _7

   ...

   _7

   }

   
   

2. Allow cleartext network traffic

   Add the following line in /app/Manifests/AndroidManifest.xml, under <application:

   
   

   _1

   android:usesCleartextTraffic = "true"

   
   

3. Enable the user to specify a channel name

   Add a text box to the user interface. In /app/res/layout/activity_main.xml add the following lines before </RelativeLayout>:

   
   

   _10

   <EditText

   _10

   android:id="@+id/editChannelName"

   _10

   android:layout_width="match_parent"

   _10

   android:layout_height="wrap_content"

   _10

   android:layout_below="@id/JoinButton"

   _10

   android:layout_alignStart="@id/JoinButton"

   _10

   android:layout_alignEnd="@id/LeaveButton"

   _10

   android:hint="Type the channel name here"

   _10

   android:inputType="text"

   _10

   android:text="" />

   
   

4. Add the required import statements

   In /app/java/com.example.<projectname>/MainActivity, add the following lines after the last import statement:

   
   

   _13

   import android.util.Log;

   _13

   import android.widget.EditText;

   _13

   _13

   import okhttp3.OkHttpClient;

   _13

   import okhttp3.Request;

   _13

   import okhttp3.Response;

   _13

   import okhttp3.Call;

   _13

   import okhttp3.Callback;

   _13

   _13

   import com.google.gson.Gson;

   _13

   _13

   import java.io.IOException;

   _13

   import java.util.Map;

   
   

5. Add variables for your connection to the token server

   Declare the variables you need to specify the user id, token role, token server URL and the token expire time. Add the following declarations to the MainActivity class:

   
   

   _4

   private int tokenRole; // The token role: Broadcaster or Audience

   _4

   private String serverUrl = "<Token Server URL>"; // The base URL to your token server, for example, "https://agora-token-service-production-xxxx.up.railway.app".

   _4

   private int tokenExpireTime = 40; // Time in seconds after which the token will expire.

   _4

   private EditText editChannelName; // To read the channel name from the UI.

   
   

   Make sure you specify the token server URL in exactly the same format as shown in the example.

6. Set up access to the channel name text box from code

   Add the following line to the onCreate method:

   
   

   _1

   editChannelName = (EditText) findViewById(R.id.editChannelName);

   
   

7. Retrieve a token from the server

   Use a GET request to retrieve an authentication token for a specific channel from the token server, then decode the return parameters.

   In the MainActivity class, add the following fetchToken method:

   
   

   _35

   private void fetchToken(int uid, String channelName, int tokenRole) {

   _35

   // Prepare the Url

   _35

   String URLString = serverUrl + "/rtc/" + channelName + "/" + tokenRole + "/"

   _35

   + "uid" + "/" + uid + "/?expiry=" + tokenExpireTime;

   _35

   _35

   OkHttpClient client = new OkHttpClient();

   _35

   _35

   // Instantiate the RequestQueue.

   _35

   Request request = new Request.Builder()

   _35

   .url(URLString)

   _35

   .header("Content-Type", "application/json; charset=UTF-8")

   _35

   .get()

   _35

   .build();

   _35

   Call call = client.newCall(request);

   _35

   call.enqueue(new Callback() {

   _35

   _35

   @Override

   _35

   public void onFailure(Call call, IOException e) {

   _35

   Log.e("IOException", e.toString());

   _35

   }

   _35

   _35

   @Override

   _35

   public void onResponse(Call call, Response response) throws IOException {

   _35

   if (response.isSuccessful()) {

   _35

   Log.i("Token Received", token);

   _35

   Gson gson = new Gson();

   _35

   String result = response.body().string();

   _35

   Map map = gson.fromJson(result, Map.class);

   _35

   String _token = map.get("rtcToken").toString();

   _35

   // Use the token to join a channel or to renew an expiring token

   _35

   setToken(_token);

   _35

   }

   _35

   }

   _35

   });

   _35

   }

   
   

8. Join a channel using the token

   Use the retrieved token to either join a channel or to renew an expiring token.

   In the MainActivity class, add the following setToken method:

9. Handle the event triggered by Agora SD-RTN™ when the token is about to expire

   A token expires after the expireTime specified in the call to the token server or expires after 24 hours, if the time is not specified. The onTokenPrivilegeWillExpire event receives a callback when the current token is about to expire so that a fresh token may be retrieved and used.

   In the MainActivity class, add the following method after private final IRtcEngineEventHandler mRtcEventHandler = new IRtcEngineEventHandler() {

   
   

   _7

   // Listen for the event that the token is about to expire

   _7

   @Override

   _7

   public void onTokenPrivilegeWillExpire(String token) {

   _7

   Log.i("i", "Token Will expire");

   _7

   fetchToken(uid, channelName, tokenRole);

   _7

   super.onTokenPrivilegeWillExpire(token);

   _7

   }

   
   

10. Update the joinChannel method to fetch a token

    In the MainActivity class, replace the joinChannel method with the following:

To ensure that you have implemented Agora token authentication workflow in your app:

1. Generate a token in Agora Console.

   Users communicate securely using channels in the same project. The App ID you use to generate this token must be the same one you supplied to the cloud platform.

2. In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

3. Set the variables in your app:

   1. Update appID in the declarations to the value from Agora Console.

   2. Set token to an empty string in the declarations.

   3. Set uid to a non-zero integer.

   4. Update serverUrl in the declarations to the base address of your token server, for example, https://agora-token-service-production-1234.up.railway.app.

   5. If you are developing with UI Kit: set channelName to the same Channel you specified in the web demo app.

4. Connect a physical Android device to your development device.

5. In Android Studio, click Run app. A moment later you see the project installed on your device.

   If this is the first time you run the project, grant microphone and camera access to your app.

6. If you are developing with IoT SDK, enter the same channel name in the UI text box that you used to connect to the Agora web demo.

7. Click Join to connect your Android app to the web demo app.

Your app magically connects to the same channel you used in web demo. You don’t need to hardcode a token in your app; each channel is secured with a specific token, and each token is refreshed automatically. That’s pretty cool!

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

The token server RESTful web service used in this page is written in Golang using the Gin framework. Want to use the code in your authentication service? Download the token server source code and binaries for various platforms from Github.

To see how to create a token generator inside your IAM system, see Integrate a token generator.

A token server GET request has the following structure:

_1

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

• :channelName is the name of the Agora channel, or a wildcard for multiple channels that the local user may join. For example, you use a Agora* token to join AgoraChannel or AgoraAwesome. However, you cannot use it to join the AppTestchannel.

  A channel name may contain numbers with both upper and lower case letters. The name length must be less than 64 characters. Wildcard channels work for tokens that start with 007 and later.

• :role is the user role

  Use publisher for publisher, subscriber for subscriber.

• :tokentype is the type of token

  Agora SD-RTN™ supports both integer user IDs and string user accounts for token generation. To ensure smooth communication, all the users in a channel must use the same type of ID, that is, either the integer uid, or a string userAccount. Best practice is to use the uid.

• :uid is the user ID

  User Id can be any 32-bit unsigned integer. It can be set to 0, if you do not need to authenticate the user based on the user ID.

• expireTime (optional) is the number of seconds after which the token will expire

  By default, a token expires after 24 hours unless a shorter life span is explicitly specified in the token request.

• renewToken
• onTokenPrivilegeWillExpire