Secure authentication with tokens
Updated
Introduces how to retrieve tokens from your app server to authenticate your users.
Agora uses digital tokens to authenticate users and their privileges before they access Agora Chat. For test purposes, you can generate temporary tokens in Agora Console. See Manage users and generate tokens for details.
In a development environment, you deploy your own app server to generate authentication tokens. This page introduces how to set up a token server, retrieve tokens from your server, and authenticate your users.
Understand the tech
Agora Chat employs two types of tokens for authentication:
-
Use tokens with app privileges to call Agora RESTful APIs.
-
Use tokens with user privileges for user authentication and interaction through the Agora Chat SDK.
| Use-case | Token type | Information required to generate | Maximum validity |
|---|---|---|---|
| RESTful API calls | Token with app privileges | App ID of your Agora Chat projectApp certificate of your Agora Chat projectToken validity period for your Agora Chat project | 24 hours |
| SDK API calls | Token with user privileges | App ID of your Agora Chat projectApp certificate of your Agora Chat projectToken validity period for your Agora Chat projectThe Agora Chat user ID | 24 hours |
Prerequisites
In order to follow this procedure, you must have the following:
- A valid Agora account.
- An Agora project with the App Certificate and Agora Chat enabled.
- App ID, OrgName, and AppName of your Agora project. See Enable and Configure Agora Chat Service.
If you have a firewall implemented in your network environment, Agora provides a firewall whitelist solution for you to access Agora Chat in environments with restricted network access. If you want to use the firewall whitelist solution, submit a ticket and our technical support will provide the target domain and corresponding IP.
Implement the authentication flow
This section shows you how to supply and consume a token used to authenticate a user with Agora Chat.
Deploy an app server to generate tokens
Tokens used for connecting with Agora Chat are generated by your app server. When a client sends a request, the app server generates an appropriate token. The following figure shows how to manage tokens with app and user privileges to facilitate secure user authentication and interaction with Agora Chat services.
Token generation API call sequence
This section guides you through setting up a token server. Choose your preferred language and follow the step-by-step procedure.
This sample server code provided in this guide is for demonstration purposes only. Do not use it directly in a production environment.
Chat SDK token authentication
The following code fetches and replaces an expired token for the Agora Chat SDK. It performs the following tasks:
-
Fetches a fresh token on app startup* At the start of the application, it fetches a valid token for the user from a token server.
-
Listens for
tokenDidExpireevent: The app sets up a listener to monitor when the token is about to expire. Upon receiving this event, it fetches a new token from the token server and renews the token with the Agora Chat SDK. Since SDK v1.4.0, the SDK triggers this event when 80% of the token's validity period has elapsed (previously 50%).
To execute the code, ensure you set the following values in the code:
- App Key: The app key of your Agora project.
- User ID: The username that you will be used communication.
- Token Server URL: The URL of your token server, which provides valid tokens for authentication.
Chat RESTful API token authentication
To create a new user, use the following curl command:
curl -X POST -H "Authorization: Bearer " -i "https://XXXX/app-id/XXXX/users" -d '[
{
"username": "user1",
"password": "123",
"nickname": "testuser"
}
]'The server responds with the user details:
{
"action": "post",
"application": "8be024f0-e978-11e8-b697-5d598d5f8402",
"path": "/users",
"entities": [
{
"uuid": "0ffe2d80-ed76-11e8-8d66-279e3e1c214b",
"username": "user1",
"activated": true,
"nickname": "testuser"
}
]
}Reference
This section introduces token generator libraries, version requirements, and related documents about tokens.
Token generator libraries
For more examples and source code in other development languages, explore the AgoraDynamicKey open-source repository on GitHub.
Tokens for Agora RTC products
If you use Agora Chat together with the Agora RTC SDK, Agora recommends upgrading to AccessToken 2.