使用 Token 鉴权

---

1 功能简介

使用 Token 鉴权，指用户进行登录时，ZIM 的业务服务端会根据用户登录时携带的 Token 参数，判断用户是否有权限进行登录，避免因权限控制缺失或操作不当引发的风险问题。

2 实现原理

用户登录 ZIM 的服务端之前，开发者服务端应先生成 Token，ZIM 服务端会对带着 Token 的用户进行校验，根据 Token 参数判断用户是否为合法登录的用户。

登录时 Token 校验的流程如下图：

1. 客户端发起申请 Token 的请求。
2. 在开发者的服务端上生成 Token，并返回给客户端。
3. 客户端携带申请到的 Token 和 userID 信息，登录 ZIM SDK。
4. ZIM SDK 会自动将 Token 发送到 ZIM 服务端进行校验。
5. ZIM 服务端会将校验的结果返回给 ZIM SDK。
6. ZIM SDK 再将校验的结果直接返回给客户端，没有权限客户端登录将失败。

3 使用步骤

以下将介绍开发者的服务端如何生成 Token、如何使用 SDK 设置 Token、以及 Token 过期时的处理方式。

3.1 生成 Token

1. 获取 AppID 和 ServerSecret。

前往 ZEGO 控制台 创建项目，获取接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考 项目管理 - 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。

2. 开发者服务端生成 Token。

为方便开发者使用，ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件，支持使用 Go、C++、Java、Python、PHP、.NET、Node.js 等语言，在开发者的服务端部署生成 Token。

以 Go 语言为例，开发者可参考以下步骤使用 zego_server_assistant 生成 Token：

1. 首先将 “go/zegoserverassistant” 目录，拷贝到开发者的服务端项目中。
2. 使用命令 import zsa "your-project-go-mod-path/zegoserverassistant" 引入插件，需要将 “your-project-go-mod-path” 替换为开发者自己的项目名称。
3. 调用插件提供的 GenerateToken04 方法生成 Token。

var appId uint32 = <Your AppId>   // type: uint32
userId := <Your userID>  // type: string
secret := <ServerSecret>  // type: 32 byte length string
var effectiveTimeInSeconds int64 = <Your token effectiveTime> //type: int64; unit: s

token, err := zsa.GenerateToken04(appId, userId, secret, effectiveTimeInSeconds)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(token)

3.2 设置 Token

用户在登录时传入权限相关的 Token，并设置对应的权限。

try{
    ZIMLoginConfig loginConfig = ZIMLoginConfig();
    //该用户的用户昵称，不填写代表不修改用户昵称
    loginConfig.userName = 'userName';
    //若使用 token 作为登录鉴权的方式，请填写该参数，否则无需填写
    loginConfig.token = '';
    // 本次登录是否为离线登录，详情请参考离线登录相关文档
    loginConfig.isOfflineLogin = false;
    await ZIM.getInstance()?.login('zego', loginConfig);
    // 登录成功，编写登录成功的业务逻辑
} on PlatformException catch(onError){
    // 登录失败
    //登录失败的错误码，请参考接入文档的错误码表来处理
    onError.code;
    //登录失败的错误信息
    onError.message;
}

3.3 Token 过期时的处理方式

在 Token 过期前 30 秒，SDK 会通过 onTokenWillExpire 回调发出通知。若登录成功后 Token 有效期不足 30 秒，则会立即回调。

收到该回调后，开发者需要从自己的服务端获取新的有效 Token，并调用 SDK 提供的 renewToken 接口更新 Token。

ZIMEventHandler.onTokenWillExpire = (zim, second) {
    ZIM.getInstance().renewToken('new token');
};