简介

针对用户的项目开发需求,Agora SDK 提供了两种鉴权机制:App IDSignalingToken 。下图描述这两种鉴权机制的关系以及适用场景:

../_images/key_relation_signaling.jpg

其中:

  • App ID 易于获取,适用于对安全要求不高的场景

  • SignalingToken 安全性高,更适用于对安全要求较高的生产环境

  • App Certificate 仅用于生成 SignalingToken,不可单独使用。一旦启用了 App Certificate,则必须使用 SignalingToken

App ID

在 Agora 官网注册后,你就可以创建项目,每一个项目的唯一标识就叫做 App ID。 一旦有人非法获取了你的 App ID,他就可以在 Agora 提供的 SDK 中使用你的 App ID,因此 Agora 建议你仅在测试阶段或对安全性要求不高的场景里使用 App ID。

用户若需更换 App ID, 需要先调用 destroy() 方法销毁实例。

获取 App ID

每个 Agora 账户下可创建多个项目,且每个项目有独立的 App ID。

  1. 访问 https://dashboard.agora.io/,按照屏幕提示依次填入您的邮箱、密码等信息。

  2. 项目列表 页面点击 添加新项目 。按照屏幕提示填写您的手机号码,完成手机号验证。

  3. 填写您想要的 项目名, 然后点击 提交

  4. 在所创建的项目下查看 App ID。下图中红框标出的就是对应项目的App ID。获取 App ID 后即可使用对应的 Agora.io 服务功能。

使用 App ID

在调用 Agora SDK 的 API 接口实现功能时,如创建对象、加入频道,SDK 会需要你填入 App ID。将你获取到的 App ID 直接填入即可。

SignalingToken

获取 SignalingToken

  1. 获取 App ID。详见上文的获取 App ID

  2. 获取 App Certificate。在上文项目列表中查看 App ID 的地方,启用该项目的 App Certificate:

    1. 点击激活项目右上方的 编辑 按钮。

      ../_images/project_edit.png
    2. 点击 App Certificate 右方的 启用 按钮。仔细阅读关于 App Certificate 介绍后,根据屏幕提示,确认启用 App Certificate。

      ../_images/enable_app_cert.png
    3. 点击 App Certificate 后面的“眼睛”图标,显示完整的 App Certificate。如需隐藏 App Certificate,再次点击“眼睛”图标。

      ../_images/view_app_certificate.png
    • 如果出于某种原因你需要更新 App Certificate,请联系 support@agora.io
    • 将你的 App Certificate 保存在服务器端,且对任何客户端均不可见。
    • 通常 App Certificate 在启用一小时后生效。
    • 当项目的 App Certificate 被启用后,你必须使用 Token。例如: 在启用 App Certificate 前,你可以使用 App ID 加入频道。但启用了 App Certificate 后,你就必须使用 Token 加入频道。
    1. 如果你的项目同时集成了声网的信令 SDK,你可以调试 App Certificate 下方的信令Token调试开关

      ../_images/SignalingToken_debug.png
      • 如果 App Certificate 未启用,信令Token调试开关默认不生效,SignalingToken 支持任意值

      • 如果 App Certificate 已启用:

        • 信令Token调试开关默认随 App Certificate 一同启用:你可以正常设置 SignalingToken,也可以通过 _no_need_token 参数不使用 SignalingToken。

        • 如果关闭信令Token调试开关:你可以正常设置 SignalingToken,但是不能将 SignalingToken 设成 _no_need_token,否则将得到信令错误码 206.

建议客户业务上线后,关闭信令Token调试开关,禁用_no_need_token

  1. 集成算法。使用以下方法生成令牌 (SignalingToken):
    输入:

    appId             = "C5D15F8FD394285DA5227B533302A518" //App ID
    appCertificate    = "fe1a0437bf217bdd34cd65053fb0fe1d" //App Certificate
    expiredTime       = "1546271999" // 授权时间戳
    account           = "test@agora.io" //客户端定义的用户 ID

    下表中所有字段从前往后拼接:

    字段 描述
    SDK 版本 SignalingToken 版本号,固定为 1 的字符串
    App ID App ID, 长度为 32 的字符串
    授权时间戳 服务到期的 UTC 时间戳,用户在服务到期后,无法再登录 Agora 信令系统和使用其功能。长度为 10 的数字串。
    签名

    根据以下字段的输入,通过 MD5 算法和 hex 编码而成的 32 位字符串:

    • account: 用户登录厂商 Agora 信令系统的账户
    • appId: 32 位 App ID 字符串
    • appCertificate: 32 位 App Certificate 字符串
    • expiredTime: 服务到期的 UTC 时间戳,用户在服务到期后,无法再登录 Agora 信令系统和使用其功能

输出:

    token       = "1:appId:expiredTime:md5(account + appId + appCertificate + expiredTime)"
                = "1:C5D15F8FD394285DA5227B533302A518:1546271999:md5(test@agora.ioC5D15F8FD394285DA5227B533302A518fe1a0437bf217bdd34cd65053fb0fe1d1546271999)"
                = "1:C5D15F8FD394285DA5227B533302A518:1546271999:2d572d6e3a75ebde5a06626f40fe9684"

生成的 token 即为登录 Agora 信令系统所需的 SignalingToken,详见使用 SignalingToken

Agora 已在 GitHub 上提供了生成 SignalingToken 的示例代码:

使用 SignalingToken

在用户请求登录 Agora 信令系统时:

  1. 客户端向企业自己的服务器申请授权。

  2. 服务器端收到请求后,通过 Agora 提供的算法生成 SignalingToken,返回给授权的客户端应用程序。

  3. 客户端应用程序调用 login,参数 token 要求设为 SignalingToken。

  4. Agora 的服务器接收到 SignalingToken 信息,验证该通话是来自于合法用户,并允许访问 Agora 信令系统。