跳转至

飞书集成指南

1. 集成能力与配置顺序

CAN 的飞书集成由一套企业自建应用提供凭证，可按需启用以下能力：

能力 是否必需 说明
飞书单点登录 按需 用户从 CAN 登录页跳转至飞书授权，授权后返回 CAN。
用户绑定同步 按需 将 CAN 用户与飞书用户建立映射；支持手动、字段自动匹配和通过数据表匹配。
飞书应用消息推送 按需 使用飞书应用向用户或群发送 CAN 监控消息。
飞书机器人 Webhook 推送 按需 使用群机器人 Webhook 推送；不依赖 App ID / App Secret。

建议按以下顺序实施：

  1. 创建飞书企业自建应用，记录凭证并配置能力、权限和可见范围。
  2. 在 CAN 的“办公软件”中保存飞书凭证并启用集成。
  3. 仅在需要单点登录时，于“登录认证”中启用飞书登录。
  4. 仅在需要用户映射或消息接收人选择时，配置用户绑定同步。
  5. 按实际推送方式配置监控推送，并逐项验收。

2. 前置检查

开始前，请确认以下条件均满足：

  • 已拥有 CAN 平台管理员权限。
  • 已拥有飞书企业管理员或应用管理员权限，能创建并发布企业自建应用、申请权限和设置应用可见范围。
  • CAN 可通过 HTTPS 访问；CAN 服务端可访问 open.feishu.cn。
  • 已准备对外稳定的 CAN 访问地址，例如 https://can.example.com。不要使用本机地址、内网地址或临时环境地址作为生产回调地址。
  • 若 CAN 位于反向代理或负载均衡之后，代理须正确传递外部协议、主机名和端口；否则飞书授权回调时可能出现 redirect_uri 不一致。
  • 需要同步或推送的飞书成员、部门和群已纳入应用的数据可见范围。

3. 在飞书开放平台创建并配置应用

3.1 创建企业自建应用

  1. 登录 飞书开放平台。
  2. 在开发者后台选择“创建企业自建应用”。
  3. 填写应用名称、描述和图标后创建。建议使用清晰的生产名称，例如“CAN 数据监控”。
  4. 在应用的“凭证与基础信息”中记录 App ID 与 App Secret。

创建飞书应用

安全要求：App Secret 仅可保存在 CAN 管理后台或企业认可的密钥管理系统中。不要放入文档、截图、工单评论、前端代码或聊天记录。发生泄露时，立即在飞书开放平台重置并同步更新 CAN 配置。

3.2 按功能添加应用能力

使用场景 需要添加的飞书应用能力 配置要求
单点登录 网页应用 在“安全设置”中配置重定向 URL。
应用消息推送 机器人 将机器人能力添加到该自建应用，并确保接收人可使用该应用。
Webhook 推送 群机器人 在目标飞书群内创建机器人并获取 Webhook 地址；这不是自建应用能力。

3.3 配置单点登录重定向 URL

仅在启用“飞书单点登录”时执行本节。

  1. 进入飞书应用的网页应用与安全设置。
  2. 将下列基础地址加入重定向 URL白名单：
https://<CAN-访问域名>/user/softLogin
  1. 示例：CAN 地址为 https://can.example.com 时，重定向 URL 应为 https://can.example.com/user/softLogin。

注意事项：

  • 必须填写完整基础 URL，包含 https://、域名和 /user/softLogin 路径；不能只填写域名。
  • 不要在该地址后手动追加 code、state、softType 或 softCode 参数；CAN 在发起授权时会自动追加必要参数。
  • 生产与测试环境使用不同域名时，分别添加对应的回调地址，并使用各环境独立的应用或独立配置。

3.4 配置应用可见范围并发布

将需要登录、同步或接收应用消息的成员和部门纳入应用的可见范围。完成权限或配置变更后，按飞书页面要求提交审核、发布版本；仅保存草稿可能不会在生产租户生效。

获取应用凭证

4. 飞书权限清单

