本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护

文档中心





全部产品

Console 官网社区技术支持





使用 Token 鉴权

更新时间 2023/05/22 09:05:41

鉴权是指在用户访问你的系统前，对其进行身份校验。用户在使用声网服务，如加入教室时，声网使用 Token 对其鉴权。

为提供更好的鉴权体验和安全性保障，声网自 2022 年 8 月 18 日推出新版 Token：AccessToken2。我们推荐使用 AccessToken2，同时也兼容 AccessToken。

本文提供如何使用 AccessToken2 在服务端部署一个 Token 生成器，如何在客户端使用 Token 鉴权，以及相关的参考信息。

鉴权原理

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

声网 Token 在 app 服务器上生成，其最长有效期为 24 小时。当用户从你的 app 客户端登录到灵动课堂服务器时，声网平台会读取该 Token 中包含的信息，并进行校验。Token 包含以下信息：

你在声网控制台创建项目时生成的 App ID
灵动课堂用户 ID
Token 过期的 Unix 时间戳

前提条件

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

一个有效的声网账户。
已开启 App 证书的声网项目。
Golang 1.14 以上版本，GO111MODULE 设置为开启。
如果你使用的是 Go 1.16 及以上版本，GO111MODULE 已默认开启。详情请参考 New module changes in Go 1.16。
npm 以及支持的浏览器。

实现鉴权流程

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

获取 App ID 及 App 证书

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

1. 获取 App ID

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

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

2. 获取 App 证书

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

在声网控制台的项目管理页面，找到你的项目，点击配置。
点击主要证书下面的复制图标，即可获取项目的 App 证书。

为 AccessToken2 部署 Token 服务器

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

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

