飞书应用接入指南
本文面向租户管理员，介绍如何在企业的飞书开放平台后台创建自建应用，并将其接入 OpenToken，以启用飞书扫码登录和组织架构（部门、人员）同步能力。
请登录 飞书开放平台，在当前企业的管理后台完成以下操作。
1. 创建自建应用
在飞书开放平台后台创建一个自建应用，然后进入 凭证与基础信息 页面，获取并妥善保存：
- App ID
- App Secret
2. 获取事件加密凭证
进入 事件与回调 → 加密策略，获取并记录：
- Encrypt Key（加密 Key）
- Verification Token（验证 Token）
这两项凭证在该页面直接可见，无需先配置事件订阅，稍后需要填写到 OpenToken。
3. 申请权限
在 权限管理 中申请以下权限：
| 权限 | 用途 |
|---|---|
contact:contact.base:readonly | 读取通讯录基础信息 |
contact:department.base:readonly | 读取部门基础信息 |
contact:department.organize:readonly | 读取部门组织架构 |
contact:user.base:readonly | 读取用户基础信息 |
contact:user.department:readonly | 确定用户的主部门及多部门归属 |
contact:user.email:readonly | 扫码登录时匹配已有账号 |
contact:user.phone:readonly | 扫码登录时匹配已有账号 |
contact:user.employee_number:read | 同步员工工号 |
contact:user.employee:readonly | 同步员工的离职、暂停、正常等状态 |
tenant:tenant:readonly | 获取企业标识 tenant_key，保存配置时必需 |
tenant:tenant.domain:read | 查询企业域名信息，可选 |
可以逐条搜索添加，也可以使用批量导入：
{
"scopes": {
"tenant": [
"contact:contact.base:readonly",
"contact:department.base:readonly",
"contact:department.organize:readonly",
"contact:user.base:readonly",
"contact:user.department:readonly",
"contact:user.email:readonly",
"contact:user.phone:readonly",
"contact:user.employee_number:read",
"contact:user.employee:readonly",
"tenant:tenant:readonly",
"tenant:tenant.domain:read"
],
"user": []
}
}
每个权限都必须配置 权限可访问的数据范围。在权限列表中点击对应权限的 配置，将“应用身份权限”可访问的数据范围设为 全部成员 并保存。
如果未设为“全部成员”，组织同步只能获取应用创建者可见的部门和人员，可能导致同步数据不完整。
4. 在 OpenToken 中配置并启用
回到 OpenToken，进入 设置 → 企业 IM 登录配置，填写以下四项凭证并保存：
- App ID
- App Secret
- Encrypt Key
- Verification Token
保存后，务必启用该配置。
飞书校验事件回调地址时，会向 OpenToken 发起握手请求。OpenToken 需要使用此处配置的 Encrypt Key 和 Verification Token 正确应答。如果未启用配置就前往飞书填写回调地址，校验会失败。
5. 配置重定向 URL
- 在 OpenToken 的 设置 → 企业 IM 登录配置 中新建或编辑飞书配置。
- 复制只读的 登录回调地址（redirect_uri）。
- 返回飞书开放平台，在 安全设置 → 重定向 URL 中新增该地址并保存。
- 确认飞书登记的地址与 OpenToken 展示的地址完全一致，包括协议、 域名、路径以及结尾是否有斜杠。
6. 配置事件订阅并完成验证
进入飞书开放平台的 事件与回调 → 事件配置：
- 订阅方式选择 将事件发送至开发者服务器，即 Webhook 模式。不要选择长连接或 Stream 模式。
- 回到 OpenToken 的 设置 → 企业 IM 登录配置，复制 事件回调地址 并粘贴到飞书。
- 保存后，飞书会立即向该地址发起握手校验。由于第 4 步已经保存并启用配置，OpenToken 会自动应答。
- 飞书显示验证成功后，即表示回调地址接入完成。
7. 添加订阅事件
在 事件与回调 → 事件配置 → 添加事件 中，添加以下 6 个部门和人员变更事件：
contact.department.created_v3
contact.department.updated_v3
contact.department.deleted_v3
contact.user.created_v3
contact.user.updated_v3
contact.user.deleted_v3
这些事件用于将企业内部门和人员的新增、修改及删除实时同步到 OpenToken。
8. 发布应用
进入 版本管理与发布，创建并发布应用版本。发布前，务必将页面底部的可用范围改为 所有员工；否则除管理员外，其他用户无法通过飞书扫码登录。
9. 飞书登录
完成上述配置并发布应用后，用户可在 OpenToken 登录页使用飞书扫码登录。首次扫码时，系统会根据当前飞书账号是否已关联 OpenToken 账号，引导用户创建新账号或绑定现有账号。
9.1 使用飞书扫码
在登录页切换到 飞书扫码登录，打开飞书 App 扫描二维码，并在飞书中确认授权。二维 码失效时，刷新页面后重新扫描。
9.2 选择账号处理方式
如果当前飞书账号尚未关联 OpenToken 账号，系统会显示账号处理选项。已有 OpenToken 账号的用户选择 绑定现有账号；尚无 OpenToken 账号的用户选择 创建新账号。
9.3 创建新账号
点击 创建新账号，依次填写登录用户名、登录密码和确认密码。用户名最多 30 位；密码为 8 至 64 位，并同时包含字母和数字。确认两次密码一致后，点击 创建。创建成功后，当前飞书身份会与新账号关联并完成登录。
9.4 绑定现有账号
点击 绑定现有账号，输入已有 OpenToken 账号的登录用户名和登录密码，然后点击 绑定。绑定成功后，当前飞书身份会与该账号关联；以后使用同一飞书账号扫码时可直接登录。
10. 飞书接入后的功能与运作
接入飞书后，企业员工可使用飞书身份扫码登录 OpenToken；更重要的是，企业的部门与人员组织架构统一在飞书中维护，OpenToken 通过事件订阅自动同步，管理员无需在 OpenToken 后台再单独维护一套组织架构，避免两套系统数据不一致、重复维护。
飞书扫码登录。 员工使用飞书 App 扫码并确认授权，即可登录已关联的 OpenToken 账号，无需再记住独立的用户名和密码。
组织架构自动同步。 管理员只需在飞书中新增、修改或删除部门和人员，OpenToken 即通过已订阅的变更事件（增、改、删）实时同步部门层级、人员信息、工号、部门归属及在职状态（正常、暂停、离职等），无需在 OpenToken 后台手动录入或修改，做到“一处维护、自动同步”。
同步范围。 同步范围取决于飞书权限“可访问的数据范围”，需设为“全部成员”，否则只能同步部分人员。
飞书负责身份认证与组织架构数据源，OpenToken 负责账号登录与业务权限；飞书中人员离职或禁用时，OpenToken 会自动同步该状态（离职员工在 OpenToken 中软删除），角色分配与权限调整仍需在 OpenToken 中完成。
完成检查
- 飞书应用已发布，且可用范围为所有员工。
- OpenToken 中的飞书配置已保存并启用。
- 登录回调地址和事件回调地址已在飞书中验证通过。
- 11 项权限均已添加，必要权限的数据范围为全部成员。
- 6 个部门和人员变更事件均已订阅。