为保证通信安全,当用户加入 RTC 频道或服务端开始录制时,Agora 需要对其鉴权。Agora 提供如下鉴权方案,你可以根据自己的实际使用场景,选择合适的鉴权方式:

鉴权方案 详情 适用场景
App ID 频道内所有客户端均使用 App ID 鉴权 低安全需求场景,如测试环境
Token 频道内所有客户端均使用 Token 鉴权 高安全需求场景,如生产环境
App ID 或 Token 频道内有的客户端使用 App ID、有的客户端使用 Token 鉴权 由低安全向高安全需求过渡的场景
为提高项目的安全性,Agora 会逐步取消对 App ID 鉴权方案的支持,建议你将所有项目升级至使用 Token 鉴权。

使用 App ID 鉴权

开发者在 Agora 控制台注册账号后,可以创建多个项目,每一个项目的唯一标识就是 App ID。如果有人非法窃取了你的 App ID,他就可以在自己的项目中使用你的 App ID。因此,只使用 App ID 鉴权,安全性较低,我们推荐只在测试环境,或对安全要求不高的场景里使用 App ID 鉴权。

为提高项目的安全性,Agora 会逐步取消对 App ID 鉴权方案的支持,建议你将所有项目升级至使用 Token 鉴权。为保证不影响项目的运行,你可以同时使用 App ID 和 Token 鉴权进行灰度升级。

参考如下步骤,获取并使用 App ID:

  1. 进入控制台,按照屏幕提示注册账号并登录控制台。详见注册与登陆

  2. 点击左侧导航栏的 图标进入项目管理页面。

  3. 点击创建按钮。

  4. 在弹出的对话框内输入项目名称,选择 APP ID 为鉴权机制,并点击提交

  5. 项目创建成功后,你会在项目列表中看到刚刚创建的项目。点击 查看并复制该项目对应的 App ID。

  6. 在调用 Agora 的 API 接口实现功能,如 SDK 初始化时,Agora 会需要你填入 App ID。将你获取到的 App ID 直接填入即可。

  7. 如果你需要升级至 Token 鉴权方案,点击编辑进入编辑项目页面即可启用 App 证书。

    只有在创建项目时选择 APP ID 为鉴权机制,你才会看到无证书无证书表示使用 App ID 鉴权。

使用 Token 鉴权

Token 是一种动态密钥,通过 App ID、App 证书、用户名、频道名和 Token 有效时间戳等参数生成,安全性较高。在正式生产环境等对安全要求较高的场景中,我们推荐使用 Token 鉴权。

Token 适用范围

如下产品可以用 Token 进行鉴权:

产品 支持 Token 的版本 查看版本信息
语音或视频 SDK (Native) v2.1.0 及以上 getSdkVersion
语音或视频 SDK (Web) v2.4.0 及以上 AgoraRTC.VERSION
语音或视频 SDK (Electron) 所有版本 getVersion
语音或视频 SDK (Unity) 所有版本 GetSdkVersion
本地服务端录制 SDK v2.1.0 及以上 /
云端录制录制 所有版本 /
实时码流加速 SDK 所有版本 /
互动游戏 SDK v2.2.0 及以上 getVersion

如果你使用的产品版本低于上表中的版本,你可以升级版本或使用 Channel Key 鉴权。如果你从使用支持 Channel Key 的版本升级到使用 Token 的版本,请参考动态密钥升级指南

生成 Token

Token 需要在你的服务端生成。参考如下步骤,在 Agora 控制台获取 App ID、启用 App 证书,然后调用 API 生成 Token。

1. 获取 App ID

参考上文步骤获取 App ID

2. 启用 App 证书

App 证书是 Agora 控制台为开发项目生成的字符串。根据不同的安全需求,Agora 在项目中设置了两种 App 证书,区别如下:

  • 主要证书:用于生成临时 Token 和正式 Token。启用主要证书后,你不能直接删除主要证书。
  • 次要证书:只可用于生成正式 Token。启用次要证书后,你可以将次要证书与主要证书互换或删除次要证书。

如果你是第一次启用 App 证书,你需要先启用主要证书。

参考如下步骤启用主要证书:

  • 如果你在创建项目时,选择 APP ID + APP 证书 + Token 为鉴权机制,Agora 会默认为你启用主要证书。主要证书会显示在编辑项目页面,你可以点击 查看并复制主要证书。
  • 如果你在创建项目时,选择 APP ID 为鉴权机制,那么你需要手动启用主要证书。在编辑项目页面,找到主要证书,点击启用。成功启用后,你可以点击 查看并复制主要证书。