在飞书应用的“权限管理”中，按实际启用的 CAN 功能申请权限。下表遵循最小权限原则；没有启用的功能无需申请对应权限。

CAN 功能 飞书权限或能力 必需性 用途与注意事项
单点登录 网页应用、重定向 URL 必需 这是应用能力和安全配置，不是 API 权限。CAN 以 OAuth 授权码流程完成登录。
单点登录 获取用户 user_id 必需 CAN 使用飞书用户 user_id 识别已绑定的用户。
用户绑定同步 获取通讯录基本信息 或 以应用身份访问通讯录 必需 CAN 以应用身份读取部门及部门成员；以飞书权限页显示的可申请项为准。
用户绑定同步 获取通讯录部门组织架构信息 / 获取部门基础信息 建议且通常需要 用于遍历部门层级并获取部门成员。权限名称可能因飞书控制台版本而略有差异。
用户绑定同步 获取用户 user_id 必需 CAN 当前以 user_id 作为飞书侧人员标识。
用户绑定同步 获取用户手机号 按需 仅当用户映射字段选择手机号时申请。
用户绑定同步 获取用户邮箱信息 按需 仅当用户映射字段选择邮箱时申请。
飞书应用消息推送 机器人能力 必需 让飞书应用能够以机器人身份向用户或群发送消息。
飞书应用消息推送 以应用身份发消息 必需 用于向单个用户、用户组或群发送监控通知。
飞书应用消息推送（选择群） 获取群组信息 按需 仅在 CAN 中需要查询并选择飞书群作为接收对象时申请。
飞书应用消息推送（加急） 以应用身份发消息；飞书租户的消息加急可用性 按需 CAN 会调用飞书的应用消息加急能力；最终是否可用还受飞书租户版本、成员及平台限制影响。
飞书机器人 Webhook 推送 无 App 权限 不需要 Webhook 由群机器人地址鉴权；若机器人启用签名校验，在 CAN 中配置对应签名密钥。

补充说明：

  • 通讯录权限与应用可见范围是两项独立配置。权限获批但应用不可见时，CAN 仍无法读取相应部门或成员。
  • 手机号、邮箱等属于敏感字段。仅在确有映射需求时申请，并遵循企业数据最小化与审批规范。
  • 飞书会根据应用类型、租户版本与控制台版本调整权限展示名称。配置时应以飞书“权限管理”页面的当前名称为准；本文用于说明所需能力范围。
  • 权限变更或新增应用能力后，需重新发布应用并等待企业管理员审核（如飞书提示需要审批）。

5. 在 CAN 中配置飞书集成

5.1 保存飞书凭证

  1. 使用 CAN 平台管理员登录 CAN。
  2. 进入 平台管理 > 办公软件。
  3. 找到“飞书”，点击编辑。
  4. 填写下列内容：
CAN 字段 填写值 示例
App ID 飞书应用的 App ID cli_xxxxxxxxxxxxxxxx
App Secret 飞书应用的 App Secret 请填写真实密钥，不要使用示例值
回调域名 / 回调地址 CAN 的完整登录回调地址 https://can.example.com/user/softLogin
  1. 保存后开启“飞书”集成开关。

CAN 最新实现会使用该基础回调地址发起飞书授权，并自动追加必要的 softType、softCode、code 与 state 参数。CAN 配置与飞书“重定向 URL”的基础协议、域名、端口和路径必须一致；不要手动添加这些参数。

在 CAN 中开启飞书集成

5.2 启用飞书单点登录（按需）

保存办公软件配置只表示 CAN 已具备飞书集成凭证；若要让用户从登录页使用飞书登录，还需：

  1. 进入 平台管理 > 登录认证。
  2. 找到“飞书”认证方式并启用。
  3. 选择允许使用该认证方式的用户范围：手动创建用户和/或已同步用户。
  4. 如需默认进入飞书登录，可在默认登录方式中选择飞书；建议保留至少一种管理员可用的备用登录方式。
  5. 使用一名已在 CAN 中存在或已完成绑定的飞书测试用户验证登录。

