Baklib 文档中心

飞书集成

本文帮助组织管理员完成飞书(以及 Lark 国际版)单点登录配置,让成员使用飞书账号进入 Baklib 工作台;同时说明账号绑定、通讯录与员工数据同步、飞书工作台免登的配置方法和常见问题。
当前版本支持组织成员的飞书登录与通讯录同步,需要按本文创建企业自建应用。以下能力暂不包含:在飞书应用商店一键安装 Baklib、站点访客使用飞书登录、登录页内嵌飞书二维码组件(登录时会跳转到飞书官方授权页,授权页本身支持扫码或账号登录)。

功能概览

能力
说明
角色
飞书账号登录
登录页出现「使用飞书登录」,授权后进入 Baklib 工作台
管理员配置,成员使用
账号绑定与解绑
成员把飞书身份绑定到已有 Baklib 账号,也可随时解绑
成员
组织级配置
每个 Baklib 组织独立保存自己的飞书自建应用与凭证,互不影响
管理员
部门同步
把飞书组织架构(部门树)同步到 Baklib,可重复执行
管理员
员工导入
从飞书全量拉取成员,确认后导入为 Baklib 员工
管理员
入职 / 离职自动同步
订阅飞书通讯录事件后,成员入职、变更、离职会近实时同步到 Baklib
管理员配置事件
飞书工作台免登
成员在飞书工作台点击 Baklib 应用,自动完成授权并进入工作台
管理员配置,成员使用

管理员配置

前置条件

  • 您是 Baklib 组织的管理员,可以进入「管理后台 → 第三方集成」。
  • 您的飞书租户是团队版或企业版:飞书个人版无法提供企业组织身份与通讯录能力。
  • 您拥有飞书企业管理员或具有开发者权限的账号,可以在飞书开发者后台创建企业自建应用、申请权限并提交发布。部分权限与发版需要企业管理员审核。
  • 您有一个可被公网访问的 Baklib 工作台域名,用于飞书回调。可在「管理后台 → 域名管理 → 工作台域名」查看。
  • 建议在启用飞书登录的同时,保留手机号、邮箱等其它登录方式,避免个别成员无法登录。
  • 首次配置约需 30–60 分钟,飞书侧审核时间另计。

第 1 步:创建飞书企业自建应用

  1. 使用企业管理员或开发者账号登录 飞书开发者后台。
  2. 点击「创建企业自建应用」,填写应用名称(例如 Baklib)、图标与描述。
  3. 进入应用详情,在「应用能力」中开启网页应用能力。
  4. 打开「凭证与基础信息」,记录 App ID(通常以 cli_ 开头)与 App Secret。App Secret 只显示一次,请妥善保存。
企业自建应用只能在本企业内使用,不能授权给其它飞书企业。

第 2 步:配置重定向 URL

进入「开发配置 → 安全设置 → 重定向 URL」,添加上:
https://<您的组织域名>/-/oauth/feishu/callback
请把 <您的组织域名> 替换为您的 Baklib 工作台域名,并注意:
  • 地址必须是 https://,路径与大小写都不能改动;
  • 该地址要与 Baklib 集成详情页显示的「重定向 URL」完全一致;
  • 每个组织使用自己域名下的回调地址,不要照抄其它组织的地址。

第 3 步:申请权限与通讯录数据范围

进入「开发配置 → 权限管理」,按实际需要申请以下权限:
权限
用途
何时需要
登录与用户基本信息
获取成员的飞书身份、姓名、头像,完成登录
必须
通讯录只读(部门、成员)
同步部门、导入员工、接收通讯录事件
需要同步通讯录时
邮箱、手机号
导入员工时填充联系方式;工作台免登自动创建成员时匹配账号
按需,建议最小化申请
申请权限后,还需要在「开发配置 → 权限管理 → 数据权限」中设置应用通讯录权限范围(部分企业也可由飞书管理员在飞书管理后台的「工作台 → 应用管理」中设置)。建议按最小化原则选择「全员」或目标部门。
权限范围过小,同步部门、导入员工时只能拿到部分数据;调整权限或范围后,需要重新发布应用版本并通过审核才会生效。

第 4 步:配置事件与回调(可选,推荐)

