Security Keys

There is a new release of the Developer Center! If you'd like to check it out, please click  here

Security Keys

Read This First

The information on this page is for the Agora Native SDK (except the Gaming SDK) versions v2.1.0 or later.

  • If you are using an Agora SDK version earlier than v2.1.0 and wish to migrate to the latest version, see Token Migration Guide. The permission key for the host-in user is replaced by a token.
  • For Agora Native SDK versions earlier than v2.1.0; for example, v2.0.2, see Security Keys .
  • For Agora Web SDK, see Security Keys.
  • For Agora Gaming SDK, see Security Keys.
  • For the Agora Signaling SDK, see Security Keys.

The following figures show the dynamic key and access token support for different Agora SDK versions.

For Agora SDKs earlier than v2.1.0:

../_images/key_compatibility_1.jpg

For Agora SDKs v2.1.0 or later:

../_images/key_compatibility_2.jpg

Note

Host-in in the figures is defined as changing the client role from an audience to a host by calling setClientRole(). Host-in is only available for customers who have enabled this function.

Introduction

The Agora SDK provides two different keys for authentication: App ID and Token. The following diagram shows the relationship between and applicable scenarios of these two keys:

../_images/key_relation_native.jpg

Where:

  • An App ID can be easily abtained and applies to scenarios of relatively low security requirements, such as the testing environment.
  • A Token adds the security and applies to scenarios of higher security requirements, such as the production environment.
  • An App Certificate is enabled for the sole purpose of generating a Token and cannot be used alone. Once the App Certificate is enabled, you can only use the Token for authentication.

App ID

After signing up at Dashboard, multiple projects can be created. Each project will be assigned a unique App ID. The App ID identifies your project and organization in the joinChannel method to access the Agora Global Network, and enable one-to-one or one-to-more communication or live-broadcast sessions using a unique channel name for your App ID.

The communication or live-broadcast session for an App ID is separate from sessions with different App IDs. Channel messages and billing and management services are linked to respective App IDs.

Anyone with your App ID can perform the same operations in their own client applications, and join sessions that belong to you and are billed to you. For added security, Agora recommends using the Token mechanism for large-scale production applications.

Note

To switch your App ID, you must first call the function destroy() to destroy the current instance.

Token

Generating and Using a Token

../_images/key_theory.jpg
  • Agora provides the token generation code
  • The customer’s server uses the token generation code to generate a token
  • Upon receiving the client SDK’s request for the token, the customer’s server passes the generated token to the client SDK through the messaging or signaling system.

Token Design

A voice call, video call, or live broadcast includes different user roles with different default rights. For example, in a live broadcast:

  • A host can publish and subscribe the voice and video streams, as well as invite an audience to co-host.
  • An audience can subscribe to the voice and video streams, as well as request to co-host.
  • An administrator can mute or ban users from a channel.

Role-privilege Model

Role Description Permissions
Attendee Participants in a voice call or video call
  • Join a channel.
  • Publish a voice stream. [1]
  • Publish a video stream. [1]
  • Publish a data stream. [1]
Publisher Users (hosts) who publish video or/and voice streams in a live broadcast.
  • Join a channel.
  • Publish a voice stream.
  • Publish a video stream.
  • Publish a data stream.
  • Publish a voice stream on the CDN. [2]
  • Publish a video stream on the CDN. [2]
  • Invite users to publish a voice stream. [3]
  • Invite users to publish a video stream. [3]
  • Invite users to publish a data stream. [3]
Subscriber Users (audience) who need to subscribe to the voice and video streams in a live broadcast.
  • Join a channel.
  • Request to publish a voice stream. [3]
  • Request to publish a video stream. [3]
  • Request to publish a data stream. [3]

Footnotes

[1](1, 2, 3) In the communication mode, Agora does not provide authentication for publishing a voice, video or data stream. If you need to enable this service, contact sales@agora.io.
[2](1, 2) In the live broadcast mode, Agora does not provide authentication for publishing a voice or video stream on the CDM. If you need to enable this service, contact sales@agora.io.
[3](1, 2, 3, 4, 5, 6) In the live broadcast mode, Agora has not associated this permission with the user role.

The design of a Token is based on the authentication of different user roles, each of which is associated with a set of permissions.

  • You must define the role and lifespan when creating a Token.
  • When you login with a Token, the SDK sends the Token to the Agora servers for authenticating the assigned privileges.
  • During a call or live broadcast, you can update the Token for the clients in the channel to modify their privileges.

Getting an App ID

