常见问题

产品 / 插件
平台 / 框架

ZIM 如何从 AppSign 鉴权升级为 Token 鉴权?

产品 / 插件:即时通讯

平台 / 框架:iOS / Android / macOS / Windows / React Native / uni-app

更新时间:2022-10-31 15:05


文档导读

为了提高项目的安全性,对于使用 AppSign 鉴权的开发者,可以使用 Token 鉴权、且鉴权通过后才能使用相关服务(如果您不需要,可继续使用 AppSign 鉴权方式),您可以参考本文档进行升级。

  • 开始支持 “AppSign 鉴权” 的 SDK 版本:

    • iOS/Android/macOS/Windows:2.3.0 及以上版本,2022-08-12 发布。
    • uni-app/React Native:2.3.0 及以上版本,2022-08-30 发布。
    • Flutter:2.3.0 及以上版本,2022-09-02 发布。
    • 其余平台:暂不支持 AppSign 鉴权。
  • 所有版本的 SDK,均支持 “Token 鉴权”。

方案说明

ZIM SDK 提供了如下 “Token 鉴权” 的接入方案:

/Pics/ZIM/quick_start_Structure.png

在此方案中,您需要通过您自己的业务系统实现以下业务逻辑:

  • 搭建客户端的用户管理逻辑,并下发用户 ID 用于客户端登录。
  • 鉴权 Token,建议由您的业务后台自行实现,保证鉴权数据安全。

鉴权方式

鉴权方式 功能描述 安全级别
AppSign 鉴权
在创建 ZIM 实例时传入 AppSign,鉴权通过后即可使用 ZIM 功能。
该方式不兼容 Token 鉴权,使用时,请在登录 ZIM 时给 Token 传入空字符串。
安全级别很低。
原因为:如果 AppSign 被泄漏,攻击者会盗用您的云服务流量,并且 AppSign 没有过期机制,建议您尽快升级为 Token 鉴权。
Token 鉴权(推荐)
Token 鉴权是在登录 ZIM 时必须传入 Token,鉴权通过后即可使用实时音视频功能。
该方式不兼容 AppSign 鉴权,当开发者切换为 Token 鉴权后,请在登录 ZIM 时传入正确的 Token,鉴权通过才可以使用 ZIM 功能。
安全级别高。
原因为:通过开发者自建服务端下发 Token,并且在客户端上进行认证,且下发的 Token 具有时效性。因此,我们推荐您使用 Token 鉴权。

升级指导

服务开通

  • 2.3.3 及以上 版本的 SDK,支持鉴权方式的自主切换,无需联系 ZEGO 技术支持处理。
  • 以下版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理。
    • iOS/Android/macOS/Window:2.3.0 ~ 2.3.1 版本。
    • uni-app/React Native/Flutter:2.3.0 版本。
  • 2.3.0 以下 版本的 SDK,默认为 “Token 鉴权”,不支持 “AppSign 鉴权”,无需另行开通。

生成 Token

开发者客户端向开发者服务端发送请求申请 Token,由开发者服务端生成 Token 后返回给到对应客户端。

ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件,支持使用 Go、C++、Java、Python、PHP、.NET、Node.js 语言,在开发者的服务端或客户端部署生成 Token(不推荐客户端生成)。

生成 Token 的详细介绍请参考如下文档:

产品 参考文档
即时通讯

使用 Token

本章主要介绍您升级 SDK 后如何使用 Token 功能。

各平台的实现流程如下:

iOS/macOS

  1. 已下载并集成最新版本的 SDK,详情请参考 集成 SDK

  2. 调用 createWithAppConfig 接口创建 ZIM 实例时,ZIMAppConfig 中的 “AppSign” 传空或者不传。

    // 创建 ZIM 对象,传入 appID、appSign
    // 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式:
    // (1) 2.3.3 及以上版本的 SDK,支持鉴权方式的自主切换; (2) 2.3.0 ~ 2.3.1 版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理
    ZIMAppConfig *appConfig = [[ZIMAppConfig alloc] init];
    appConfig.appID = (unsigned int)appID;     //替换为您申请到的 AppID
    appConfig.appSign = @"appSign";     //AppSign 传空或者不传
    self.zim = [ZIM createWithAppConfig: appConfig];
  3. 调用 loginWithUserInfo 接口登录 ZIM 时,需要填入开发者服务器生成的 Token。

    // userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
    // userName 最大 64 字节的字符串,无特殊字符限制。
    ZIMUserInfo *userInfo = [[ZIMUserInfo alloc]init];
    userInfo.userID = @"zegoUser1"; //填入NSString类型的值
    userInfo.userName = @"zegotest";//填入NSString类型的值
    
    // 登录时:
    // 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
    [zim loginWithUserInfo:userInfo token:token callback:^(ZIMError * _Nonnull errorInfo) {
        //这里填写登录的回调
    }];
  4. 在收到的 tokenWillExpire 回调后,调用 renewToken 接口更新 Token 并传入 SDK 即可。

    - (void)zim:(ZIM *)zim tokenWillExpire:(unsigned int)second {
        NSString *token = [MyToken getToken]; // 重新请求开发者服务端获取 Token
        [self.zim renewToken:token callback:^(ZIMError * _Nonnull errorInfo) {
            // 开发者可根据 ZIMErrorCode 来判断更新 Token 是否成功。
            ......
        }];
    }