如果需要「入职 / 离职自动同步」,进入「开发配置 → 事件与回调」,完成以下配置:
  1. 在「事件配置」中选择「将事件发送至开发者服务器」,请求地址填写 https://<您的组织域名>/-/third_party/feishu/callback。
  2. 保存时飞书会发送一次校验请求,Baklib 会自动返回校验值。若提示校验失败,请确认组织域名可以从公网访问、地址填写完整。
  3. 在「加密策略」中复制 Encrypt Key 与 Verification Token(可重置),稍后填入 Baklib 集成配置。建议两者都配置。
  4. 订阅通讯录事件,然后重新发布应用版本并通过审核,订阅才会生效。
需要订阅以下通讯录事件(建议使用 v2.0 事件):
事件
含义
contact.user.created_v3
成员入职
contact.user.updated_v3
成员信息变更
contact.user.deleted_v3
成员离职
contact.department.created_v3
部门创建
contact.department.updated_v3
部门更新
contact.department.deleted_v3
部门删除
如果飞书开启了事件加密,Baklib 中必须填写对应的 Encrypt Key,否则事件会校验失败;未填写 Verification Token 时,Baklib 不校验事件来源,不建议在生产环境这样使用。
飞书要求事件接收方在 3 秒内响应,Baklib 会先快速响应、再在后台处理。处理失败时飞书会按 15 秒、5 分钟、1 小时、6 小时重试,最多 4 次;重复推送的事件 Baklib 只处理一次。

第 5 步:发布应用

  1. 进入「应用发布 → 版本管理与发布」,创建版本并申请线上发布。
  2. 由企业管理员在飞书管理后台的「工作台 → 应用审核」中通过审核。
  3. 在飞书开发者后台的「应用发布」设置中确认应用可用范围(哪些成员可以使用该应用),只有范围内的成员才能登录或免登。
之后每次修改权限、事件订阅或工作台主页地址,都需要重新创建版本并审核通过。

第 6 步:在 Baklib 添加并启用飞书集成

  1. 以组织管理员身份进入「管理后台 → 第三方集成」。
  2. 点击「添加集成」,选择「飞书 OAuth2」并安装。
  3. 按以下说明填写配置并保存:
配置项
填写说明
App ID
第 1 步记录的 App ID
App Secret
第 1 步记录的 App Secret
品牌
默认「飞书(中国版)」;Lark 国际版选「Lark(国际版)」
授权范围(scope)
可选,多个值用空格分隔;留空则使用应用已开通的权限
Encrypt Key
第 4 步加密策略中的 Encrypt Key;启用事件同步时必填
Verification Token
第 4 步加密策略中的 Verification Token;启用事件同步时建议填写
首次登录自动创建成员
默认关闭。仅影响飞书工作台免登,详见下文说明
保存后返回集成列表,把飞书集成启用。表单页与集成详情页会显示本组织的「重定向 URL」和「事件回调地址」,可用于和飞书后台逐字核对。如需临时关闭飞书登录,在集成列表中停用即可。
「首次登录自动创建成员」默认关闭。开启后,成员首次从飞书工作台打开 Baklib 且尚未绑定时,系统会尝试按手机号或邮箱匹配已有账号;匹配不到且组织允许注册时,会自动创建成员。该方式存在账号安全风险,请评估后再开启。从登录页使用飞书登录时不会自动创建成员。

第 7 步:配置飞书工作台入口(可选)

如需成员在飞书工作台一键打开 Baklib:
  1. 在飞书开发者后台进入「应用能力 → 网页应用」。
  2. 在「桌面端主页」中填写 https://<您的组织域名>/-/third_party/feishu/entry。
  3. 保存后重新发布应用版本并通过审核。
配置完成后,成员在飞书客户端的工作台点击 Baklib 应用即可免登进入;在普通浏览器打开该地址时,会引导到飞书授权页。

配置自检清单

完成以上步骤后,建议先用测试成员验证,再开放给全员。逐项检查:
  • 组织登录页出现「使用飞书登录」按钮;
  • 用一个已绑定飞书的测试成员登录成功;
  • 成员在「个人中心 → 账号绑定」中能看到「飞书」项;
  • 「管理后台 → 部门/员工 → 同步部门」中出现「同步飞书部门」卡片;
  • 「管理后台 → 部门/员工 → 导入员工」中出现「从飞书同步数据」;
  • 在飞书后台保存事件地址时校验通过,并能在修改一个测试成员后看到 Baklib 侧的员工数据变化(需已配置第 4 步);
  • 在飞书客户端工作台点击 Baklib 应用可以免登进入(需已配置第 7 步)。

成员使用

以下功能需要管理员已按上文完成配置,并且您属于飞书应用可用范围内的成员。