Each Agora account can create multiple projects, and each project has a unique App ID.

  1. Sign up for an account at https://dashboard.agora.io/.

  2. Click Add New Project on the Projects page of the dashboard.

  3. Fill in the Project Name and click Submit.

    ../_images/create_project.png
  4. Find the App ID under the created project.

Using an App ID

Access the Agora services by the unique App ID:

  1. Enter the App ID in the start window to enable voice or video communication in the demo.
  2. Add the App ID to the code when developing the application.
  3. Set the appId parameter as the App ID when calling APIs.

Getting a Token

Each Agora account can create multiple projects, and each project has a unique App ID and App Certificate. You need to use both the App ID and App Certificate so as to generate a Token.

1. Get an App ID

See Getting an App ID.

2. Get an App Certificate

  1. Login to https://dashboard.agora.io.

  2. Click Add New Project on the Projects page of the dashboard.

  3. Fill in the Project Name and click Submit. Find the App ID under the created project.

    ../_images/create_project.png
  4. Enable the App Certificate for the project.

    • Click Edit on the top-right of the project.

    • Click Enable to the right of the App Certificate. Read About App Certificate before confirming the operation.

      ../_images/enable_app_cert.png
    • Click the ‘eye’ icon to view the App Certificate. You can re-click this icon to hide the App Certificate.

      ../_images/view_app_certificate.png

Note

  • An App Certificate is enabled for the sole purpose of generating a Token and cannot be used alone.
  • Contact support@agora.io to renew an App Certificate.
  • Keep the App Certificate on the server, never on any client machine.
  • It takes about an hour for the App Certificate to take effect after it is enabled.
  • Once the App Certificate is enabled for a project, a Token must be used. For example, before enabling the App Certificate, an App ID can be used to join a channel; but once an App Certificate is enabled, a Token must be used to join a channel.

3. Generate a Token

Generate a token with the simpleTokenBuilder method on the server, and use the sample code provided by Agora in the following programming languages: CPP, GO, Java, Node.js, Python, and PHP.

  1. Go to https://github.com/AgoraIO/AgoraDynamicKey and refer to the sample code to deploy your code on your server.
  2. Call the API to generate a token for the programming language used:

The following table describes the parameters used.

Name Description
App ID ID of the App that you registered on the Agora dashboard. See Getting an App ID.
App Certificate Certificate of the app that you registered on the Agora dashboard. See 2. Get an App Certificate.
channelName Name of the channel that the user wants to join.
uid ID of the user who wants to join a channel.
role

Role of the user who wants to join a channel. Choose one of the following roles:

  • Attendee: User in the communication mode.
  • Publisher: Broadcaster in the live-broadcast mode.
  • Subscriber: Audience in the live-broadcast mode.
privilege Privileges to services corresponding to the specified roles. See Role-privilege Model.
expireTimestamp [4] The privilege expiration time. The default value is 0 in which the privilege never expires. A user can join a channel indefinitely within the designated expiration time and will be removed from the channel after the expiration time.

Footnotes

[4]expireTimestamp is represented by the number of seconds elapsed since 1/1/1970. If, for example, you want to access the Agora Service within 10 minutes after the privilege is granted, set it as the current timestamp + 600 (seconds). The valid time for each privilege is independent, in which you can set through the setPrivilege method.

Note

If you have implemented Agora’s algorithm in other languages, you can

file a pull request at https://github.com/AgoraIO/AgoraDynamicKey. Agora will merge any valid implementations and test cases.

Using the Token

Before a user joins a channel (starts a call or receives an invitation), the following sequence occurs:

  1. The client application requests authentication from your organization’s business server.
  2. The server, upon receiving the request, uses the algorithm provided by Agora to generate a Token, and then passes the Token back to the client application.
  3. The client application calls the specific API to join a channel, which requires the Token as the first parameter.
  4. The Agora server receives the Token and confirms that the call comes from a legitimate user, and then allows the user to access the Agora SD-RTN™ (Software Defined Real-time Network).

Note

  • For security reasons, you are required to join a channel within 24 hours after the token is generated; otherwise, you will have to regenerate the token.
  • When you deploy the token, it replaces the original App ID when someone joins a channel.
  • The token expires after a certain period of time. Your application must call renewToken() if it receives the tokenPrivilegeWillExpire callback or a timeout occurs. The onError or didOccurError callback returns ERR_TOKEN_EXPIRED (109).
  • The token encoding uses the industry-standard HMAC/SHA1 approach and the libraries are available on most server-side development platforms, such as Node.js, PHP, Python, and Ruby. For more information, see: http://en.wikipedia.org/wiki/Hash-based_message_authentication_code.
Is this page helpful?