Android

  1. 已下载并集成最新版本的 SDK,详情请参考 集成 SDK

  2. 调用 create 接口创建 ZIM 实例时,ZIMAppConfig 中的 “AppSign” 传空或者不传。

    // 创建 ZIM 对象,传入 appID、appSign 与 Android 中的 Application
    // 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式:
    // (1) 2.3.3 及以上版本的 SDK,支持鉴权方式的自主切换; (2) 2.3.0 ~ 2.3.1 版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理
    ZIMAppConfig appConfig = new ZIMAppConfig();
    appConfig.appID = 12345;  //替换为您申请到的 AppID
    appConfig.appSign = "appSign";   //AppSign 传空或者不传
    zim = ZIM.create(appConfig, application);
  3. 调用 login 接口登录 ZIM 时,需要填入开发者服务器生成的 Token。

    // userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
    // userName 最大 64 字节的字符串,无特殊字符限制。
    ZIMUserInfo zimUserInfo = new ZIMUserInfo();
    zimUserInfo.userID = userID;
    zimUserInfo.userName = userName;
    
    // 登录时:
    // 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
    zim.login(zimUserInfo, token, new ZIMLoggedInCallback() {
        @Override
        public void onLoggedIn(ZIMError error) {
            // 开发者可根据 ZIMError 来判断是否登录成功。          
        }
    });
  4. 在收到的 onTokenWillExpire 回调后,调用 renewToken 接口更新 Token 并传入 SDK 即可。

    @Override
    public void onTokenWillExpire(int second){
        String token = getToken(); // 重新请求开发者服务端获取 Token;
        engine.renewToken(token, new ZIMTokenRenewedCallback {
            @Override
            public void onTokenRenewed(String token, ZIMError error) {
                // 开发者可根据 ZIMError 来判断更新 Token 是否成功
            } 
        });
    }

Windows

  1. 已下载并集成最新版本的 SDK,详情请参考 集成 SDK

  2. 调用 create 接口创建 ZIM 实例时,ZIMAppConfig 中的 “AppSign” 传空或者不传。

    // 创建 ZIM 对象,传入 appID、appSign,目前仅建议一个客户端创建一个zim实例
    // 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式:
    // (1) 2.3.3 及以上版本的 SDK,支持鉴权方式的自主切换; (2) 2.3.0 ~ 2.3.1 版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理
    zim::ZIMAppConfig app_config;
    app_config.appID = 12345;     //替换为您申请到的 AppID
    app_config.appSign = "appSign";   //AppSign 传空或者不传
    zim_ = zim::ZIM::create(app_config);
  3. 调用 login 接口登录 ZIM 时,需要填入开发者服务器生成的 Token。

    // userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
    // userName 最大 64 字节的字符串,无特殊字符限制。
    zim::ZIMUserInfo user_info;
    user_info.userID = user_id;
    user_info.userName = user_name;
    
    // 登录时:
    // 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
    zim_->login(user_info, token, [=](zim::ZIMError errorInfo){
        // 这里可以获取登录结果返回值,并根据错误码执行用户代码
    });
  4. 在收到的 onTokenWillExpire 回调后,调用 renewToken 接口更新 Token 并传入 SDK 即可。

    void onTokenWillExpire(ZIM * zim, unsigned int second) override {
        std::string token = getToken(); // 重新请求开发者服务端获取 Token
        zim->renewToken(token, [=](const std::string &token, zim::ZIMError errorInfo) {
            // 开发者可根据 errorInfo 中的 code 来判断更新 Token 是否成功
            ......
        });
    }

