飞书集成独享版

概述

功能简介

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

应用场景

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

前提条件

1. 准备独享版企业

1.1 注册独享版企业

飞书自建应用对接独享版，需要自行准备一个内置模式的独享版企业，用于与飞书对接。

1）如尚未创建企业

详情请参见：独享版创建内置模式企业

2）如已创建了企业

管理员登录独享版控制台，点击「企业管理」。

在企业列表中找到目标企业，确保该企业账号模式为「内置模式」。

1.2 获取独享版企业访问地址

管理员登录独享版控制台，点击「基础信息」，在「平台信息」处即可获取独享版企业访问地址。

请复制并保存，下文多处需要使用。

1.3 获取独享版域名

管理员登录独享版控制台，点击「基础信息」，在「SSL 证书信息」处即可获取独享版工程域名。

请复制并保存，下文需要使用。

1.4 获取独享版企业租户ID

1）访问独享版企业

企业创建者在浏览器中访问独享版企业并登录。

2）获取企业租户ID

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

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

2. 飞书侧创建应用

2.1 注册飞书企业

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

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

2.2 创建飞书自建应用

1）登录 飞书开发者后台

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

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

2.3 开通应用权限

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

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

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

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

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

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

2.4 配置初始重定向 URL

本节先填入一个可用的初始回调地址，使后续绑定流程可以跳转回独享版企业。

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

2）添加以下重定向URL，单击「添加」。

1.2节独享版企业访问地址/portal/tenant/1.4节独享版企业租户ID/admin/lark/cp/1/main/install_callback

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）在同一浏览器，分别使用独享版企业创建者账号登录 1.2 节的独享版企业访问地址，使用飞书管理员账号登录 飞书 。

2）访问飞书安装页面：

1.2节独享版企业访问地址/portal/tenant/1.4节独享版企业租户ID/admin/lark/cp/1/main/install

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

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

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

6）点击「完成」后自动跳转至独享版企业。

3.2 确认绑定成功

1）管理员登录 1.2 节的独享版企业地址，进入「管理后台 > 企业信息」页面。

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

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

4. 飞书侧完善应用配置

4.1 回写重定向 URL

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

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

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

3）添加以下重定向 URL：1.2节独享版企业访问地址/lark/corp/3.1节绑定成功后获取的企业 ID/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://1.3节获取的独享版域名

4.6 重新发布版本

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

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

2）填写应用基础信息：

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

5. 通讯录配置与同步

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

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

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

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

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

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

5.2 独享版企业同步飞书通讯录

管理员登录1.2节的独享版企业访问地址，单击「管理后台>内部组织」，单击「立即同步」，将飞书通讯录同步至独享版企业。

6. 完成绑定

完成上述步骤后，即完成了独享版企业与飞书的绑定，拥有可用性权限的成员可以在飞书中使用独享版。

成员登录方式请参考：飞书用户登录独享版

7. 注意事项

1）一个独享版企业只能绑定一个飞书企业，绑定前请确认目标飞书企业无误。

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

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

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

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