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

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:

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:
- Render
- Railway
- Heroku

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:

Create and run a token server
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.

To start deploying the token server to your cloud platform, choose one of the following links:
- Render
- Railway
- Heroku
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:
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.
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 found in 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:
_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 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:

Retrieve an RTM token from the server

Use a GET request to retrieve an RTM authentication token for initializing the Signaling engine.

private fun fetchRTMToken(uid: Int, callback: TokenCallback) {
    // Prepare the Url
    val urlString = "$serverUrl/rtm/$uid/?expiry=$tokenExpiryTime"
    fetchToken(urlString, callback)
}
private fun fetchToken(urlString: String, callback: TokenCallback) {
    // Prepare the Url
    val client = OkHttpClient()
    // Create a request
    val request: Request = Builder()
        .url(urlString)
        .header("Content-Type", "application/json; charset=UTF-8")
        .get()
        .build()
    // Send the async http request
    val call = client.newCall(request)
    call.enqueue(object : Callback {
        // Receive the response in a callback
        @Throws(IOException::class)
        override fun onResponse(call: Call, response: Response) {
            if (response.isSuccessful) {
                try {
                    // Extract token from the response
                    val responseBody = response.body!!.string()
                    val jsonObject = JSONObject(responseBody)
                    val token = if (urlString.contains("/rtm/")) {
                        // Message channel token
                        jsonObject.getString("rtmToken")
                    } else {
                        // Stream channel token
                        jsonObject.getString("rtcToken")
                    }
                    // Return the token
                    callback.onTokenReceived(token)
                } catch (e: JSONException) {
                    e.printStackTrace()
                    callback.onError("Invalid token response")
                }
            } else {
                callback.onError("Token request failed")
            }
        }
        override fun onFailure(call: Call, e: IOException) {
            callback.onError("IOException: $e")
        }
    })
}

Call fetchToken to get a fresh RTM token. Use the token in the config to initiate the Signaling Engine.

fun loginWithToken(uid: Int): Int {
    return if (isValidURL(serverUrl)) { // A valid server url is available
        // Fetch a token from the server for the specified uid
        fetchRTMToken(uid, object : TokenCallback {
            override fun onTokenReceived(token: String?) {
                // Use the received token to log in
                if (token != null) login(uid, token)
            }
            override fun onError(errorMessage: String) {
                // Handle the error
                notify("Error fetching token: $errorMessage")
            }
        })
        0
    } else { // use the uid and token from the config.json file
        val defaultUid = config!!.optString("uid").toInt()
        val token = config!!.optString("token")
        login(defaultUid, token)
    }
}

Retrieve a Stream Channel token

To join a stream channel you retrieve an RTC token from the token server by specifying the uid and channelName.

fun fetchRTCToken(channelName: String, role: Int, callback: TokenCallback) {
    // Fetches the RTC token for stream channels
    val urlString = "$serverUrl/rtc/$channelName/$role/uid/$localUid/?expiry=$tokenExpiryTime"
    fetchToken(urlString, callback)
}

Use the Stream Channel token to join a stream channel

Create a stream channel using the channel name and call join with the RTC token.

fun joinStreamChannel(channelName: String): Int {
    fetchRTCToken(channelName, 1, object : TokenCallback {
        override fun onTokenReceived(token: String?) {
            // Use the received token to log in
            if (token != null) {
                streamChannel = signalingEngine!!.createStreamChannel(channelName)
                streamChannel.join(
                    JoinChannelOptions(token, true, true, true),
                    object : ResultCallback<Void?> {
                        override fun onFailure(errorInfo: ErrorInfo?) {
                            notify("Join stream channel failed:\n" + errorInfo.toString())
                            isStreamChannelJoined = false
                        }
                        override fun onSuccess(responseInfo: Void?) {
                            isStreamChannelJoined = true
                            mListener?.onSubscribeUnsubscribe(true)
                            notify("Joined stream channel: $channelName")
                        }
                    })
            }
        }
        override fun onError(errorMessage: String) {
            // Handle the error
            notify("Error fetching token: $errorMessage")
        }
    })
    return 0
}

join

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

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.

override fun onTokenPrivilegeWillExpire(token: String) {
    handleTokenExpiry()
    super.onTokenPrivilegeWillExpire(token)
}

Event Listeners

Renew the token

You persist the existing session by retrieving a fresh token and calling renewToken.

protected fun handleTokenExpiry() {
    notify("Token is about to expire")
    // Fetch a new token
    fetchToken(object : TokenCallback {
        override fun onTokenReceived(token: String?) {
            // Use the token to renew authentication
            signalingEngine!!.renewToken(token, object: ResultCallback<Void?> {
                override fun onFailure(errorInfo: ErrorInfo?) {
                    notify("Failed to renew token")
                }
                override fun onSuccess(responseInfo: Void?) {
                    notify("Token renewed")
                }
            })
        }
        override fun onError(errorMessage: String) {
            // Handle the error
            notify("Error fetching token: $errorMessage")
        }
    })
}

Test authentication

To test authentication using a token server:

Configure the project
1. Setup an Authentication server
2. Open the file <samples-root>/signaling-manager/src/main/res/raw/config.json
3. In config.json, set:
  - token to an empty string.
  - serverUrl to the base URL for your token server. For example: https://agora-token-service-production-yay.up.railway.app.
Run the reference app
1. In Android Studio, connect a physical Android device to your development machine.
2. Click Run to start the app.
3. A moment later you see the project installed on your device.
Test server authentication:

For each user you want to add to the conversation:
1. Launch an instance of the app.
2. Enter a numeric user ID, then press Login.
3. Enter a channel name, then press Subscribe to join a channel.
4. Send and receive messages between users.

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:

You are viewing Agora Docs forBeta products and features. Switch to Docs