使用 Token 鉴权

鉴权是指在用户访问你的系统前，对其进行身份校验。用户在使用 Agora 服务，如加入音视频通话或登录信令系统时，Agora 使用 Token 对其鉴权。

本文展示如何在服务端部署一个 Token 生成器，以及如何搭建一个使用 Token 鉴权的客户端。

鉴权原理

下图展示了鉴权的基本流程：

Token 在 app 服务器上生成，其最大有效期为 24 小时。当用户从你的 app 客户端连接至 Agora 频道时，Agora 平台会读取该 Token 中包含的信息，并进行校验。Token 包含以下信息：

• 你在 Agora 控制台创建项目时生成的 App ID
• 频道名
• 用户 ID
• 用户权限，如是否能发流或收流
• Token 过期的 Unix 时间戳

虽然 Token 最大有效期为 24 小时，为保证通信安全，Agora 建议按照你的业务场景需要设置较短的有效期，例如一小时。

前提条件

开始前，请确保你的项目或使用的 Agora 产品满足如下条件：

• 一个有效的 Agora 账户。

• 已开启 App 证书的 Agora 项目。

• Golang 1.14 或以上版本，GO111MODULE 设置为开启。

  如果你使用的是 Go 1.16 或以上版本，GO111MODULE 已默认开启。详情请参考 New module changes in Go 1.16。

• npm 以及支持的浏览器。

实现鉴权流程

本节介绍如何使用 Agora 提供的代码生成并提供 Token，对用户及其权限进行校验。

获取 App ID 及 App 证书

本节介绍如何获取生成 Token 所需的安全信息，如你的项目的 App ID 及 App 证书。

获取 App ID

Agora 会给每个项目自动分配一个 App ID 作为项目唯一标识。

在 Agora 控制台的项目管理页面，找到你的项目，点击 App ID 右侧的 图标，即可获取项目的 App ID。

获取 App 证书

参考以下步骤获取 App 证书：

1. 在 Agora 控制台的项目管理页面，找到你的项目，点击配置。
   

2. 点击主要证书下面的复制图标，即可获取项目的 App 证书。
   

部署 Token 服务器

Token 需要在你的服务端部署生成。当客户端发送请求时，服务端部署的 Token Generator 会生成相应的 Token，再发送给客户端。

本节展示如何使用 Golang 在你的本地设备上搭建并运行一个 Token 服务器。

