飞书自建应用绑定简道云

概述

功能简介

本文说明如何通过飞书开放平台创建企业自建应用，并与简道云完成双向参数绑定，使企业成员在飞书工作台中使用简道云。

应用场景

企业已使用飞书办公，且需要自定义应用图标、可用人员范围、机器人消息通道，或需要通过事件订阅自动同步成员入职、离职、信息变更。

前提条件

1. 准备简道云企业

飞书自建应用对接简道云，需要自行准备一个公共模式的简道云企业，用于与飞书对接。

1.1 注册简道云企业

在 简道云 注册账号并创建企业。

已创建过企业可跳过此步，直接登录简道云。

1.2 获取简道云企业租户ID

登录简道云，点击右上角头像，进入「管理后台 > 企业信息」。

在账号模式处确认当前企业为「公共模式」，并记录租户 ID 的值，后续飞书安全配置中需要使用。

2. 飞书侧创建应用

2.1 注册飞书企业

在 飞书 注册账号并创建企业。

已创建过团队可跳过此步，直接 登录飞书 。

2.2 创建飞书自建应用

1）登录 飞书开发者后台

2）首次创建时单击「创建企业自建应用」；已有应用时在「企业自建应用」列表中单击「创建应用」。

3）填写应用名称、应用描述并单击「创建」。创建完毕后进入应用配置页。

2.3 开通应用权限

本节需为应用开通多项权限，缺少任意一项将导致通讯录同步或消息推送失败。

1）进入「权限管理 > 开通权限」。

2）在「应用身份权限」和「用户身份权限」下分别开通以下权限：

3）选择上述权限后，点击「确认开通权限」。

4）设置“应用身份权限”可访问的数据范围。

请将权限可访问的数据范围，配置为「与应用的可用范围一致」。点击「确认」。

2.4 配置初始重定向 URL

本节先填入一个可用的初始回调地址，使后续绑定流程可以跳转回简道云。

1）进入「安全设置 > 重定向 URL」。

2）添加以下地址，并将其中的{tenantId}替换为1.2节获取的简道云企业的「租户 ID」。

https://lark.jiandaoyun.com/portal/tenant/{tenantId}/admin/lark/cp/1/main/install_callback

3）单击「添加」。

2.5 启用网页应用能力

本节先占位创建网页应用能力，最终地址将在第 5 阶段回填。

1）进入「应用能力 > 添加应用能力」。

2）在右侧选择「网页应用」并添加。

3）桌面端主页与移动端主页暂填https://www.jiandaoyun.com，第 5.1 节将替换为简道云返回的正式地址。

4）打开方式按需选择：即用户在飞书工作台访问该应用后的简道云页面打开形式。

5）点击保存。

2.6 获取 AppID 与 App Secret

本步获取 AppID 与 App Secret。

打开应用详情，在「凭证与基础信息」中记录 AppID 与 App Secret。

2.7 获取事件订阅参数

本步获取飞书应用的 Encrypt Key 与 Verification Token。

1）进入「事件与回调 > 加密策略」。

2）首次访问时单击「重置 Encrypt Key」生成密钥。

3）复制并留存 Encrypt Key 与 Verification Token。

2.8 发布应用初始版本

本步发布应用的第一个版本。

1）单击「版本管理与发布 > 创建版本」。

2）填写应用基础信息：

3）填写基础资料后单击「保存 > 确认发布」。

3. 简道云侧单向绑定

3.1 简道云绑定飞书

本阶段目标是把飞书侧的 4 个参数写入简道云，并取回 5 项回填参数。

1）在同一浏览器，分别使用简道云企业创建者账号登录 简道云，使用飞书管理员账号登录 飞书 。

2）飞书安装页面地址如下，请将其中的{tenantId}替换为1.2节获取的简道云企业的「租户 ID」后，在浏览器中访问。

https://lark.jiandaoyun.com/portal/tenant/{tenantId}/admin/lark/cp/1/main/install

3）将2.6与2.7节获取的参数填入表单，点击「安装」。

4）确认飞书企业信息，点击「授权」。

5）绑定成功后，页面将显示以下信息，请务必全部复制存档，，否则需解绑再执行绑定流程才能再次获取。

6）点击「完成」后自动跳转至简道云。

3.2 确认绑定成功

1）管理员登录，进入「管理后台 > 企业信息」页面。

2）企业账号模式变更为「飞书集成模式」，并显示飞书自建应用的相关信息，说明3.1节绑定成功。

3）请记录下该页面的「企业账号 URL」信息，将在下文使用。

4. 飞书侧完善应用配置

4.1 回写重定向 URL

添加重定向 URL 作为免登授权码跳转地址。

1）在飞书自建应用配置页面，进入「安全设置 > 重定向 URL」。

2）添加 3.1 节获取的重定向 URL1 与 URL2 。

3）添加以下重定向 URL，请将其中的{corpid}替换为 3.1 节获取的企业 ID。

https://lark.jiandaoyun.com/lark/corp/{corpid}/auth

4.2 回写网页应用配置

在飞书自建应用配置页面，进入「 网页应用>网页应用配置」，点击「编辑」。

在对应位置添加 3.1 节获取的桌面端主页与移动端主页，点击「保存」。

4.3 设置事件订阅

事件订阅用于将飞书通讯录变动实时同步至简道云。

1）在飞书自建应用配置页面，进入「事件与回调 >订阅方式」，点击「编辑」。

2）选择「将事件发送至开发者服务器」，将 3.1 节获取的请求地址 URL 填入，点击「保存」。

3）订阅方式设置成功后，单击「添加事件」，在「应用身份订阅」中添加以下事件：

4.4 添加机器人

机器人用于向飞书成员推送简道云的流程与数据提醒；不添加则成员无法在飞书中收到简道云消息。

1）进入「应用能力>添加应用能力」。

2）选择「机器人」并单击「添加」。

4.5 配置 H5 可信域名

配置可信域名后，简道云表单才能在飞书移动端调用定位等 JSAPI 能力。

1）进入「安全设置 > H5 可信域名」。

2）添加以下域名并保存。

https://lark.jiandaoyun.com

4.6 重新发布版本

由于 4.1 至 4.5 节修改了应用配置，需再次发布版本才能生效。

1）单击「版本管理与发布 > 创建版本」。

2）填写应用基础信息：

3）填写基础资料后单击「保存 > 确认发布」。

5. 通讯录配置与同步

本阶段目标是让应用的通讯录读取范围与可用人员范围一致，避免成员同步不全。

5.1 飞书侧调整应用可用范围和应用权限

1）访问「飞书管理后台」

2）在「工作台>应用管理」中找到该自建应用，单击「配置」。

3）设置可使用该应用的成员范围。

4）在自建应用的「应用权限>通讯录设置」中勾选「与可用人员范围保持一致」。

5.2 简道云同步飞书通讯录

管理员登录简道云，单击「管理后台>内部组织」，单击「立即同步」，将飞书通讯录同步至简道云。

6. 完成绑定

完成上述步骤后，即完成了简道云与飞书的绑定，拥有可用性权限的成员可以在飞书中使用简道云。

7. 注意事项

1）一个简道云企业只能绑定一个飞书企业，绑定前请确认目标飞书企业无误。

2）修改飞书应用配置后必须重新发布版本，仅保存不发布不会生效。

3）参数变更需要手动同步。

当飞书开放平台的 AppID、App Secret、Encrypt Key 或 Verification Token 发生变动时，须在简道云同步修改，否则集成会中断。

单击简道云右上角头像，进入「企业管理>企业信息」。在授权信息处单击「修改绑定」，填入新的参数并保存。