3. 生成 Token

  • 为方便在测试阶段中鉴权,Agora 控制台提供临时 Token。点击生成临时 Token 展开生成步骤:

    生成临时 Token
    • 生成临时 Token 前,请确保你已开启主要 App 证书。详见启用主要 App 证书
    • 临时 Token 适用于对安全要求一般的测试场景。对于正式生产环境,我们推荐使用正式 Token。
    • 临时 Token 不适用于 Agora RTM SDK。

    进入项目管理页面,在项目列表中,点击 按钮。

    进入 Token 页面,输入待加入的频道名,并点击生成临时 Token 即可。

  • 在正式生产环境中,Agora 建议你在服务端调用 buildTokenWithUid 生成正式 Token。详见生成 Token
  • Agora 支持使用 C++、Java、Python、PHP 等语言在你的服务端生成正式 Token。本节 API 注释以 C++ 示例代码为例。
  • Token 采用业界标准化的 HMAC/SHA1 加密方案,在 Node.js、Java、Python、C++ 等绝大多数通用的服务端开发平台上均可获得所需加密库。具体加密方案可参看 Authentication code

示例代码

    static std::string buildTokenWithUid(
        const std::string& appId,
        const std::string& appCertificate,
        const std::string& channelName,
        uint32_t uid,
        UserRole role,
        uint32_t privilegeExpiredTs = 0);
参数 描述
appId 你的项目 App ID。
appCertificate 你的项目 App 证书。
channelName 标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
  • uid 用户 ID,32 位无符号整型。
    role 用户角色。暂时只支持一种角色,请使用默认值 Role_Publisher = 1
    privilegeExpiredTs Token 有效时间戳,为自 1970 年 1 月 1 日零时起经过的秒数。比如,如果你将 privilegeExpiredTs 设为当前时间戳再加 600 秒,那么 Token 会在生成 10 分钟后过期。Token 的最大有效期为 24 小时。如果你设为 0,或超过 24 小时,则 Token 有效期依然是 24 小时。

    我们在 GitHub 上提供了一个开源的 Agora Dynamic Key 仓库,并覆盖了 C++、C#、Go、Java、Node.js、Perl、PHP、Python、Ruby 等语言。你可以根据实际开发环境,选择一种语言,查看 src 文件夹中的源代码或 sample 文件夹中的示例代码。

    4. 更换和删除 App 证书

    开启主要证书后,你还可以启用次要证书,次要证书可以用于生成正式 Token。如果主要证书存在安全风险,你可以将次要证书转换为主要证书并删除原来的主要证书,从而规避风险。

    参考如下步骤更换和删除 App 证书:

    1. 编辑项目页面,找到次要证书,点击启用。成功启用后,用户可以使用主要证书和次要证书生成的 Token 加入同一频道。
    2. 点击切换为主证书,次要证书就会和主要证书互换。切换后,使用原主要证书生成的临时 Token 会失效。
    3. 点击删除即可删除原主要证书。删除后,你无法恢复该证书,且使用该证书生成的 Token 会失效。你需要使用新的主要证书重新生成 Token 并鉴权。
    4. 删除后,次要证书的状态会变成未启用。下次启用时会生成新的次要证书。

    使用 Token

    你可以参考如下步骤使用 Token:

    1. app 客户端调用 Agora 的 API 接口实现功能,如加入频道时,需要填入生成的 Token、以及生成 Token 时使用的用户名、频道名等。
    2. Agora 服务端接收到填入的 Token 等信息后,会验证用户是否有权限访问频道。如果验证通过,用户可以加入频道并使用相应的 Agora 服务。
    3. Token 具有有效期。在 Token 失效后,你需要在 app 服务端重新生成 Token,并调用 renewToken

    同时使用 App ID 和 Token 鉴权

    为提高项目的安全性,Agora 会逐步取消对 App ID 鉴权方案的支持,建议你将所有项目升级至使用 Token 鉴权。

    如果你仅使用 App ID 鉴权,你可以参考如下步骤,同时使用 App ID 和 Token 鉴权,对 app 进行灰度升级:

    1. 启用主要 App 证书

    2. 成功启用主要 App 证书后,你可以使用主要证书生成 Token

    3. 同时使用 App ID 和 Token 鉴权。例如,当现存用户都使用 App ID 鉴权时,你可以对新用户使用 Token 鉴权,保障新老用户可以加入相同频道。再逐步将老用户的鉴权方案升级为使用 Token 鉴权。

    4. 在全量用户切换至 Token 鉴权后,Agora 建议你删除无证书。

      一旦无证书被删除,你无法使用 App ID 鉴权,且项目无法重新开启无证书。