用飞书账号登录

  1. 打开组织登录页,点击「使用飞书登录」。
  2. 在飞书授权页完成登录与授权,可以使用飞书扫码或账号登录。
  3. 若该飞书身份已经绑定 Baklib 账号,会直接进入工作台;若尚未绑定,页面会提示「该身份还未绑定登录账号」,请先用已有账号登录并完成绑定,或按组织流程注册新账号后再绑定。
登录全程使用飞书官方授权流程,Baklib 不会要求您输入飞书密码。

绑定或解绑飞书身份

  1. 登录 Baklib,打开个人中心(右上角头像菜单),进入「账号绑定」。
  2. 找到「飞书」一项,点击「绑定」,按提示在飞书完成授权,确认后提示绑定成功。
  3. 已绑定的身份会显示头像与姓名;点击「解除绑定」并确认即可解绑。
解绑后,该飞书身份将无法再登录这个 Baklib 账号,但账号本身和其它登录方式不受影响,之后也可以重新绑定。解绑前请确认账号还有手机号、邮箱或密码等可用的登录方式。

从飞书工作台打开

配置工作台入口后,成员在飞书客户端的工作台找到 Baklib 应用,点击即可打开:
  • 已绑定账号:自动完成授权并进入工作台;
  • 尚未绑定账号:会提示先注册或登录后绑定;
  • 在普通浏览器中打开该入口地址:会引导到飞书授权页,属于正常现象。

通讯录与员工数据

同步部门

  1. 进入「管理后台 → 部门/员工 → 同步部门」。
  2. 找到「同步飞书部门」卡片,点击「同步」并确认。
  3. 等待同步完成,飞书的部门树会创建或更新到 Baklib。
说明:
  • 该操作只同步部门,不会同步员工;
  • 可以重复执行,重复执行会按飞书部门更新名称与层级,并清理已失效的部门对应关系;
  • 建议先同步部门再导入员工,这样员工才能归属到正确的部门。

导入员工

  1. 进入「管理后台 → 部门/员工 → 导入员工 → 从飞书同步数据」。
  2. 第 1 步「同步部门」:可点击「立即同步部门」,或选择「不同步部门,直接下一步」。
  3. 第 2 步「拉取数据」:等待拉取完成;人数较多时可能需要几分钟,可点击「刷新」查看进度。
  4. 第 3 步「检查数据」:确认员工数量与字段,选择导入方式后点击「开始导入」:
    • 增量导入(推荐):只新增或更新本次清单中的员工,不会删除系统已有员工;
    • 完全同步:让系统员工名单与本次清单一致,未出现在清单中的员工会被删除,操作不可撤销,请确认清单包含全部在职员工后再选择。
  5. 在导入任务详情页查看进度与结果。
字段对应关系:姓名、手机号、邮箱、所属部门、工号、职位、性别来自飞书成员资料。若只导入员工、没有同步部门,员工的「所属部门」会为空。
导入使用应用身份拉取数据,受「应用通讯录权限范围」限制。数据不全时,请先调整飞书侧的权限与数据范围。

入职 / 离职自动同步

配置第 4 步的事件与回调后,飞书通讯录的变化会近实时同步到 Baklib:
飞书事件
在 Baklib 中的效果
成员入职
自动创建员工档案并归属部门;若该飞书身份已绑定 Baklib 账号,会关联到该账号
成员信息变更
更新姓名、邮箱、手机号、工号、部门等信息
成员离职
移除对应的员工档案,Baklib 账号本身保留,不影响已注册账号的登录
部门创建 / 更新
同步 Baklib 部门树;缺少上级部门时会自动补齐
部门删除
移除 Baklib 中对应的部门,部门内的员工档案保留
说明:
  • 事件同步是准实时的,通常为秒级到分钟级;
  • 历史数据不会自动补齐,仍建议定期使用「同步部门 / 导入员工」做全量校准;
  • 若事件不生效,请先确认应用版本是否已重新发布并通过审核。

通过Webhook将消息推送至飞书群

在指定的飞书群创建接收消息的机器人,并获取飞书创建机器人的飞书 Hook ID与安全密钥,填入到知识库/资源库/应用库的Webhooks中,那么知识库/资源库/应用库有新增、修改、删除等相关,就会通过机器人发送消息至指定的群。
飞书机器人创建

Lark 国际版

若企业使用 Lark 国际版:
  1. 在 Lark 开发者后台 创建企业自建应用,步骤与飞书一致。
  2. 在 Baklib 集成配置中把「品牌」选择为「Lark(国际版)」。
  3. 保存后,授权页、接口与令牌端点会自动切换为 larksuite.com 域名,无需手工填写端点。
  4. 回调地址规则与中国版相同,使用您这个组织自身的 Baklib 工作台域名即可。
