文档中心
互动直播
Agora.io 社区
如何使用连麦鉴权功能?
分类: 集成类    平台: Android / iOS / macOS / Web / Windows / Unity / Cocos Creator / Electron / React Native / Flutter   最后更新时间: 2021/07/05 01:16:25
  • 开通连麦鉴权功能涉及 app 逻辑修改。请确保在开通前阅读本文。
  • 该功能仅适用于 setChannelProfile 中的 profileLIVE_BROADCASTING 的场景。

功能介绍

连麦鉴权,主要用于控制频道内的用户是否有发布流的权限,需要开发者通过自己的业务服务端部署并生成 Token、Agora 服务器再对生成的 Token 校验实现。

该功能可以确保频道内的发流用户都经过授权,从而防止黑客通过利用业务漏洞或盗取 Token 进行直播间炸房等行为。

前提条件

开始前请确保你的 app 满足如下条件:

  • 使用 v2.1.0 及之后的 RTC SDK。
  • 所有客户端都只能使用 Token 鉴权。如果你想升级到使用 Token 鉴权,可以参考升级鉴权方案

实现方法

1. 修改 Token 参数设置

本文以 C++ 的 API 为例,介绍生成 Token 的 role 参数变更方式。具体的参数解释也适用于其他语言。

// API
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);