1. 创建一个 server.go 文件，然后贴入如下代码。将其中的 <Your App ID>和 <Your App Certificate> 替换为你的 App ID 和 App 证书。

  package main

  import (
     rtctokenbuilder "github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/RtcTokenBuilder"
     "fmt"
     "log"
     "net/http"
     "time"
     "encoding/json"
     "errors"
     "strconv"
 )

  type rtc_int_token_struct struct{
     Uid_rtc_int uint32 `json:"uid"`
     Channel_name string `json:"ChannelName"`
     Role uint32 `json:"role"`
 }

  var rtc_token string
  var int_uid uint32
  var channel_name string

  var role_num uint32
  var role rtctokenbuilder.Role

 // 使用 RtcTokenBuilder 来生成 RTC Token
 func generateRtcToken(int_uid uint32, channelName string, role rtctokenbuilder.Role){

     // 填入项目 App ID
     appID := "<Your App ID>"
     // 填入 App 证书
     appCertificate := "<Your App Certificate>"
     // Token 过期的时间，单位为秒
     // 为作演示，在此将过期的时间戳设为 40 秒。当 Token 即将过期时，你可以看到客户端自动更新 Token 的过程
     expireTimeInSeconds := uint32(40)
     // 获取当前时间戳
     currentTimestamp := uint32(time.Now().UTC().Unix())
     // Token 过期的 Unix 时间戳
     expireTimestamp := currentTimestamp + expireTimeInSeconds

     result, err := rtctokenbuilder.BuildTokenWithUID(appID, appCertificate, channelName, int_uid, role, expireTimestamp)
     if err != nil {
         fmt.Println(err)
     } else {
         fmt.Printf("Token with uid: %s\n", result)
         fmt.Printf("uid is %d\n", int_uid )
         fmt.Printf("ChannelName is %s\n", channelName)
         fmt.Printf("Role is %d\n", role)
     }
     rtc_token = result
 }



 func rtcTokenHandler(w http.ResponseWriter, r *http.Request){
     w.Header().Set("Content-Type", "application/json; charset=UTF-8")
     w.Header().Set("Access-Control-Allow-Origin", "*")
     w.Header().Set("Access-Control-Allow-Methods", "POST, OPTIONS");
     w.Header().Set("Access-Control-Allow-Headers", "*");

     if r.Method == "OPTIONS" {
         w.WriteHeader(http.StatusOK)
         return
     }

     if r.Method != "POST" && r.Method != "OPTIONS" {
         http.Error(w, "Unsupported method.  Please check.", http.StatusNotFound)
         return
     }



     var t_int rtc_int_token_struct
     var unmarshalErr *json.UnmarshalTypeError
     int_decoder := json.NewDecoder(r.Body)
     int_err := int_decoder.Decode(&t_int)
     if (int_err == nil) {

                 int_uid = t_int.Uid_rtc_int
                 channel_name = t_int.Channel_name
                 role_num = t_int.Role
                 switch role_num {
                 case 0:
                    // 已废弃。RoleAttendee 和 RolePublisher 的权限相同。
                     role = rtctokenbuilder.RoleAttendee
                 case 1:
                     role = rtctokenbuilder.RolePublisher
                 case 2:
                     role = rtctokenbuilder.RoleSubscriber
                 case 101:
                     // 已废弃。RoleAdmin 和 RolePublisher 的权限相同。
                     role = rtctokenbuilder.RoleAdmin
                 }
     }
     if (int_err != nil) {

                  if errors.As(int_err, &unmarshalErr){
                 errorResponse(w, "Bad request.  Wrong type provided for field " + unmarshalErr.Value  + unmarshalErr.Field + unmarshalErr.Struct, http.StatusBadRequest)
                 } else {
                 errorResponse(w, "Bad request.", http.StatusBadRequest)
             }
         return
     }

     generateRtcToken(int_uid, channel_name, role)
     errorResponse(w, rtc_token, http.StatusOK)
     log.Println(w, r)
 }

  func errorResponse(w http.ResponseWriter, message string, httpStatusCode int){
     w.Header().Set("Content-Type", "application/json")
     w.Header().Set("Access-Control-Allow-Origin", "*")
     w.WriteHeader(httpStatusCode)
     resp := make(map[string]string)
     resp["token"] = message
     resp["code"] = strconv.Itoa(httpStatusCode)
     jsonResp, _ := json.Marshal(resp)
     w.Write(jsonResp)

  }

  func main(){
     // 使用 int 型 uid 生成 RTC Token
     http.HandleFunc("/fetch_rtc_token", rtcTokenHandler)
     fmt.Printf("Starting server at port 8082\n")

          if err := http.ListenAndServe(":8082", nil); err != nil {
         log.Fatal(err)
     }
      }

2. go.mod 文件定义导入路径及依赖项。运行如下命令行来为你的 Token 服务器创建 go.mod 文件：

   $ go mod init sampleServer

3. 运行如下命令行安装依赖。你可以使用 Go 镜像进行加速，例如 https://goproxy.cn/ 。

   $ go get

4. 运行如下命令行启动服务器：

   $ go run server.go

使用 Token 对用户鉴权

本节以 Web 客户端为例，展示如何使用 Token 对客户端的用户进行鉴权。

1. 创建一个项目文件夹，其中包含如下文件：

   • index.html：用户界面
   • client.js：使用 Agora RTC Web SDK 4.x 的 app 逻辑

     |
     |-- index.html
     |-- client.js