注意事项:
  • Lark 单次请求的授权范围上限为 50 个,飞书中国版为 200 个;
  • 需要自行完成 Lark 租户的权限申请与审核,以及数据出境合规评估与合同约定;
  • 当前版本只提供品牌选择与端点切换的配置能力,尚未在真实 Lark 租户中完成端到端验证;正式启用前请在您的 Lark 租户中完整联调。

常见问题与错误码

登录与授权

现象
可能原因与处理
登录页没有「使用飞书登录」按钮
组织还没有添加或没有启用飞书集成;请管理员在「管理后台 → 第三方集成」中检查
提示应用未发布、无使用权限(错误码 20010)
应用未发布、未通过管理员审核,或当前成员不在应用可用范围内;请飞书管理员确认应用状态与可用范围
授权后提示「该身份还未绑定登录账号」
该飞书身份还没有绑定 Baklib 账号。请先用已有账号登录,在「个人中心 → 账号绑定」中绑定飞书;工作台免登场景可评估开启「首次登录自动创建成员」
错误码 20003 / 20004(授权码无效或过期)
授权码有效期 5 分钟且只能使用一次。请关闭页面后重新发起登录,不要重复刷新回调页
错误码 20027(授权范围未开通)
飞书后台没有申请或开通对应权限,或 Baklib 的「授权范围」中填写了应用未开通的权限。请申请权限并重新发布审核,或清空授权范围
错误码 20071(重定向 URL 不一致)
飞书后台的重定向 URL 与 Baklib 集成中显示的地址不完全一致。请逐字核对协议、域名、端口、路径与大小写,重新保存
错误码 99991679(权限不足)
应用缺少对应接口权限,或应用通讯录权限范围不包含目标成员或部门。补齐权限、调整范围后重新发布审核;同步部门、导入员工、免登获取用户信息时较常见
页面显示「授权失败」并带错误信息
多为凭证或地址配置不一致。请核对 App ID / App Secret 是否为当前应用、重定向 URL 是否一致;仍失败时联系 Baklib 支持,并提供页面上的错误信息

通讯录、事件与工作台

现象
可能原因与处理
同步部门或导入员工的数据不全
飞书「应用通讯录权限范围」配置过小,或邮箱、手机号等字段权限未申请。请调整数据权限范围与字段权限后重试
导入的员工没有所属部门
没有先同步部门,或导入时选择了「不同步部门」。请先执行「同步部门」,再重新导入或手工调整
保存事件请求地址时校验失败
回调地址无法从公网访问、域名或路径填写错误,或 Encrypt Key / Verification Token 与 Baklib 中填写的不一致。请确认地址完整、域名可公网访问后重试
事件已订阅,入职 / 离职没有同步
修改权限或事件后没有重新发布并审核;应用未发布;集成未启用;或订阅的事件不完整。请补齐后重新发布版本并测试
通讯录变化没有立即出现在 Baklib
事件为准实时同步,偶尔会因飞书重试而延迟。稍后刷新即可;也可用「同步部门 / 导入员工」补拉
工作台打开 Baklib 没有自动登录
未配置「网页应用 → 桌面端主页」,或地址未填写为本文第 7 步的入口地址;成员不在应用可用范围;应用未发布。请逐项检查
打开工作台入口提示「请先配置并启用飞书集成」
组织还没有添加或没有启用飞书集成;请管理员检查集成状态后重试

账号与安全

现象
可能原因与处理
解绑飞书后有什么影响
该飞书身份不能再登录这个 Baklib 账号,账号本身和其它登录方式不受影响,之后可以重新绑定。解绑前请确认账号还有其它可用登录方式
停用或删除飞书集成会怎样
停用后登录页不再显示飞书登录、工作台免登不可用,已绑定关系保留;删除集成会清除该组织内所有成员的飞书绑定,之后需要重新添加集成并重新绑定
为什么不能只凭手机号或邮箱自动登录
飞书中的手机号、邮箱可能由管理员导入,未经成员本人实时验证,不适合作为唯一登录凭证。因此默认只允许已绑定的身份登录,「首次登录自动创建成员」默认关闭
App Secret、Encrypt Key 如何保管
仅组织管理员可见,不要发给无关人员或写入前端页面。如怀疑泄露,请在飞书后台重置后回填 Baklib

相关文档