此示例服务器仅用于演示，请勿用于生产环境中。

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

 package main

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

 type education_token_struct struct {
     roomUuid string `json:"roomUuid"`
     userUuid string `json:"userUuid"`
     role int `json:"role"`
 }

 var educationToken string

 func generateEducationToken(roomUuid string, userUuid string, role int) {
     appID := "Your_App_ID"
     appCertificate := "Your_Certificate"
     expire := uint32(3600)

     result, err := educationtokenbuilder.BuildRoomUserToken(appID, appCertificate, roomUuid, userUuid, role, expire)

     if err != nil {
         fmt.Println(err)
     } else {
         fmt.Printf("EducationToken: %s\n", result)
         educationToken = result
     }
 }

 func educationTokenHandler(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_education_str education_token_struct
     var unmarshalErr *json.UnmarshalTypeError
     str_decoder := json.NewDecoder(r.Body)
     education_err := str_decoder.Decode(&t_education_str)

     if (education_err != nil) {
         if errors.As(education_err, &unmarshalErr) {
             errorResponse(w, "Bad request. Please check your params.", http.StatusBadRequest)
         } else {
             errorResponse(w, "Bad request.", http.StatusBadRequest)
         }
         return
     }

     generateRtmToken(t_education_str.roomUuid,t_education_str.userUuid,t_education_str.role)
     errorResponse(w, educationToken, 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() {
     // Handling routes
     http.HandleFunc("/fetch_education_token", educationTokenHandler)

     fmt.Printf("Starting server at port 8082\n")

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

go.mod 文件定义导入路径及依赖项。运行如下命令来为你的 Token 服务器创建 go.mod 文件：
```
$ go mod init sampleServer
```
运行如下命令行安装依赖：
```
$ go get
```
运行如下命令行启动服务器：
```
$ go run server.go
```

使用 AccessToken2 鉴权

Web

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

下列参考代码来自灵动课堂 Web 端源码 packages/agora-demo-app/src/pages/home/index.tsx。

向集成了声网 Token 生成器的服务端发起 Token 请求。

 const { token, appId } = await roomApi.getCredentialNoAuth({
     userUuid,
     roomUuid,
     role: userRole,
 });

将请求成功后获取到的 Token 用于创建 launchOption 对象。

 const launchOption = {
 appId,
 sdkDomain,
 pretest: true,
 courseWareList: [],
 language: language as LanguageEnum,
 userUuid: `${userUuid}`,
 rtmToken: token,
 roomUuid: `${roomUuid}`,
 roomType: roomType,
 roomName: `${roomName}`,
 userName: userName,
 roleType: userRole,
 region: region as EduRegion,
 duration: +duration * 60,
 latencyLevel: 2,
 shareUrl,
 };

调用 launch 方法，使用 Token 加入课堂。
```
 AgoraEduSDK.launch(dom, launchOption);  
```

Android

本节以 Android 端灵动课堂 App 为例，展示如何使用 Token 对客户端的用户进行鉴权。

下列参考代码来自灵动课堂 Android 端源码 app/src/main/java/io/agora/education/setting/FcrMainActivity.kt。

向你已经集成了声网 Token 生成器的服务端，发起 Token 请求。

ConfigUtil.getV3Config(region,roomUuid,roleType,userUuid,object : EduCallback<ConfigData> {})

将请求成功后获取到的 Token 用于创建 AgoraEduLaunchConfig 对象。

val config = AgoraEduLaunchConfig(userName, userUuid, roomName,roomUuid, roleType, roomType, token,null,duration)

调用 launch 方法，使用 Token 加入课堂。

 AgoraClassroomSDK.launch(this, config, AgoraEduLaunchCallback { event ->
    // class state
 })

iOS

本节以 iOS 端灵动课堂 App 为例，展示如何使用 Token 对客户端的用户进行鉴权。

以下参考代码来自灵动课堂 iOS 端源码 /App/AgoraEducation/Debug/DebugViewController.swift。

向集成了声网 Token 生成器的服务端发起 Token 请求。

data.requestToken(roomId: info.roomId,
                  userId: finalUserId,
                  userRole: info.roleType.rawValue,
                  success: tokenSuccessBlock,
                  failure: failureBlock)

将请求成功后获取到的 Token 用于创建 AgoraEduLaunchConfig 对象。

let launchConfig = AgoraEduLaunchConfig(userName: userName,
                                        userUuid: userId,
                                        userRole: userRole,
                                        roomName: roomName,
                                        roomUuid: roomId,
                                        roomType: roomType,
                                        appId: appId,
                                        token: token,
                                        startTime: nil,
                                        duration: nil,
                                        region: region,
                                        mediaOptions: nil,
                                        userProperties: nil)

调用 launch 方法，使用 Token 加入课堂。

AgoraClassroomSDK.launch(launchConfig,
                          success: launchSuccessBlock,
                          failure: failureBlock)

参考

AccessToken2 生成器代码

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

App 全局 Token

作用域为 App 全局操作，如创建教室，设置和查询房间等。

语言	算法	核心方法	示例代码
C++	HMAC-SHA256	BuildAppToken	N/A
Go	HMAC-SHA256	BuildAppToken	sample.go
Java	HMAC-SHA256	buildAppToken	EducationTokenBuilder2Sample.java
Node.js	HMAC-SHA256	buildAppToken	EducationTokenSample.js
PHP	HMAC-SHA256	buildAppToken	EducationTokenBuilderSample.php
Python 2	HMAC-SHA256	build_app_token	education_token_builder_sample.py
Python 3	HMAC-SHA256	build_app_token	education_token_builder_sample.py

个人用户 Token

作用域为指定 App ID 下的用户级别操作，可跨房间使用，如个人云盘。

语言	算法	核心方法	示例代码
C++	HMAC-SHA256	BuildUserToken	N/A
Go	HMAC-SHA256	BuildUserToken	sample.go
Java	HMAC-SHA256	buildUserToken	EducationTokenBuilder2Sample.java
Node.js	HMAC-SHA256	buildUserToken	EducationTokenSample.js
PHP	HMAC-SHA256	buildUserToken	EducationTokenBuilderSample.php
Python 2	HMAC-SHA256	build_user_token	education_token_builder_sample.py
Python 3	HMAC-SHA256	build_user_token	education_token_builder_sample.py

指定房间指定用户（客户端使用）

作用域为指定房间中的指定用户，该 Token 打包了 ServiceEducation 和 ServiceRtm 两个服务，在客户端 SDK 启动时传入，可以帮助用户打通灵动课堂及 RTM 用户登录的 token。

语言	算法	核心方法	示例代码
C++	HMAC-SHA256	BuildRoomUserToken	N/A
Go	HMAC-SHA256	BuildRoomUserToken	sample.go
Java	HMAC-SHA256	buildRoomUserToken	EducationTokenBuilder2Sample.java
Node.js	HMAC-SHA256	buildRoomUserToken	EducationTokenSample.js
PHP	HMAC-SHA256	buildRoomUserToken	EducationTokenBuilderSample.php
Python 2	HMAC-SHA256	build_room_user_token	education_token_builder_sample.py
Python 3	HMAC-SHA256	build_room_user_token	education_token_builder_sample.py

AccessToken 生成器代码

如果你使用的是 AccessToken，可参考以下示例代码：

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

开发注意事项

参数匹配

生成 Token 时填入的用户 ID，需要和登录灵动课堂系统时填入的用户 ID 一致。

App 证书与 Token

生成 Token 需要先在控制台启用对应项目的 App 证书。项目一旦开启了 App 证书，就必须使用 Token 鉴权。

这篇文章对你有帮助吗？

是

否