企业微信集成

注意：

  • 本节仅适用于单独购买该插件的企业用户。免费用户请忽略本环节。
  • 使用扫码登录和从企业微信打开网盘时，需要配置公网域名。
  • 若仅在内网使用，可考虑企业微信验证码登录方式。

更新说明：

自 2022 年 6 月 20 日起，企业微信对通讯录接口做了升级。在此之后创建的自建应用，或调整过回调地址、可信 IP 的应用，需使用新版接口。 本插件在 v1.58+ 版本已兼容新旧接口，部分配置有所变化，详见本文 第 7 节 更新说明。

可道云的企业微信插件通过企业微信自建应用实现通讯录同步和网页扫码登录。

wx_kod

企业微信对接通常需要公网可访问的域名，原因如下：

  • Webhook/事件回调：企业微信需要将成员变更等事件主动推送到您的服务器，需要固定的公网地址
  • OAuth 2.0 登录：扫码登录、静默授权等流程需要配置公网可访问的回调 URL

企业微信集成功能概述

  1. 用户数据集成：将企业微信用户同步到可道云
  2. 部门数据集成：将企业微信部门结构同步到可道云
  3. 用户实时同步：在企业微信后台增删改用户后，可道云自动更新
  4. 部门实时同步：在企业微信后台增删改部门后，可道云自动更新
  5. 企业微信 App 单点登录：在企业微信中打开可道云应用，自动识别当前用户并登录
  6. 企业微信扫码登录：在电脑浏览器访问可道云，用企业微信 App 扫码即可登录

wx_des

对接流程

注意：

  • 企业可信 IP 是企业微信的白名单限制。若服务器 IP 变更，请及时更新，否则将无法登录。

1. 插件中心安装插件

管理员登录后，进入插件中心，安装「企业微信」插件。在插件配置界面需填写以下参数：

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

wx_server

以下步骤说明如何获取这些参数。

2. 企业 ID

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

登录企业微信管理后台，进入【我的企业】，在页面底部找到企业 ID（CorpId [1]）。

3. 通讯录设置

进入【管理工具】→【通讯录同步】→【企业可信 IP】，填写可道云服务器的外网 IP 地址。

wx_list

4. 创建应用

进入【应用管理】→【自建应用】，创建新应用。

wx_panel

点击新创建的应用，可获取 AgentId [2] 和 Secret [3]。

wx_app

继续下拉，找到开发者接口设置：

wx_dev

  • 可见范围：设为根部门（影响用户登录和通讯录同步；若范围过小，拉取用户列表会异常）
  • 应用主页：填写可道云地址，如 https://kod.kodcloud.com
  • 网页授权及 JS-SDK：在 OAuth2.0 可信域名中填写可道云域名，如 kod.kodcloud.com

wx_domain

  • 企业微信授权登录：启用 Web 网页，填写授权回调域名，如 kod.kodcloud.com

wx_callback

  • 企业可信 IP：填写可道云服务器 IP 地址

5. 同步方式

可道云提供两种通讯录同步方式：

  • 实时推送（推荐）：在企业微信后台配置接收事件服务器后，通讯录变动会实时推送到可道云。

提示：

  • 实时推送只在通讯录发生变化时才推送变更部分。完成插件配置后，需先在【同步设置】页点击【手动同步用户数据】，执行一次全量初始化同步。
  • 新版接口的推送触发条件：成员所属部门或 userid 变更、部门父节点变更时。
  • 定时拉取：可道云定时（默认 240 分钟）从企业微信拉取全量通讯录并覆盖更新。

提示：

  • 定时拉取为全量覆盖，可能存在同步延迟，且会增加服务器压力。
  • 新版接口只能拉取成员及部门的 ID 和名称，覆盖更新效果有限，不推荐。

实时推送的详细配置步骤——进入【管理工具】→【通讯录同步】（同第 3 步）：

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

wx_callback2

点击保存以验证回调地址。注意：验证前需先在可道云插件中填写并保存上述参数，否则验证会失败。

openapi 回调地址保存不通过

只有选择实时推送时才需要配置这些参数。请先在插件中填写并保存，再到企业微信后台保存验证。

6. 配置插件

将以上参数填入可道云企业微信插件配置，点击【应用】保存。

若选择【实时推送】，需在企业微信后台配置接收事件服务器之前先保存插件配置。

配置项说明：

  • 是否同步组织架构：关闭后只同步用户，不同步部门（用户默认归属根部门）
  • 允许账号昵称重复：企业微信中可能存在同名用户；关闭此项后，同名账号将无法同步
  • 用户所属部门权限：用户在其所有归属部门中，统一使用此文档权限
  • 用户在根部门权限：（点击更多展开）用户在根部门（企业网盘）中的文档权限
  • 用户存储空间大小：同步用户的个人空间配额
  • 部门存储空间大小：同步部门的共享空间配额
  • 用户默认权限角色：同步用户的角色权限

wx_sync

  • 失效数据处理：指已同步到可道云、但在企业微信通讯录中被删除的部门和用户。开启后同步时直接禁用；关闭后仅做标记，管理员可在【用户与部门管理 → 待处理账号】中手动处理。
  • 同步指定排除：按名称排除不需要同步的部门或用户，多个用英文逗号分隔。若某用户的所有归属部门都在排除范围内，该用户也不会被同步。

wx_others

7. 更新说明

2022 年 6 月企业微信接口升级后，不再支持通过接口直接获取用户详情（手机号、邮箱等），需用户主动授权。插件做了如下调整——若仍能使用旧版接口，建议不要轻易变更应用配置：

  • 初始化同步只同步用户 ID 和昵称；用户首次扫码登录时，需在企业微信 App 中授权，以获取并更新用户详情
  • 已取消根据手机号或邮箱自动绑定账号的功能

8. 其他问题

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

    • 需要在创建应用时正确设置应用主页地址，才能从企业微信直接打开完整站点。

  2. 选择验证码登录，提示消息网关尚未开启

    • 需要先安装并配置「消息网关」插件

    msgateway

插件安装, 企业微信, H5应用