企业微信集成

注意：

  • 企业微信对接要求：使用扫码登录和从企业微信打开网盘时, 要求有公网域名。
  • 如果只在内网使用，可以考虑使用企业微信验证码登录。

更新说明：

自2022年6月20日起，企业微信对通讯录相关接口做了升级调整。在此之后创建的自建应用，或做过回调地址、可信IP调整的应用，将只能使用新版接口。 为适应接口变更，本插件在版本v1.58+对新旧版本做了兼容调整。调整后，部分功能配置及使用有所变化，具体请参考 # 7. 更新说明

Kod的企业微信插件，是结合企业微信中的自建应用（免密登录），来实现企业微信通讯录信息同步和网页扫码登录。 wx_kod

企业微信集成功能概述

  1. 用户数据集成：企业微信用户集成同步到可道云。
  2. 部门数据集成：企业微信部门集成同步到可道云。
  3. 用户实时同步：在企业微信后台新增、修改、删除用户；数据自动实时同步到可道云。
  4. 部门实时同步：在企业微信后新增、修改、删除部门；数据自动实时同步到可道云。
  5. 企业微信APP中单点登录：在企业微信中打开可道云应用，能自动识别当前登录的用户并自动登录对应账号。
  6. 企业微信扫码登录可道云：电脑/浏览器端打开可道云，通过企业微信扫码可以实现自动登录。

wx_des

对接流程

注意：

  • 企业可信IP是企业微信方面限制的白名单, 如果有变更, 请及时修改, 否则将无法使用企业微信登录。

1. 插件中心安装插件

管理员登录；插件中心，安装『企业微信』插件。 在企业微信插件配置界面，需填写如下几个参数，以完成配置：

  1. 企业应用CorpId
  2. kod应用AgentId
  3. kod应用Secret
  4. 推送回调Token(可选)
  5. EncodingAESKey(可选)

wx_server

通过后续步骤，可获取到相关参数。

2. 企业ID

如尚未注册企业微信，请前往 注册

登录企业微信，导航栏【我的企业】，页面底部，获取到 企业IDCorpId [1]。

3. 通讯录设置

  • 导航栏【管理工具】，点击【通讯录同步】 - 【企业可信IP】：填写kod服务器IP地址。

wx_list

4. 创建应用

导航栏【应用管理】，选择【自建应用】进行创建。 wx_panel 点击新创建的应用，可以获取到AgentId [2]、Secret [3]。 wx_app 继续下拉可以看到开发者接口设置 wx_dev

  • 可见范围：企业根部门。其范围会影响用户登录和通讯录同步(须设置到根部门,否则拉取用户列表会异常)
  • 应用主页：填写kod地址，如：https://kod.kodcloud.com
  • 网页授权及JS-SDK：只需设置OAuth2.0授权的可信域名，填写kod域名，如 kod.kodcloud.com wx_domain
  • 企业微信授权登录：启用Web网页，填写授权回调域名，如 kod.kodcloud.com wx_callback
  • 企业可信IP：填写kod服务器IP地址。

5. 同步方式

可道云提供了两种同步企业微信通讯录的方案：实时推送、定时拉取。

  • 实时推送：在企业微信后台开启通讯录同步API接口方式，并完成接收事件服务器配置后，如果企业微信通讯录的数据发生变动，会实时推送到kod系统，kod接收数据后进行更新。

提示：

  • 此方式只有在企业微信通讯录发生变化时才进行推送（且只推送有变化的部分），因此在完成插件配置后，需在【同步设置】页点击【手动同步用户数据】，进行一次数据初始化同步。
  • 新版接口推送触发条件：成员所属部门或userid发生变更、部门父节点变更时。
  • 定时拉取：kod系统通过企业微信提供的接口，定时拉取（时间推荐默认填写的240分钟，数据量较大时适当增大）通讯录数据进行更新。

提示：

  • 此方式为定时全量拉取企业微信通讯录数据，进行覆盖更新。可能存在同步不及时，增加服务器压力的情况。
  • 新版接口只能拉取成员及部门的ID、名称，覆盖更新的作用不大，故不推荐。

下面详细介绍【实时推送】所需配置—— 导航栏【管理工具】, 点击【通讯录同步】（同步骤3）：

  1. 同步方式：API同步
  2. 权限：API编辑通讯录，并选择开启手动编辑
  3. 设置接收事件服务器
    • URL：[kod地址]/?plugin/weixinAuth/callback
    • Token：随机获取 [4]
    • EncodingAESKey：随机获取 [5]

wx_callback2 点击保存，以验证回调地址——保存前，需先填写并保存插件配置，否则会因为获取不到相关配置参数而导致验证不通过。

openapi回调地址保存不通过

插件选择实时推送时, 才需要填写这些, 把参数填写插件保存后, 再到企业微信保存

6. 配置插件

将如上参数配置到kod企业微信插件配置中，点击【应用】进行保存

如选择同步方式为【实时推送】，需要在企业微信后台配置接收事件服务器之前保存插件配置。

名词解释：

  • 是否同步组织架构：如选择关闭，将不同步部门，只同步用户账号（部门归属默认为根部门）。
  • 允许账号昵称重复：在企业微信通讯录中，可能存在用户昵称（姓名）相同的情况，如关闭该项，同名账号将无法同步。
  • 用户所属部门权限：用户在归属的所有部门中，都设置为这个文档权限。
  • 用户在根部门权限：（点击更多展开设置） 用户在根部门（企业网盘）中的文档权限。
  • 用户存储空间大小：用户个人空间分配大小。
  • 部门存储空间大小：每个部门的共享空间大小。
  • 用户默认权限角色：用户个人角色权限。 wx_sync
  • 失效数据处理：此处的失效数据，主要是指已同步到kodbox系统，但在企业微信通讯录中被删除了的部门和用户。 如选择开启，同步时失效数据将被直接禁用；如选择关闭，则只对失效数据做标记，而不直接禁用，管理员可在后台【用户与部门管理】-【待处理账号】选择管理。
  • 同步指定排除：不需要同步的部门/用户，按名称进行排除，多个时以”,”分隔。关于排除指定部门，如待同步用户的（所有）归属部门都在排除指定范围内，则该用户也不会被同步。 wx_others

7. 更新说明

此次企业微信接口升级，最主要的变化是不再支持通过接口获取用户详情（手机号、邮箱等），详情需要用户主动授权来获取。 根据此变化，插件功能做了如下调整——对于还能正常使用旧版接口的用户，建议不要轻易变更应用：

  • 数据初始化同步，只同步用户id、昵称。用户首次扫码登录时，提示在企业微信App中进行授权，以获取用户详情，更新至系统后台；
  • 取消根据手机号或邮箱自动绑定账号功能。

8. 其他问题

  1. 企业微信点击站点图标，打开的是对话框

    • 要从企业微信打开站点，需要在创建应用时设置应用主页地址。
插件安装, 企业微信, H5应用