风险提示：首次启用前请确认平台管理员仍可通过备用认证方式登录。不要在未验证飞书登录前关闭所有账号密码或其他管理员登录入口。

5.3 配置用户绑定同步（按需）

用户绑定同步不是创建 CAN 用户的唯一方式；它用于将 CAN 用户与飞书用户标识关联，以支持飞书登录、消息接收人与后续人员匹配。

  1. 进入 管理 > 用户，打开“办公软件绑定”配置。
  2. 选择已开启的飞书集成。
  3. 开启绑定，并选择一种方式：
方式 适用场景 配置建议
自动匹配 CAN 与飞书存在稳定且唯一的共同字段 优先使用账号、邮箱或手机号等唯一字段；避免使用可能重复的姓名。
手动绑定 少量特殊账号或自动匹配无法覆盖的用户 逐个维护 CAN 用户与飞书 user_id 的对应关系。
数据表匹配 用户主数据在外部表中维护 选择 CAN 账号列与飞书用户标识列，先在小范围数据上验证。
  1. 设置手动执行或定时执行；首次上线建议先手动执行并核对结果。
  2. 执行后检查绑定结果，重点确认管理员、告警接收人和同名用户是否匹配正确。

CAN 可用的飞书人员字段包括 user_id、姓名、邮箱和手机号。若以邮箱或手机号作为匹配条件，必须同时确认飞书应用已申请并获批对应的敏感字段权限。

6. 配置飞书监控消息推送（按需）

6.1 飞书应用推送

适用于由 CAN 统一使用已配置的飞书自建应用发送通知。

  1. 确认第 5.1 节的飞书集成已启用，且飞书应用已添加机器人能力并获“以应用身份发消息”权限。
  2. 在 CAN 的监控配置中新增或编辑推送渠道，选择“飞书应用推送”。
  3. 选择接收用户、用户组或飞书群；选择群时应额外确认“获取群组信息”权限和应用可见范围。
  4. 保存后发送测试消息。

使用消息加急时，请先用少量测试账号验证。CAN 当前对单次加急涉及的用户和群数量存在限制；若飞书侧不支持加急，保留普通消息推送作为降级方式。

6.2 飞书机器人 Webhook 推送

适用于将消息投递到特定飞书群，不需要 CAN 保存飞书应用的 App ID / App Secret。

  1. 在目标飞书群中添加自定义机器人，复制 Webhook 地址。
  2. 若机器人开启签名校验，复制其签名密钥。
  3. 在 CAN 的监控推送配置中选择“飞书 Webhook”，填写 Webhook 地址；按需填写签名密钥。
  4. 发送测试消息，并在目标群确认卡片或文本内容。

请将 Webhook 地址视为敏感凭证；任何获得地址的人都可能向该群发送消息。泄露时应在飞书群中重新生成机器人 Webhook 并更新 CAN 配置。

7. 上线验收清单

建议在生产切换前由 CAN 管理员和飞书管理员共同完成下表：

验收项 预期结果
凭证保存 CAN 可保存 App ID、App Secret 与回调地址，飞书集成状态为开启。
重定向 URL 飞书侧与 CAN 侧的基础地址均为 https://<CAN-访问域名>/user/softLogin，协议、域名、端口和路径完全一致。
单点登录 测试用户可跳转飞书、完成授权并回到原 CAN 页面；未绑定用户的行为符合企业预期。
应用可见范围 测试用户、同步部门和告警接收人均在飞书应用可见范围内。
用户绑定 自动、手动或数据表匹配结果正确；同名账号未发生误绑定。
应用消息推送 可向测试用户和测试群发送消息；必要时验证加急行为。
Webhook 推送 测试群收到消息；启用签名校验时签名验证成功。
备用登录 至少一名平台管理员仍可通过备用认证方式进入 CAN。
审计与安全 文档、截图、日志和工单中未出现 App Secret、完整 Webhook 地址或签名密钥。