2. 在 index.html 中加入以下代码，创建用户界面：

   <html>
   <head>
      <title>Token demo</title>
   </head>
   <script src="https://unpkg.com/axios/dist/axios.min.js"></script>
   <body>
      <h1>Token demo</h1>
      <script src="https://download.agora.io/sdk/release/AgoraRTC_N.js"></script>
    <script src="./client.js"></script>
   
   </body>
   </html>

3. 将如下代码贴入 client.js 文件中，实现客户端鉴权逻辑。

   • 将 <Your App ID> 替换为你的 App ID。该 App ID 必须与 Token 生成代码中的 App ID 一致。

   • 将 <Your Host URL and port> 替换为你部署好的本地 Golang 服务器的主机 URL 和端口，如 10.53.3.234:8082 。

     var rtc = {
       // 设置本地音频轨道和视频轨道。
       localAudioTrack: null,
       localVideoTrack: null,
     };
     
     var options = {
       // 传入 App ID
       appId: "<Your app ID>",
       // 传入频道名
       channel: "ChannelA",
       // 设置用户为 host (可发流) 或 audience（仅可收流）
       role: "host"
     };
     
     // 从 Golang 服务器获取 Token
     function fetchToken(uid, channelName, tokenRole) {
     
       return new Promise(function (resolve) {
           axios.post('http://<Your Host URL and port>/fetch_rtc_token', {
               uid: uid,
               channelName: channelName,
               role: tokenRole
           }, {
               headers: {
                   'Content-Type': 'application/json; charset=UTF-8'
               }
           })
               .then(function (response) {
                   const token = response.data.token;
                   resolve(token);
               })
               .catch(function (error) {
                   console.log(error);
               });
       })
     }
     
     async function startBasicCall() {
     
       const client = AgoraRTC.createClient({ mode: "live", codec: "vp8" });
       client.setClientRole(options.role);
       const uid = 123456;
     
       // 将获取到的 Token 赋值给 join 方法中的 token 参数，然后加入频道
       let token = await fetchToken(uid, options.channel, 1);
     
       await client.join(options.appId, options.channel, token, uid);
       rtc.localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack();
       rtc.localVideoTrack = await AgoraRTC.createCameraVideoTrack();
       await client.publish([rtc.localAudioTrack, rtc.localVideoTrack]);
       const localPlayerContainer = document.createElement("div");
       localPlayerContainer.id = uid;
       localPlayerContainer.style.width = "640px";
       localPlayerContainer.style.height = "480px";
       document.body.append(localPlayerContainer);
     
       rtc.localVideoTrack.play(localPlayerContainer);
     
       console.log("publish success!");
     
       client.on("user-published", async (user, mediaType) => {
           await client.subscribe(user, mediaType);
           console.log("subscribe success");
     
           if (mediaType === "video") {
               const remoteVideoTrack = user.videoTrack;
               const remotePlayerContainer = document.createElement("div");
               remotePlayerContainer.textContent = "Remote user " + user.uid.toString();
               remotePlayerContainer.style.width = "640px";
               remotePlayerContainer.style.height = "480px";
               document.body.append(remotePlayerContainer);
               remoteVideoTrack.play(remotePlayerContainer);
     
           }
     
           if (mediaType === "audio") {
               const remoteAudioTrack = user.audioTrack;
               remoteAudioTrack.play();
           }
     
           client.on("user-unpublished", user => {
               const remotePlayerContainer = document.getElementById(user.uid);
               remotePlayerContainer.remove();
           });
     
       });
     
       // 收到 token-privilege-will-expire 回调时，从服务器重新申请一个 Token，并调用 renewToken 将新的 Token 传给 SDK
       client.on("token-privilege-will-expire", async function () {
           let token = await fetchToken(uid, options.channel, 1);
           await client.renewToken(token);
       });
     
       // 收到 token-privilege-did-expire 回调时，从服务器重新申请一个 Token，并调用 join 重新加入频道
       client.on("token-privilege-did-expire", async function () {
           console.log("Fetching the new Token")
           let token = await fetchToken(uid, options.channel, 1);
           console.log("Rejoining the channel with new Token")
           await client.join(options.appId, options.channel, token, uid);
       });
     
     }
     
     startBasicCall()

   在上述代码示例中，你可以看到 Token 与客户端的以下代码逻辑有关：

   • 调用 join 方法，使用 Token、用户 ID 和频道名加入频道。用户 ID 和频道名必须和用于生成 Token 的用户 ID 和频道名一致。
   • 在 Token 过期前 30 秒，SDK 会触发 token-privilege-will-expire 回调。收到该回调后，客户端需要从服务器获取新的 Token 并调用 renewToken 方法将新生成的 Token 传给 SDK。
   • Token 过期时，SDK 会触发 token-privilege-did-expire 回调。收到该回调后，客户端需要从服务器获取新的 Token 并调用 join 方法，再使用新的 Token 重新加入频道。

