# 如何使用连麦鉴权功能? (/zh-CN/reference/faq/integration/token_cohost) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 功能介绍 [#功能介绍] 连麦鉴权,主要用于控制频道内的用户是否有发布流的权限,需要开发者通过自己的业务服务端部署并生成 Token、声网服务器再对生成的 Token 校验实现。 该功能可以确保频道内的发流用户都经过授权,从而防止黑客通过利用业务漏洞或盗取 Token 进行直播间炸房等行为。 :::warning[注意] - 开通连麦鉴权功能涉及 app 逻辑修改。请确保在开通前阅读本文。 - 该功能仅适用于 `setChannelProfile` 中的 `profile` 为 `LIVE_BROADCASTING` 的场景。 ::: ## 实现方法 [#实现方法] ### 1. 修改 Token 参数设置 [#1-修改-token-参数设置] 本文以 C++ 的 API 为例,介绍生成 AccessToken2 的 `role` 参数变更方式。具体的参数解释也适用于其他语言。 ```cpp #include #include #include "../src/RtcTokenBuilder2.h" using namespace agora::tools; int main(int argc, char const *argv[]) { (void)argc; (void)argv; // 获取环境变量 AGORA_APP_ID 的值。请确保你将该变量设为你在声网控制台获取的 App ID const char *env_app_id = getenv("AGORA_APP_ID"); std::string app_id = env_app_id ? env_app_id : ""; // 获取环境变量 AGORA_APP_CERTIFICATE 的值。请确保你将该变量设为你在声网控制台获取的 App 证书 const char *env_app_certificate = getenv("AGORA_APP_CERTIFICATE"); std::string app_certificate = env_app_certificate ? env_app_certificate : ""; // 将 channelName 替换为需要加入的频道名 std::string channel_name = "channelName"; // 填入你实际的用户 ID uint32_t uid = 2882341273 // Token 的有效时间,单位秒 uint32_t token_expiration_in_seconds = 3600; // 所有的权限的有效时间,单位秒 uint32_t privilege_expiration_in_seconds = 3600; std::string result; std::cout << "App Id:" << app_id << std::endl; std::cout << "App Certificate:" << app_certificate << std::endl; if (app_id == "" || app_certificate == "") { std::cout << "Need to set environment variable AGORA_APP_ID and " "AGORA_APP_CERTIFICATE" << std::endl; return -1; } // 生成 Token result = RtcTokenBuilder2::BuildTokenWithUid( app_id, app_certificate, channel_name, uid, UserRole::kRolePublisher, token_expiration_in_seconds, privilege_expiration_in_seconds); std::cout << "Token With Int Uid:" << result << std::endl; return 0; } ``` | 参数 | 概述 | | --- | --- | | `role` | [token-cohost-html-0-1-1 details](#table-slot-token-cohost-html-0-1-1) | **token-cohost-html-0-1-1 details** 用户发流权限: - `kRolePublisher(1)`:(默认)用户有发流权限。 - `kRoleSubscriber(2)`: 用户没有发流权限。 ### 2. 修改 app 层实现逻辑 [#2-修改-app-层实现逻辑] 你可以参考如下步骤在业务层对连麦用户的发流权限进行校验(适用于连麦观众需要上麦的场景): 1. 加入频道前,客户端向业务服务器申请权限为 `kRoleSubscriber` 的 Token。业务服务器将生成的角色为 `kRoleSubscriber` 的 Token 回传给客户端。 2. 客户端在调用 `joinChannel` 方法时,传入以 `kRoleSubscriber` 权限生成的 Token。 3. 客户端由观众切换为主播前,向业务服务器申请角色为 `kRolePublisher` 的 Token。业务服务器将生成的权限为 `kRolePublisher` 的 Token 回传给客户端。 4. 客户端调用 `renewToken` 方法将新的 Token 同步给 声网服务器。 5. 客户端调用 `setClientRole` 将用户角色切换为主播。声网服务器会在调用 `setClientRole` 方法的同时校验用户权限,如果 Token 角色为 `kRolePublisher`,则客户端成功获得发布流的权限。 :::info[信息] - 如果客户端想要由主播切换回观众,同理,可以参考上述步骤 3-5,先申请角色为 `Audience` 的 Token,然后调用 `renewToken`,再调用 `setClientRole` 即可。 - 如果 Token 超过服务有效期,则需要生成新的 Token,并调用 `renewToken` 将新的 Token 传给 SDK。新生成的 Token 同样有服务有效期。 ::: ### 3. 开启连麦鉴权 [#3-开启连麦鉴权] 请参考以下步骤在声网控制台开启连麦鉴权服务: 1. 登录[声网控制台](https://console.shengwang.cn/),在页面左上方选择需要开通连麦鉴权的项目。 2. 在**全部产品**下选择**实时互动 RTC**,然后选择**功能配置**。 3. 点击**连麦鉴权**,然后将状态设为**启用**,如下图所示: ![示意图](https://web-cdn.agora.io/docs-portal/img/rtc/cohost.png) 在控制台启用连麦鉴权后,该服务会在约 5 分钟后生效。 项目一旦开启了连麦鉴权服务,则用户在频道中发流需要同时满足两个条件: - 在 `setClientRole` 中设置的 `role` 参数为 `BROADCASTER`。 - 在生成 Token 的代码中设置的 `role` 参数为 `kRolePublisher`。 ## 升级注意事项 [#升级注意事项] **1. 假设用户角色为主播。升级到连麦鉴权后,会发生不能说话的情况吗?** 回答:不会。但是当用户当前 Token 过期后,需要重新在服务端申请权限为 `kRolePublisher` 的 Token,然后调用 `renewToken` 将新的 Token 同步给 SDK。 **2. 假设用户角色为观众。升级到连麦鉴权后,如果该用户想要上麦变成主播说话,有哪些注意事项?** 回答:app 开通连麦鉴权后,用户是否能上麦发言必须同时满足两个条件: - 申请 Token 时填入的 role 为 `kRolePublisher` - `setClientRole` 方法中设置的 role 为 `BROADCASTER` 因此如果观众用户想要上麦说话,需要参考上述修改 App 层实现逻辑的步骤,获取权限为 `kRolePublisher` 的 Token,并调用 `renewToken` 更新 Token,再调用 `setClientRole` 将用户角色设为主播。 ## 相关文档 [#相关文档] 为方便你对频道中的用户的发流权限进行更精细的控制,声网还提供一个同名的重载方法。支持你对用户分别设置加入频道、发布音频流、发布视频流及发布数据流的权限进行分别设置。 ```cpp static std::string buildTokenWithUid( const std:string& app_id, const std::string& app_certificate, const std::string& channel_name, uint32_t uid, uint32_t token_expire, uint32_t join_channel_privilege_expire = 0, unit32_t pub_audio_privilege_expire = 0, uint32_t pub_video_privilege_expire = 0, uint32_t pub_data_stream_privilege_expire = 0); ``` 该方法生成带角色权限的 RTC Token,支持对如下权限及其过期时间进行更精确的设置: - 加入 RTC 频道 - 在 RTC 频道中发布音频 - 在 RTC 频道中发布视频 - 在 RTC 频道中发布数据流 其中,发布音频、视频和数据流的权限仅在开通连麦鉴权服务后才生效。 一个用户可以设置多个权限。每个权限的最大有效时间为 24 小时。权限即将过期或已经过期后,SDK 会分别触发 `onTokenPriviegeWillExpire` 或 `onRequestToken` 回调。你需要在业务层区分即将过期或已经过期的是哪个权限,并根据业务需要及时生成新的 Token,然后调用 `renewToken` 将新的 Token 传给 SDK,或重新调用 `joinChannel` 加入频道。 :::info[信息] 你需要根据实际业务场景设置合理的过期时间戳。例如,如果加入频道的权限过期时间早于发布音频权限的过期时间,则在加入频道的权限过期后,用户就会被踢出 RTC 频道;即便发布音频的权限没有过期,对用户来讲这个权限是没有意义的。 ::: | 参数 | 描述 | | ---------------- | ---------------- | | `join_channel_privilege_expire` | **加入频道权限**的 Unix 过期时间戳,单位为秒。该值为当前时间戳和权限有效期的总和。比如,你将 `join_channel_privilege_expire` 设为当前时间戳再加 600 秒,那么加入频道的权限会在生成 10 分钟后过期。 | | `pub_audio_privilege_expire` | **发布音频权限**的 Unix 过期时间戳,单位为秒。该参数仅在开启连麦鉴权后生效。该值为当前时间戳和权限有效期的总和。比如,你将 `pub_audio_privilege_expire` 设为当前时间戳再加 600 秒,那么发布音频的权限会在生成 10 分钟后过期。如果希望该权限永久有效,则将该参数设为当前时间戳。| | `pub_video_privilege_expire` | **发布视频权限**的 Unix 过期时间戳,单位为秒。该参数仅在开启连麦鉴权后生效。该值为当前时间戳和权限有效期的总和。比如,你将 `pub_video_privilege_expire` 设为当前时间戳再加 600 秒,那么发布视频的权限会在 10 分钟后过期。如果希望该权限永久有效,则将该参数设为当前时间戳。| | `pub_data_stream_privilege_expire` | **发布数据流权限**的 Unix 过期时间戳,单位为秒。该参数仅在开启连麦鉴权后生效。该值为当前时间戳和权限有效期的总和。比如,你将 `pub_data_stream_privilege_expire` 设为当前时间戳再加 600 秒,那么发布数据流的权限会在 10 分钟后过期。如果希望该权限永久有效,则将该参数设为当前时间戳。 |