使用 Token 鉴权

  • 小程序

更新时间

了解实时互动 RTC 在不同平台上的 Token 鉴权方式,包括接入流程、关键配置和平台差异。

鉴权是指在用户访问你的系统前,对用户权限进行校验,声网用 Token 对用户鉴权。Token 也称为动态密钥,是在加入频道时用于校验用户权限的一组字符串。当 App 用户使用声网服务,如加入 RTC 频道时传入 Token,声网服务端会根据 Token 中的信息校验用户的权限。

下图展示声网使用 Token 对用户鉴权的流程:

前提条件

开始前,请确保你的项目满足如下条件:

  • 已开启 App 证书的声网项目以及项目的 App ID,可参考开通 RTC 服务获取。

  • 已在你的项目中集成实时互动 SDK 并实现基本的实时互动功能,详见实现音视频互动。

实现加入频道鉴权

本节介绍如何使用 Token 对加入频道的用户鉴权。为确保你的业务的安全性,声网推荐你对每一个加入频道的客户端都进行鉴权。

生成 Token

声网在 GitHub 上提供一个开源的 Token 生成器代码仓库 AgoraDynamicKey,支持使用 C++、Java、Golang 等多种语言来在你自己的服务器上生成 Token。

以下列出的语言均基于 HMAC-SHA256 算法生成 Token。

以 C++ 为例,你可以通过 privilege_expiration_in_seconds 来统一设置所有权限的过期时间。

示例代码如下:

#include <cstdlib>
#include <iostream>

#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 = "uid";
    // Token 的有效时间,单位秒
    uint32_t token_expiration_in_seconds = 3600;
    // 所有的权限的有效时间,单位秒,声网建议你将该参数和 Token 的有效时间设为一致
    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;
}

信息

使用 Token

本节介绍如何使用 Token 对客户端加入频道的用户进行鉴权。

使用获取到的 Token 和用户 ID、频道名等信息,通过 join 方法加入频道。

注意

加入频道时使用的用户 ID 和频道名必须和生成 Token 时的用户 ID 和频道名一致。

JavaScript
// 频道名
const channel = 'xxx'
// 用户 ID
const uid = 1
// 请求服务端生成 channel 和 uid 对应的 token
const token = getToken()
// 是否为纯音频场景
const isAudioOnly = false
// 用户 ID 类型  0: int 1: string
const uidType = 0
// 加入频道
await client.join(
  token,
  channel,
  uid,
  isAudioOnly,
  uidType
);

Token 过期处理

使用 Token 加入频道后,在 Token 过期前 30 秒,SDK 会触发 token-privilege-will-expire 事件;Token 过期时,SDK 会触发 token-privilege-did-expire 事件。

当收到上述回调后,你需要重新在服务端生成新的 Token,然后调用 renewToken 更新 Token。

下列示例代码展示在收到 token-privilege-will-expire 事件提示 Token 即将过期时,调用 renewToken 来更新 Token。

JavaScript
client.on("token-privilege-will-expire", async () => {
  // 请求服务端生成 channel 和 uid 对应的新 token
  const token = getToken()
  // 重新鉴权
  await client.renewToken(token)
})

部署与调试

本节介绍如何在你的本地来快速部署一个 Token 生成器,部署成功之后你可以用生成的 Token 调试你的项目。

方式一:通过 Docker 部署 Token 生成器

参考以下步骤在本地部署一个基于 Docker 的 Token 生成器并申请 Token:

注意

在开始前,请确保你已安装 Docker。

方式二:本地手动部署 Token 生成器

以 Golang 语言为例,你可以参考如下步骤来在你本地搭建并运行一个 Token 生成器来生成 Token:

注意

在开始前,请确保你的 Golang 版本是 1.14 或以上版本。

你也可以直接前往声网控制台获取临时 Token 来调试你的项目,详见获取临时 Token。

参考信息

API 参考

以 Golang 语言为例,本节介绍生成 Token 的核心方法。

BuildTokenWithUid

生成 Token 并设置所有的权限过期时间。

Go
func BuildTokenWithUid(appId string, appCertificate string, channelName string, uid uint32, role Role, tokenExpire uint32, privilegeExpire uint32)

参数

  • appId:你在声网控制台创建项目时生成的 App ID。
  • appCertificate:你的项目的 App 证书。
  • channelName:频道名,长度在 64 个字节以内。
  • uid:待鉴权用户的用户 ID,32 位无符号整数,范围为 1 到 (2³² - 1), 并保证唯一性。
  • role:用户权限,决定用户是否能在频道中发流。
    • kRolePublisher(1):(默认)用户有发流权限,即用户可在频道中发流。
    • kRoleSubscriber(2):用户有接收权限,即用户可在频道中接收,但不可发流。该参数仅在开启连麦鉴权后才生效。详情参考开启连麦鉴权。
  • tokenExpire:Token 的有效时长(秒),最长有效期为 24 小时。
  • privilegeExpire:所有权限的有效时长(秒)。如设为 0(默认值),表示权限永不过期。

注意

当 Token 过期但权限未过期时,用户仍在频道里并且可以发流,不会触发 SDK 中与 Token 相关的任何回调。但一旦和频道断开连接,用户将无法使用该 Token 加入同一频道。声网建议将 Token 的过期时间和权限过期时间设为一致。

相关文档