4. 用支持的浏览器打开 index.html 文件，可以看到客户端执行以下操作：

   • 成功加入频道。
   • 每隔 10 秒更新 Token。

参考

本节介绍 Token 生成器代码库、使用 Token 的版本要求等相关文档。

Token 生成器代码

Agora 在 GitHub 上提供一个开源的 AgoraDynamicKey 仓库，支持使用 C++、Java、Go 等语言在你自己的服务器上生成 Token。

语言	算法	核心方法	示例代码
C++	HMAC-SHA256	buildTokenWithUid	RtcTokenBuilderSample.cpp
Go	HMAC-SHA256	buildTokenWithUid	sample.go
Java	HMAC-SHA256	buildTokenWithUid	RtcTokenBuilderSample.java
Node.js	HMAC-SHA256	buildTokenWithUid	RtcTokenBuilderSample.js
PHP	HMAC-SHA256	buildTokenWithUid	RtcTokenBuilderSample.php
Python	HMAC-SHA256	buildTokenWithUid	RtcTokenBuilderSample.py
Python3	HMAC-SHA256	buildTokenWithUid	RtcTokenBuilderSample.py

API 参考

本节介绍生成 Token 的 API 参数和描述。 以 C++ 为例：

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	你在 Agora 控制台创建项目时生成的 App ID。
appCertificate	你的项目的 App 证书。
channelName	频道名称，长度在 64 个字节以内。以下为支持的字符集范围： 26 个小写英文字母 a-z； 26 个大写英文字母 A-Z； 10 个数字 0-9； 空格 标点符号和其他符号, 包括: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
uid	待鉴权用户的用户 ID 32 位无符号整数，范围为1到 (2³² - 1)， 并保证唯一性。 如不需对用户 ID 进行鉴权，即客户端使用任何 uid 都可加入频道，请把 uid 设为 0。
role	用户权限，分为发流用户和接收用户。参数决定用户是否能在频道中发流。 Role_Publisher(1)：（默认）用户有发流权限，即用户可在频道中发流。 Role_Subscriber(2)：用户有接收权限，即用户可在频道中接收，但不可发流。 该参数仅在开启连麦鉴权后才生效。详情参考如何使用连麦鉴权功能？
privilegeExpiredTs	Token 过期的 Unix 时间戳，单位为秒。该值为当前时间戳和 Token 有效期的总和。 例如，如果你将 privilegeExpiredTs 设为当前时间戳再加 600 秒，则 Token 会在 10 分钟内过期。 Token 的最大有效期为 24 小时。 如果你将此参数设为 0，或时间长度超过 24 小时，Token 有效期依然为 24 小时。

Channel Key

Token 鉴权对 SDK 版本的要求如下：

• RTC Native SDK 和本地服务端录制 SDK 的版本需为 v2.1.0 或以上。
• RTC Web SDK 的版本需为 v2.4.0 或以上。

如果你使用的是早期版本，参考 Channel Keys 来对你的用户进行鉴权。

相关文档

如需了解更多有关 Token 的信息，请参考如下文档：

• 如何处理 Token 相关错误码？
• 如何处理云端录制 101 错误码？
• 如何使用连麦鉴权功能？
• 如何升级到 Token 鉴权方案？