Token鑑權是什麼？

Token也稱為動態密鑰，是在加入頻道時用於校驗用户權限的一組字符串；鑑權是指在用户訪問你的系統前，對其進行身份校驗。用户在使用聲網服務，如加入音視頻通話或登錄信令系統時，聲網會使用 Token 對其鑑權。

我們為這種方式提供了一個較為形象的比喻，即：

某個展覽館需要遊客實名認證後，獲取專屬入場券才可參觀。遊客在完成實名認證後可以獲取到具備有效期限制的專屬入場券，在進場時提供在有效期內的入場券，方能進場。其中：

● 展覽館相當於聲網的服務，即音視頻頻道或信令系統等；
●專屬入場券相當於 Token；
●實名認證步驟相當於結合 聲網 AppID、頻道號、用户 ID 等信息 獲取到專屬 Token 的步驟；
●進場時校驗入場券相當於鑑權，即校驗 Token 是否和 聲網 AppID、頻道號、用户 ID 等信息匹配，且在有效期內。

聲網的產品和服務中大部分採用Token 鑑權的方式。下面，我們針對如何生成和使用 Token，以及 Token 鑑權中常見的問題進行詳細的講解。

如何生成和使用Token？

2.1 Token 鑑權原理

在瞭解如何生成和使用Token 前，需要先了解 Token 鑑權的原理。

如圖所示，共分為9個步驟：

1.客户端根據需要，向 app 服務端申請 Token
2.App 服務端生成並返回 Token
3.客户端以 UID、頻道名以及獲取到的 Token 加入頻道
4.聲網平台讀取該 Token 中包含的信息，並進行校驗
5.客户端收到加入頻道成功回調，並獲取用户 UID
6.Token 最大有效期為 24 小時。當即將過期時，客户端會收到 Token 即將過期的回調
7.此時，如果客户端需要繼續進行音視頻互動，需要申請新的 Token
8.App 服務端生成並返回 Token
9.客户端更新 Token這個過程中，用户需要自行實現步驟1、2、3、7、8、9 的代碼邏輯。

其中，對應的Token 包含以下信息：

● 你在聲網控制枱創建項目時生成的 App ID
● 頻道名
● 用户 ID
● 用户權限，如是否能發流或收流
● Token 的過期時間

2.2 申請與生成Token

可以看到，在用户加入頻道前，客户端需要先向服務器申請Token，並在 服務器 生成 Token，且 Token 必須與 需要加入頻道的用户所對應的 AppID、頻道名、用户 ID（UID）信息、用户權限(是否能發流或收流) 一一對應，並且確保生成的 Token 在有效期內。然後才能以 UID、頻道號 和 Token 加入對應頻道。

向服務器申請Token，可以通過向服務器發送 GET 請求等方式自行實現，以下文章以供參考：

● 部署 Token 服務器（官方文檔）：https://docs.agora.io/cn/live-streaming-premium-4.x/token_ser...
●用Token-Flutter 連接 Agora (2021-09-15) https://www.rtcdeveloper.cn/cn/community/blog/22929
● 使用 Swift 部署聲網 Token 服務器 (2022-10-27)： https://www.rtcdeveloper.cn/cn/community/blog/24981
●在NET Core 上建立 Agora AccessToken 服務 (2020-11-14)：https://www.rtcdeveloper.cn/cn/community/blog/19790
● 如何用 GoLang 為聲網 Agora 應用構建 Token 服務器 (2020-12-09)：https://www.rtcdeveloper.cn/cn/community/blog/20102
● 如何使用 NodeJS 為聲網 Agora 應用構建 Token 服務器 (2020-12-03)： https://www.rtcdeveloper.cn/cn/community/blog/20024
● 使用 Java 構建 Agora 令牌服務器 (2021-02-07)：https://www.rtcdeveloper.cn/cn/community/blog/20709
● 用 Java 構建聲網令牌服務器 (2023-01-10)： https://www.rtcdeveloper.cn/cn/community/blog/25430

生成Token，可以使用聲網提供的 Demo 實現，Demo 地址請參考：Token 生成器代碼

*請務必注意：例如用户使用 UID=123456（int 型）加入頻道 ChannelName="test"，那麼生成 Token 時傳入的參數 UID 和 ChannelName 必須是相對應的，即 UID=123456（int 型）且 ChannelName="test"，否則會導致鑑權失敗。

2.3 Token 過期處理

Token最大有效期為 24 小時。當即將過期時，客户端會收到 Token 即將過期的回調；Token 過期時，SDK 會觸發 Token 過期回調。具體處理方式如下：

● 在 Token 過期前 30 秒，SDK 會觸發 tokenPrivilegeWillExpire 回調。收到該回調後，客户端需要從服務器獲取新的Token 並調用 renewToken 將新生成的 Token 傳給 SDK。
● Token 過期時，SDK 會觸發 rtcEngineRequestToken 回調。收到該回調後，客户端需要從服務器獲取新的 Token 並調用 joinChannel 方法，再使用新的 Token 重新加入頻道。

一般來説，我們建議在Token 過期前，及時更新 Token，即從服務器獲取新的 Token 並調用 renewToken 將新生成的Token 傳給 SDK。

常見問題

當你的聲網項目中不存在無證書並且啓用了主要/次要證書，則表示你選擇使用動態密鑰 Token 對用户進行鑑權。

