# 集成飞书

URL: https://docs.ones.cn/on-premises/7.33/product-manual/admin/account-integration/third-party-integration/feishu

## 1. 集成能力

| **序号** | **能力类型** | **描述** |
| --- | --- | --- |
| 1 | ONES 消息通知到飞书 | ONES 中产生的消息将通知到飞书，并且支持点击查看及编辑详情页面。 |
| 2 | 同步成员与组织架构到 ONES | 以飞书成员与组织架构作为数据源（Identity Provider），同步到 ONES 实现快速启用与统一账号管理。 |
| 3 | 通过飞书登录到 ONES | 通过飞书的账号验证服务，登录到已绑定的 ONES 中，实现安全快捷单点登录。 |

## 2. 功能入口

管理员可在系统「团队配置中心」（多团队下「组织管理」）>「账号集成」页面，点击「添加账号集成」并选择「飞书」进行添加集成配置。

![集成飞书](https://docs.ones.cn/assets/images/45bc00a4e71735e4fc7b-64cedd309dbfad25fc19e44b6253b8a9.png)

## 3. 配置步骤

### 3.1 添加飞书

#### 3.1.1 选择版本

根据实际业务需要，选择集成的版本：飞书（国内版）或 Lark（国际版）

![集成飞书](https://docs.ones.cn/assets/images/9d3979984ca92fc9-43f199bab5d4a91f7888ce601264f9ee.png)

#### 3.1.2 新建飞书 或 Lark应用

打开系统的配置页面，同时进入 [飞书开放平台](https://open.feishu.cn/app) 或 [Lark开放平台](https://open.larksuite.com/app/) ，点击「创建企业自建应用」

在添加应用能力中，①选择添加「机器人」（用于进行消息通知）②选择添加「网页应用」

![集成飞书](https://docs.ones.cn/assets/images/080243c818d2904d-f3a25c3bcbc7b163dba0468b7cca8bc6.png)

#### 3.1.2 配置应用主页与重定向 URL

- 配置应用主页
将系统后台的「桌面端/移动端主页」，复制至飞书 或 Lark 应用的「桌面端/移动端主页」中，保存生效

![集成飞书](https://docs.ones.cn/assets/images/cd901d9f4861439c-45b774fcbcce226ee5968f04b9023d4c.png)

- 配置重定向 URL
将系统后台的「绑定企业重定向 URL」与「登录重定向 URL」，复制至飞书 或 Lark 应用的「安全设置」>「重定向 URL」中

![集成飞书](https://docs.ones.cn/assets/images/130db2dd094540ee-c9ef8ff3d94e90b6391ffead8914502f.png)

#### 3.1.3 配置应用权限

在「权限管理」-「API 权限」中，开通获取以下权限

通讯录-获取用户基本信息

通讯录-获取用户邮箱信息

通讯录-获取用户 user ID

通讯录-获取通讯录基本信息

通讯录-获取部门基础信息

通讯录-获取通讯录部门组织架构信息

通讯录-获取用户组织架构信息

通讯录-获取用户组信息

消息与群组-读取用户发给机器人的单聊消息

消息与群组-以应用的身份发消息

应用信息-校验用户是否为应用管理员

应用信息-获取应用信息

应用信息-管理应用自身资源

在「权限管理」-「数据权限」中，通讯录权限范围选择配置「与应用的可用范围一致」

#### 3.1.4 发布应用版本，配置应用凭证信息至系统

进入「版本管理与发布」，创建版本，按需配置可见范围，保存并申请线上发布

![集成飞书](https://docs.ones.cn/assets/images/3cf94c2a5e4078f9-ff0395f4abfb499ff2577b1d69adfe9a.png)

将发布后的应用凭证复制粘贴至系统中

![集成飞书](https://docs.ones.cn/assets/images/5609d93e60d31110-75367d73385d38796d83c18663e1913e.png)

#### 3.1.5 选择账号绑定方式

「账号绑定方式」用于匹配飞书账号和ONES系统已有账号，具体规则可查看账号绑定方式。

![集成飞书](https://docs.ones.cn/assets/images/ae7f33d9fb297b134a3d-1ab83c75f9339144754d47ae068ad622.png)

#### 3.1.6 用户属性映射

用于设置从飞书同步的用户属性字段，以及飞书属性字段和系统属性字段的映射关系，目前系统支持同步的字段包含：用户名、邮箱、工号、公司、职位

*注意：需要保证用户的邮箱、工号是企业唯一的*

![集成飞书](https://docs.ones.cn/assets/images/f73f9964d3eb3def303f-e228331da5f854de8733ce9fead152c5.png)

查看飞书属性字段：进入「飞书开发平台」>「开发文档」>「 [服务端文档](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/get) 」，查看「通讯录 - 获取单个用户信息」中「响应体」提供的属性字段

**飞书属性字段参考**

| **字段名** | **描述** |
| --- | --- |
| name | 用户名 |
| email 或 enterprise_email | 邮箱 |
| employee_no | 工号 |
| job_title | 职位 |

注意确认企业分辨当前在飞书中使用的是「邮箱：email（通常是个人邮箱）」还是「企业邮箱：enterprise_email」

#### 3.1.7 保存集成配置

### 3.2 配置集成功能

添加集成后，进入【飞书详情】 可以选择需要启用集成功能。

![集成飞书](https://docs.ones.cn/assets/images/13ce9d26f8630adf8cf5-d2f729c9e9fb1814836b44d06b1f0b3c.png)

#### 3.2.1 启用「用户目录同步」

启用「用户目录同步」可以获取飞书"组织架构"的成员和部门。在【详情】 > 【用户目录同步】页面，点击「配置同步」进入【配置同步】页面，选择同步方式。

- 定时同步：每10分钟ONES系统会从飞书获取一次最新的成员和部门数据；
- 事件消息同步：当飞书组织架构数据发生变动时，ONES系统会从飞书获取一次最新的成员和部门数据。
如需开启「事件消息同步」，需先将ONES系统提供的Encrypt Key、Verification Token、请求网址 URL复制并粘贴到飞书自建应用中。

进入「事件与回调」，将Encrypt Key和Verification Token复制粘贴至「加密策略」中，将请求网址 URL复制并粘贴至「事件配置」>「配置订阅方式」>「将事件发送至开发者服务器」>「请求地址」中。

![集成飞书](https://docs.ones.cn/assets/images/66d02ea60d65d4187054-f77cf57e14c3cd1f904484b210424d30.png)

完成配置后，添加「用户和机器人的会话首次被创建」、「员工入职」、「员工离职」、「员工信息变化」、「部门新建」、「部门被删除」、「部门信息变化」和「接收消息」事件，并创建版本发布修改

![集成飞书](https://docs.ones.cn/assets/images/f4abc34a341e6d26ad22-971145d5f02ac9cf981420586de33602.png)

配置完成后，点击「启用」即可启用「用户目录同步」。

#### 3.2.2 启用「登录验证」

启用「登录验证」后，已绑定飞书账号的ONES用户（提示： [用户如何绑定第三方账号](https://docs.ones.cn/on-premises/7.33/product-manual/admin/account-integration/start-to-account-integration/account-binding/) ）通过飞书扫码登录ONES系统。在【飞书详情】>【登录验证】点击「启用」，即可开启登录验证。

启用「登录验证」后，系统登录页面将显示「飞书」登录入口，点击可以进入飞书扫码登录页面

，如下图

所示

。也可以通过「登录链接」直接打开飞书扫码登录页面。

![集成飞书](https://docs.ones.cn/assets/images/b379442506c2967df432-22366487fc2742eaebfe6aa4fa7b1e04.png)

启用「登录即时创建成员」后，新用户通过「飞书」登录到系统时，会自动创建账号并同步用户数据

*注意：在「多团队」模式下，需要选择新用户默认加入的团队*

#### 3.2.3 启用「消息通知」

启用「消息通知」可以允许用户在「飞书」接收系统消息通知，启用飞书消息通知前，需要先在飞书添加「机器人」

![集成飞书](https://docs.ones.cn/assets/images/9c2c687e8bbcf76b3f71-4cb6d308b7a520822b1f36c7b2bd325b.png)

启用机器人后，在【飞书详情】>【消息通知】点击「启用」，即可开启消息通知。

*注意：启用消息通知后，需要在「项目管理」、「知识库管理」等产品的配置中添加通知方式，具体可查看*[如何添加通知方式](https://docs.ones.cn/on-premises/7.33/product-manual/admin/account-integration/what-is-account-integration/notifications/)

![集成飞书](https://docs.ones.cn/assets/images/72d1de2f2957de6e05f0-aa60379f26ba5267afa0ac0b950b4f83.png)

### 3.3 移除集成

在【飞书详情】点击「移除集成」，在确认弹窗输入"移除飞书"即可移除集成，集成移除后，从飞书获取的部门和已激活邮箱的用户将会保留，未激活邮箱的用户将会被清除。