即时通讯
  • iOS
  • Android
  • macOS
  • Windows
  • Web
  • 小程序
  • Flutter
  • Unity3D
  • uni-app
  • React Native : JavaScript
  • 产品简介
  • 下载
  • 快速开始
    • 跑通示例源码
    • 实现基本消息收发
  • 用户相关
  • 房间相关
  • 群组相关
  • 消息相关
  • 呼叫邀请
  • 会话管理
  • 离线推送
  • 客户端 API
  • 服务端 API
  • SDK 错误码
  • 常见问题
  • 文档中心
  • 即时通讯
  • 用户相关
  • 使用 Token 鉴权

使用 Token 鉴权

更新时间:2024-03-06 17:30

1 功能简介

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

2 实现原理

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

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

/Pics/ZIM/Authenticate_users_with_tokens.png

  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

Token 有效时长不能超过 24 天,为保证安全性,ZEGO 强烈建议开发者在自己的服务端生成 Token。

1. 获取 AppID 和 ServerSecret。

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

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

客户端向开发者服务端发送请求申请 Token,由开发者服务端计算 Token 并返回给对应客户端。

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

语言 支持版本 关键函数 具体地址
Go
Go 1.14.15 或以上版本
GenerateToken04
C++
C++ 11 或以上版本
GenerateToken04
Java
Java 1.8 或以上版本
generateToken04
Python
Python 3.6.8 或以上版本
generate_token04
PHP
PHP 7.0 或以上版本
generateToken04
.NET
.NET Framework 3.5 或以上版本
GenerateToken04
Node.js
Node.js 8 或以上版本
generateToken04

以 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. 开发者浏览器端生成 Token。

以下示例代码仅供参考。Token 有效时长不能超过 24 天,为保证安全性,ZEGO 强烈建议开发者在自己的服务端生成 Token。

浏览器端生成 Token 的代码示例请参考如下:

import CryptoJS from 'crypto-js';

const appConfig = {
    appID: 0, // 填写申请的 AppID
    serverSecret: '', // 填写申请的 ServerSecret
};

/**
 * 生成 token
 *
 * Token = “04” + Base64.encode(expire_time + IV.length + IV + 二进制密文.length + 二进制密文)
 * 算法:AES<ServerSecret, IV>(token_json_str),使用模式: CBC/PKCS5Padding
 *
 * 这里仅提供生成 token 的客户端示例代码。请务必在您的业务后台生成 token,避免泄漏您的 ServerSecret
 */
export function generateToken(userID, seconds) {
  if (!userID) return '';

  // 构造 加密数据
  const time = (Date.now() / 1000) | 0;
  const body = {
    app_id: appConfig.appID,
    user_id: userID,
    nonce: (Math.random() * 2147483647) | 0,
    ctime: time,
    expire: time + (seconds || 7200),  // 有效时长不能超过 24 天
  };
  // 加密 body
  const key = CryptoJS.enc.Utf8.parse(appConfig.serverSecret);
  let iv = Math.random().toString().substring(2, 18);
  if (iv.length < 16) iv += iv.substring(0, 16 - iv.length);

  const ciphertext = CryptoJS.AES.encrypt(JSON.stringify(body), key, { iv: CryptoJS.enc.Utf8.parse(iv) }).toString();
  const ciphert = new Uint8Array(Array.from(atob(ciphertext)).map((val) => val.charCodeAt(0)));
  const len_ciphert = ciphert.length;

  // 组装 token 数据
  const uint8 = new Uint8Array(8 + 2 + 16 + 2 + len_ciphert);
  // expire: 8
  uint8.set([0, 0, 0, 0]);
  uint8.set(new Uint8Array(new Int32Array([body.expire]).buffer).reverse(), 4);
  // iv length: 2
  uint8[8] = iv.length >> 8;
  uint8[9] = iv.length - (uint8[8] << 8);
  // iv: 16
  uint8.set(new Uint8Array(Array.from(iv).map((val) => val.charCodeAt(0))), 10);
  // 密文 length: 2
  uint8[26] = len_ciphert >> 8;
  uint8[27] = len_ciphert - (uint8[26] << 8);
  // 密文
  uint8.set(ciphert, 28);

  const token = `04${btoa(String.fromCharCode(...Array.from(uint8)))}`;
  console.log('generateToken', iv.length, body, token);

  return token;
}

3.2 设置 Token

Token 有效时长不能超过 24 天,为保证安全性,ZEGO 强烈建议开发者在自己的服务端生成 Token。

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

var useID = 'xxxx';
var config = {
    userName: 'xxxx',
    token: '',// 有效时长不能超过 24 天,请求开发者服务端获取
}

zim.login(useID, config)
    .then(function() {
        // 登录成功
    })
    .catch(function(err) {
        // 登录失败
    });

3.3 Token 过期时的处理方式

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

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

// 注册监听“令牌即将过期”的回调
zim.on('tokenWillExpire', function(zim, second) {
    var token = ''; // 有效时长不能超过 24 天,重新请求开发者服务端获取 Token
    zim.renewToken(token)    
        .then(function({ token }) {
            // 更新成功
        })
        .catch(function(err) {
            // 更新失败
        });
})

4 API 参考

方法 描述
login 登录 ZIM 服务。
renewToken 更新鉴权 Token。
tokenWillExpire Token 过期回调。
本篇目录