由於Token 具有一定的時效性，因此 app 在運行過程中，你有可能會收到如下與 Token 相關的錯誤碼或事件回調。本文對這些事件進行了梳理，提供觸發的原因以及解決方法，幫助你在 App 出現異常時進行問題排查。

101:App ID無效

問題描述：

● Native 端：SDK 在初始化聲網服務時返回錯誤碼 ERR_INVALID_APP_ID(101)；或調用 joinChannel 方法加入頻道時，SDK 回調 onError 事件，並報告錯誤碼 ERR_INVALID_APP_ID(101)。
● Web 端：在初始化 聲網服務或調用 Client.join 方法加入頻道時，Console 控制枱打印錯誤碼 ERR_INVALID_VENDOR_KEY(101)。

問題原因：

不是有效的App ID，一般是由於 App ID 的數據類型不對引起的。

解決方法：

建議檢查 App ID 數據格式是否有效。聲網的 App ID 為 String 型，請使用正確數據類型的 App ID，重新初始化聲網服務。

109/118/2:Token 已過期

問題描述：

● Native 端：調用 joinChannel 方法加入頻道時，SDK 回調 onError 事件，並報告錯誤碼 ERR_TOKEN_EXPIRED(109)。
● Web 端：調用 Client.join 方法加入頻道時，Console 控制枱打印錯誤碼 ERR_DYNAMIC_KEY_TIMEOUT(109)或ERR_DYNAMIC_KEY_EXPIRED(118)。
問題原因：Token過期。

解決方法：

Token一旦過期，你就需要在服務端重新生成一個 Token，然後調用 renewToken 方法嘗試重新加入頻道。

110:Token 無效

問題描述：

● Native 端：調用 joinChannel 方法加入頻道時，SDK 回調 onError 事件，並報告錯誤碼 ERR_INVALID_TOKEN(110)。
● Web 端：調用 Client.join 方法加入頻道時，Console 控制枱打印錯誤碼 ERR_NO_AUTHORIZED(110)。

問題原因：

生成的 Token 無效。一般有以下原因：

● 你的聲網項目中不存在無證書並且啓用了主要/次要證書，但是加入頻道時卻未傳入 Token；或者項目未開啓主要/次要證書，就試圖使用 Token 加入頻道。
● 你在服務端生成 Token 時填入的 App ID、用户 ID 和頻道名，與你初始化和加入頻道時填入的 App ID、用户 ID 和頻道名不匹配。

解決方法：

● 在加入頻道前，請確認你在初始化時填入的 App ID 對應的項目是否已啓用主要/次要證書。
● 如果未啓用主要/次要證書，則不能使用 Token 加入頻道。
● 如果項目中存在無證書並且已啓用主要/次要證書，則既可以僅使用 App ID 加入頻道，也可以使用主要/次要證書生成的 Token 加入頻道。
● 如果項目中不存在無證書並且已啓用主要/次要證書，則必須使用 Token 加入頻道。
● 當確認使用 Token 加入頻道時，還需要確認：
● 用於生成 Token 的 App ID 和初始化服務時填入的 App ID 一致。
● 用於生成 Token 的用户 ID 和加入頻道時填入的用户 ID 一致，且數據類型也一致。● 用於生成 Token 的頻道名和加入頻道時填入的頻道名一致。

119:靜態廠商使用動態密鑰

該錯誤碼僅適用於RTC Web SDK。

問題描述：

Web端調用 Client.join 方法加入頻道時，Console 控制枱打印錯誤碼 ERR_STATIC_USE_DYNAMIC_KEY(119)。

問題原因：

表示靜態廠商使用了動態密鑰。一般是由於使用的 App ID 對應的聲網項目未啓用主要/次要證書，卻試圖使用 Token 加入頻道引起。

解決方法：

對於未開啓主要/次要證書的項目，你可以不使用 Token 加入頻道。你也可以先啓用主要/次要證書，然後在服務端生成 Token 後重新加入頻道。

120：動態廠商使用靜態密鑰

該錯誤碼僅適用於RTC Web SDK。

問題描述：

Web端調用 Client.join 方法加入頻道時，Console 控制枱打印錯誤碼 ERR_DYNAMIC_USE_STATIC_KEY(120)。

問題原因：

表示動態廠商使用了靜態密鑰。一般是由於使用的 App ID 對應的聲網項目中不存在無證書並且已啓用主要/次要證書，加入頻道時卻沒有傳入 Token 引起。

解決方法：

如果 App ID 對應的項目中不存在無證書並且已啓用主要/次要證書，則必須使用 Token 進行鑑權。你也可以換一個沒有啓用主要/次要證書的項目的 App ID，然後嘗試重新加入頻道。

Token過期相關事件回調

為保證通信體驗，聲網提供如下兩個回調，提醒用户Token 即將過期或已經過期：

● onTokenPrivilegeWillExpire：該回調錶示 Token 即將在 30 秒內失效。收到這個回調時，你需要在服務端重新生成Token，然後調用 renewToken 方法，將新生成的 Token 傳給 SDK。
● onRequestToken（Web 平台為 onTokenPrivilegeDidExpire）：該回調錶示 Token 已經失效。收到這個回調時，你需要在服務端重新生成 Token，然後調用 joinChannel 方法重新嘗試加入頻道。

各語言Token錯誤碼對照

附錄

• 註冊並試用每月 10000 分鐘免費的聲網視頻SDK，體驗四行代碼、三十分鐘快速構建沉浸式實時互動場景
• 下載體驗聲網相關 SDK & Demo