uni-app

  1. 已下载并集成最新版本的 SDK,详情请参考 集成 SDK

  2. 调用 create 接口创建 ZIM 实例时,ZIMAppConfig 中的 “AppSign” 传空或者不传。

    // 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式:
    // (1) 2.3.3 及以上版本的 SDK,支持鉴权方式的自主切换; (2) 2.3.0 版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理
    
    // 静态同步方法,创建 zim 实例,传入 AppID 和 AppSign
    // create 方法仅第一次调用时会创建 ZIM 实例,后续调用会返回 null。
    ZIM.create({ appID: 0, appSign: '' });
    // 通过 getInstance 获取单实例,避免热更新导致 create 多次创建返回 null。
    var zim = ZIM.getInstance();
  3. 调用 login 接口登录 ZIM 时,需要填入开发者服务器生成的 Token。

    // userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
    // userName 最大 64 字节的字符串,无特殊字符限制。
    var userInfo = { userID: 'xxxx', userName: 'xxxx' };
    
    // 登录时:
    // 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
    var token = '';
    zim.login(userInfo, token)
        .then(function () {
            // 登录成功
        })
        .catch(function (err) {
            // 登录失败
        });
  4. 在收到的 tokenWillExpire 回调后,调用 renewToken 接口更新 Token 并传入 SDK 即可。

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

React Native

  1. 已下载并集成最新版本的 SDK,详情请参考 集成 SDK

  2. 调用 create 接口创建 ZIM 实例时,ZIMAppConfig 中的 “AppSign” 传空或者不传。

    // 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式:
    // (1) 2.3.3 及以上版本的 SDK,支持鉴权方式的自主切换; (2) 2.3.0 版本的 SDK,需要切换为 “Token 鉴权” 时,请联系 ZEGO 技术支持处理
    
    // 静态同步方法,创建 zim 实例,传入 AppID 和 AppSign
    // create 方法仅第一次调用时会创建 ZIM 实例,后续调用会返回 null。
    ZIM.create({ appID: 0, appSign: '' });
    // 通过 getInstance 获取单实例,避免热更新导致 create 多次创建返回 null。
    var zim = ZIM.getInstance();
  3. 调用 login 接口登录 ZIM 时,需要填入开发者服务器生成的 Token。

    // userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
    // userName 最大 64 字节的字符串,无特殊字符限制。
    var userInfo = { userID: 'xxxx', userName: 'xxxx' };
    
    // 登录时:
    // 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
    var token = '';
    zim.login(userInfo, token)
        .then(function () {
            // 登录成功
        })
        .catch(function (err) {
            // 登录失败
        });
  4. 在收到的 tokenWillExpire 回调后,调用 renewToken 接口更新 Token 并传入 SDK 即可。

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

Flutter

  1. 已下载并集成最新版本的 SDK,详情请参考 集成 SDK

  2. 调用 create 接口创建 ZIM 实例时,ZIMAppConfig 中的 “AppSign” 传空或者不传。

    // 创建 
    // 通过插件创建 ZIM 单实例,传入 APPID、AppSign
    // 请注意:ZIM 从 2.3.0 版本开始支持 AppSign 鉴权,SDK 也默认为 AppSign 鉴权,如果您需要切换鉴权方式,请联系 ZEGO 技术支持切换配置
    ZIMAppConfig appConfig = ZIMAppConfig();
    appConfig.appID = appID;
    appConfig.appSign = appSign;  //AppSign 传空或者不传
    
    ZIM.create(appConfig);
  3. 调用 login 接口登录 ZIM 时,需要填入开发者服务器生成的 Token。

    // userID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
    // userName 最大 64 字节的字符串,无特殊字符限制。
    ZIMUserInfo userInfo = ZIMUserInfo();
    userInfo.userID = "userID"; //填入 string 类型的值
    userInfo.userName = "userName";//填入 string 类型的值
    
    // 登录时:
    // 使用 Token 鉴权,需要开发者填入 "使用 Token 鉴权" 文档生成的 Token,详情请参考 [使用 Token 鉴权]
    
    ZIM
    .getInstance()
    !.login(userInfo, "token")
    .then((value) {
        //登录成功触发此处
    })
    .catchError((onError) {
        switch (onError.runtimeType) {
            // 登录失败触发此处
            case PlatformException:
                log(onError.code); //登录失败错误码
                log(onError.message!);//登录失败错误信息
                break;
            default:
        }
    });
  4. 在收到的 onTokenWillExpire 回调后,调用 renewToken 接口更新 Token 并传入 SDK 即可。

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