// 示例代码
int main(int argc, char const *argv[]) {

  // 请填入你的项目 App ID
  std::string appID  = "970Cxxxxxxxxxxxxxxxxxxxxxxx1b33";
  // 请填入你的项目 App 证书
  std::string  appCertificate = "5CFdxxxxxxxxxxxxxxxxxxxxxxx5d3b";
  // 请填入频道名
  std::string channelName= "7d72xxxxxxxxxxxxxxxxxxxxxxbdda";
  // 请填入 uid。如果填 0,则表示不对 uid 鉴权
  uint32_t uid = 2882341273;
  // Token 服务过期时间
  uint32_t expirationTimeInSeconds = 3600;
  uint32_t currentTimeStamp = time(NULL);
  uint32_t privilegeExpiredTs = currentTimeStamp + expirationTimeInSeconds;
  std::string result;

  result = RtcTokenBuilder::buildTokenWithUid(
      appID, appCertificate, channelName, uid, UserRole::Role_Publisher,
      privilegeExpiredTs);
  std::cout << "Token With Int Uid:" << result << std::endl;
参数 概述
role 用户发流权限:
  • Role_Publisher(1):(默认)用户有发流权限。
  • Role_Subriber(2): 用户没有发流权限。

2. 修改 app 层实现逻辑

你可以参考如下步骤在业务层对连麦用户的发流权限进行校验(适用于连麦观众需要上麦的场景):

  1. 加入频道前,客户端向业务服务器申请权限为 Subscriber 的 Token。业务服务器将生成的角色为 Subscriber 的 Token 回传给客户端。
  2. 客户端在调用 joinChannel 方法时,传入以 Subscriber 权限生成的 Token。
  3. 客户端由观众切换为主播前,向业务服务器申请角色为 Publisher 的 Token。业务服务器将生成的权限为 Publisher 的 Token 回传给客户端。
  4. 客户端调用 renewToken 方法将新的 Token 同步给 Agora 服务器。
  5. 客户端调用 setClientRole 将用户角色切换为主播。Agora 服务器会在调用 setClientRole 方法的同时校验用户权限,如果 Token 角色为 Publisher,则客户端成功获得发布流的权限。
  • 如果客户端想要由主播切换回观众,同理,可以参考上述步骤 3-5,先申请角色为 Audience 的 Token,然后调用 renewToken,再调用 setClientRole 即可。
  • 如果 Token 超过服务有效期,则需要生成新的 Token,并调用 renewToken 将新的 Token 传给 SDK。新生成的 Token 同样有服务有效期。

3. 开启连麦鉴权

请参考以下步骤在 Agora 控制台开启连麦鉴权服务:

  1. 登录 Agora 控制台,在项目列表区域选择你想要开启的项目,点击编辑按钮,进入编辑项目页面。
  2. 在项目详情页,下滑到功能区域,点击激活连麦鉴权
  3. 按照屏幕提示,了解开通该功能的主要事项,勾选后点击 Enable

在控制台启用连麦鉴权后,该服务会在约 5 分钟后生效。

项目一旦开启了连麦鉴权服务,则用户在频道中发流需要同时满足两个条件:

  • setClientRole 中设置的 role 参数为 BROADCASTER
  • 在生成 Token 的代码中设置的 role 参数为 Publisher

升级注意事项

1. 假设用户角色为主播。升级到连麦鉴权后,会发生不能说话的情况吗?

回答:不会。但是当用户当前 Token 过期后,需要重新在服务端申请权限为 Publisher 的 Token,然后调用 renewToken 将新的 Token 同步给 SDK。

2. 假设用户角色为观众。升级到连麦鉴权后,如果该用户想要上麦变成主播说话,有哪些注意事项?

回答:app 开通连麦鉴权后,用户是否能上麦发言必须同时满足两个条件:

  • 申请 Token 时填入的 role 为 Publisher
  • setClientRole 方法中设置的 role 为 BROADCASTER

因此如果观众用户想要上麦说话,需要参考上述修改 App 层实现逻辑的步骤,获取权限为 Publisher 的 Token,并调用 renewToken 更新 Token,再调用 setClientRole 将用户角色设为主播。

相关文档

为方便你对频道中的用户的发流权限进行更精细的控制,Agora 还提供一个同名的重载方法。支持你对用户分别设置加入频道、发布音频流、发布视频流及发布数据流的权限进行分别设置。

static std::string buildTokenWithUid(
     const std:string& appId,
     const std::string& appCertificate,
     const std::string& channelName,
     uint32_t uid,
     uint32_t joinChannelPrivilegeExpiredTs = 0,
     unit32_t pubAudioPrivilegeExpiredTs = 0,
     uint32_t pubVideoPrivilegeExpiredTs = 0,
     uint32_t pubDataStreamPrivilegeExpiredTs = 0);

该方法生成带角色权限的 RTC Token,支持对如下权限及其过期时间进行更精确的设置:

  • 加入 RTC 频道
  • 在 RTC 频道中发布音频
  • 在 RTC 频道中发布视频
  • 在 RTC 频道中发布数据流

其中,发布音频、视频和数据流的权限仅在开通连麦鉴权服务后才生效。

一个用户可以设置多个权限。每个权限的最大有效时间为 24 小时。权限即将过期或已经过期后,SDK 会分别触发 onTokenPriviegeWillExpireonRequestToken 回调。你需要在业务层区分即将过期或已经过期的是哪个权限,并根据业务需要及时生成新的 Token,然后调用 renewToken 将新的 Token 传给 SDK,或重新调用 joinChannel 加入频道。

你需要根据实际业务场景设置合理的过期时间戳。例如,如果加入频道的权限过期时间早于发布音频权限的过期时间,则在加入频道的权限过期后,用户就会被踢出 RTC 频道;即便发布音频的权限没有过期,对用户来讲这个权限是没有意义的。
参数 描述
joinChannelPrivilegeExpiredTs 加入频道权限的 Unix 过期时间戳,单位为秒。该值为当前时间戳和权限有效期的总和。比如,你将 joinChannelPrivilegeExpiredTs 设为当前时间戳再加 600 秒,那么加入频道的权限会在生成 10 分钟后过期。
pubAudioPrivilegeExpiredTs 发布音频权限的 Unix 过期时间戳,单位为秒。该参数仅在开启连麦鉴权后生效。该值为当前时间戳和权限有效期的总和。比如,你将 pubAudioPrivilegeExpiredTs 设为当前时间戳再加 600 秒,那么发布音频的权限会在生成 10 分钟后过期。如果不希望设置该权限,则将该参数设为当前时间戳。
pubVideoPrivilegeExpiredTs 发布视频权限的 Unix 过期时间戳,单位为秒。该参数仅在开启连麦鉴权后生效。该值为当前时间戳和权限有效期的总和。比如,你将 pubVideoPrivilegeExpiredTs 设为当前时间戳再加 600 秒,那么发布视频的权限会在 10 分钟后过期。如果不希望设置该权限,则将该参数设为当前时间戳。
pubDataStreamPrivilegeExpiredTs 发布数据流权限的 Unix 过期时间戳,单位为秒。该参数仅在开启连麦鉴权后生效。该值为当前时间戳和权限有效期的总和。比如,你将 pubDataStreamPrivilegeExpiredTs 设为当前时间戳再加 600 秒,那么发布数据流的权限会在 10 分钟后过期。如果不希望设置该权限,则将该参数设为当前时间戳。