飞连支持企业将第三方平台的组织架构信息导入飞连，并支持配置第三方登录飞连。本文主要介绍如何在飞连管理后台导入飞书组织架构，以及如何配置飞书第三方登录飞连。

已在飞书开放平台完成注册，且在飞书管理后台拥有完善的企业组织体系。

• 如需把飞书组织架构导入飞连，请参见导入飞书组织架构。
• 如需配置飞书第三方登录飞连，请参见配置飞书第三方登录。

步骤一：在飞书开放平台创建企业自建应用

1. 使用企业的飞书管理账号登录飞书开放平台。
2. 创建企业自建应用。
   1. 在飞书开放平台首页右上角，单击开发者后台。
   2. 在企业自建应用页签，单击创建企业自建应用。
   3. 在创建企业自建应用对话框，设置应用名称、应用描述和应用图标。

      注意

      必须上传应用图标，否则无法发布应用。

   4. 单击创建。
3. 在企业自建应用页签，单击应用卡片进入应用详情页。
   
4. 设置通讯录范围。
   1. 在左侧导航栏，单击权限管理。
   2. 在数据权限页签下的通讯录权限范围，单击配置。
   3. 在配置权限范围对话框，设置权限范围，并单击确认。
      可选与应用的可用范围一致、部分成员或全部成员，单击确认后，通讯录权限范围即同步至飞连的组织架构范围。
5. 开通应用权限。
   1. 在左侧导航栏，单击权限管理。
   2. 在 API 权限页签下的权限配置区域左侧，单击通讯录。
   3. 勾选以下权限，单击右上角的批量开通。
      • 更新通讯录
      • 获取部门基础信息
      • 获取部门组织架构信息
      • 获取角色权限
      • 获取用户基本信息
      • 获取用户组织架构信息
      • 获取用户邮箱信息
      • 获取用户受雇信息
      • 获取用户 user ID
      • （可选）通过手机号或邮箱获取用户 ID：如果需要在飞连管理后台配置飞书机器人接收消息通知，则需要开通此权限。
      • 获取用户手机号
      • 搜索用户
      • 获取通讯录基本信息
      • 获取通讯录部门组织架构信息
6. 获取应用凭证。
   1. 在左侧导航栏，单击凭证与基础信息。
   2. 保存应用凭证的 App ID 和 App Secret。
      
7. （可选）配置事件订阅。

   说明

   仅当选择实时同步方式时，需要配置事件订阅。

   当飞书组织架构的数据发生变更时，飞连为企业提供三种同步方式选择，包括手动同步、自动同步和实时同步。
   • 手动同步：在配置好数据源后，由人工主动触发数据同步操作。适用于企业管理员配置完成后，当下不想立即执行同步任务，待调试准备完成后，再进行手动同步的工作。
   • 自动同步（推荐）：指定时间同步第三方数据源。适用于企业需要在固定时间完成数据同步的场景。
   • 实时同步（推荐）：根据组织机构或者人员实时变化的信息，进行差量同步，实时同步的特点是同步速度快、响应及时、无需排队等待。适用于企业员工每日有较大的员工、部门数据信息调整，需要在飞连侧及时获取到变更情况。
     配置步骤如下：
   1. 在左侧导航栏，单击事件订阅。
   2. 在事件订阅页面，选择单击配置订阅方式后的编辑图标。
   3. 填写请求地址，地址格式为 http://{飞连门户域名}/api/v1/sync2/webhook/events/{占位符} 。
      

      注意

      • {飞连门户域名}需要替换为实际的飞连门户域名。
      • {占位符}需要替换为飞连管理后台对应飞书数据源的数据源 ID。
        
   4. 单击添加事件，添加的事件包括：contact.user.created_v3、contact.user.updated_v3、contact.user.deleted_v3、contact.department.created_v3、contact.department.updated_v3、contact.department.deleted_v3。
   5. 在事件与回调的加密策略页面，复制 Encrypt_key 与 Verification_Token 的信息至飞连实时同步配置项中。
      
8. 发布应用。
   1. 在左侧导航栏，选择版本管理与发布。
   2. 在页面右上角单击创建版本。
   3. 在版本详情页面，完成以下配置，并单击保存。
      • 应用版本号和更新说明：自定义设置即可。建议应用版本号与当前部署的飞连版本一致，便于维护。
      • 可用范围：指定能够使用该应用的员工范围。如果企业全员均需使用飞书第三方登录飞连，则选择所有员工。
   4. 单击保存，然后在版本详情页面右上角，单击申请线上发布。

步骤二：在飞连管理后台进行数据同步

1. 登录飞连管理后台。

2. 在左侧导航栏，选择账号配置。

3. 在账号配置页面的数据源同步页签，单击添加数据源。
   

4. 在选择数据源对话框的上游同步页签下，单击飞书，并单击创建。

5. 在导入配置页面的数据源区域，将步骤一：在飞书开放平台创建企业自建应用中已保存的飞书应用凭证配置在 App ID 和 App Secret 字段，在单位字段选择将该数据源同步至哪个单位，单击下一步。
   填写字段值后，单击第三方权限探测区域的开始检测，以帮助您有效检查是否已配置好第三方平台的权限，避免在配置完成后无法正常使用导入功能。

6. 在数据对象区域，完成以下配置，并单击下一步。

   1. 在选择部门与成员区域，选择同步对象。
      被选择的同步对象会被导入飞连管理后台。
   2. 在同步字段映射区域，设置第三方与飞连的字段映射关系。
      同步字段映射用于企业将第三方的成员信息中的字段映射到飞连内，其中，手机号和邮箱用于匹配用户唯一账号关系，暂不支持删除有关手机号或邮箱的字段映射关系。
      在同步字段映射区域，单击编辑，可手动调整字段映射关系，左侧第三方字段是指第三方平台内设置的用户字段。右侧飞连字段是指第三方平台映射到飞连的用户字段。字段配置说明如下：
      • 在飞连字段列，第三方 ID（用户 ID）、手机号（手机号码）、邮箱（员工邮箱）字段不允许修改与删除，用于匹配用户唯一账号关系。
      • 如果飞连默认提供的字段不能满足映射需求，可单击添加映射，手动添加字段映射关系。
        
        添加映射时，除了选择飞连提供的默认字段，还支持手动添加扩展字段。
        • 第三方字段中添加扩展字段方式如下图所示。
          
        • 飞连字段中添加扩展字段方式如下图所示，扩展字段填写说明如下：
          
          • 字段 Key：定义字段唯一值。
          • 字段名称：字段的显示名称。
          • 字段描述：字段的说明。
          • 字段类型：可选字符串、数字、布尔值、表达式、枚举值。
          • 高级配置：可选必填、唯一、编辑。
            在第三方字段和飞连字段列名右侧，单击设置图标，可以统一管理扩展字段（包括添加、编辑、删除操作）。
            

7. 在导入模式区域，选择导入模式，并单击完成配置。
   当飞书内组织架构数据发生变更时，飞连为您提供了三种同步数据的方式可选，包括手动同步、自动同步和实时同步。

   同步方式	说明	操作	策略
   手动同步	在配置好数据源后，由人工主动触发数据同步操作。适用于企业管理员配置完成后，当下不想立即执行同步任务，待调试准备完成后，再进行手动同步的工作。	选择手动同步，后续在数据接入列表中，手动开始导入组织架构数据。	手动全量同步
   自动同步	指定时间同步第三方数据源。适用于企业需要在固定时间完成数据同步的场景。	选择自动同步，并选择导入模式，支持设置每隔多少分钟或小时，或者设置每天固定时间点导入组织架构。	定时全量同步
   实时同步	细粒度的同步方式，实时同步会根据组织机构或者人员实时变化的信息，进行差量同步，实时同步的特点是同步速度快、响应及时、无需排队等待。适用于企业员工每日有较大的员工、部门数据信息调整，需要在飞连侧及时获取到变更情况。	选择实时同步，并填写步骤一：在飞书开放平台创建企业自建应用中已获取到的 Encrypt_key 和 Verification_Token 字段值。	增量同步（仅同步变更的部门与员工信息）

8. 在数据源同步页签的列表中，找到已添加的数据源配置，打开生效开关。
   打开生效开关后，该数据同步配置才正式生效，后续按照设置的同步方式进行数据同步。

   说明

   如果同步方式设置的手动同步，则打开生效开关后，可根据实际需要手动单击开始同步。

   
   此外，单击飞书数据同步，支持查看以下信息：

   • 同步配置页签：查看基础信息、同步机制、同步范围信息。

   • 同步任务页签：查看历史同步记录。您可以通过以下三个筛选条件，筛选出目标同步任务。
     在同步数据详细信息的操作列，单击详情，可查看该信息上游同步至飞连数据源的信息对比。对比同步前后的信息内容，可帮助您进行日志审计或排查用户数据问题。

     筛选条件	说明
     变更动作	可选全部、创建、更新以及删除，仅支持单选： 全部：包含所有变更动作的同步任务。 创建：代表创建了新的同步任务。 更新：代表更新了已有的同步任务。 删除：代表上游数据源删除数据时，同步删除了飞连中的数据。
     同步状态	可选全部、成功、失败以及忽略，仅支持单选： 全部：包含所有同步状态的同步任务。 成功：代表同步成功的同步任务。 失败：代表同步失败的同步任务。 忽略：代表由于各种原因不入库的情况，例如全量同步任务发现已有实时任务将新数据入库时，飞连选择忽略这些数据，不将其入库。
     搜索部门/员工	根据同步数据中包含的部门或员工名称进行筛选。

步骤一：在飞书开放平台发布应用

1. 使用企业管理员账号登录飞书开放平台。
2. 创建企业自建应用。
   1. 在飞书开放平台首页右上角，单击开发者后台。
   2. 在企业自建应用页签，单击创建企业自建应用。
   3. 在创建企业自建应用对话框，设置应用名称、应用描述和应用图标。

      注意

      必须上传应用图标，否则无法发布应用。

   4. 单击创建。
3. 在企业自建应用页签，单击应用卡片进入应用详情页。
   
4. 设置通讯录范围。
   1. 在左侧导航栏，单击权限管理。
   2. 在数据权限页签下的通讯录权限范围，单击配置。
   3. 在配置权限范围对话框，设置权限范围，并单击确认。
      可选与应用的可用范围一致、部分成员或全部成员，单击确认后，通讯录权限范围即同步至飞连的组织架构范围。
5. 开通应用权限。
   1. 在左侧导航栏，单击权限管理。
   2. 在 API 权限页签下的权限配置区域左侧，单击通讯录。
   3. 勾选以下权限，单击右上角的批量开通。
      • 更新通讯录
      • 获取部门基础信息
      • 获取部门组织架构信息
      • 获取角色权限
      • 获取用户基本信息
      • 获取用户组织架构信息
      • 获取用户邮箱信息
      • 获取用户受雇信息
      • 获取用户 user ID
      • （可选）通过手机号或邮箱获取用户 ID：如果需要在飞连管理后台配置飞书机器人接收消息通知，则需要开通此权限。
      • 获取用户手机号
      • 搜索用户
      • 获取通讯录基本信息
      • 获取通讯录部门组织架构信息
6. 配置网页。
   1. 在左侧导航栏，单击添加应用能力。
   2. 在按能力添加页签的网页应用卡片，单击添加。
      
   3. 在网页应用页面，配置桌面端主页和移动端主页，并单击保存。
      
      桌面端主页请填写 https://{飞连门户域名}:{端口}。
      移动端主页请根据需要添加以下 URL：
      • 若只需要免登录访问飞连，无需查看飞连 OTP 口令，请配置：https://{飞连门户域名}:{端口}
      • 若需要查看飞连 OTP 口令，请配置：https://{飞连门户域名}:{端口}/multiple-pages/third-otp.html

      注意

      {飞连门户域名} 是指飞连门户网站的域名，而不是飞连管理后台的域名，请确保填写正确。

7. 配置安全设置。
   1. 在左侧导航栏，单击安全设置。
   2. 在重定向 URL中，添加以下 URL。
      
      • https://{飞连门户域名}:{端口}/multiple-pages/third-login.html
      • https://{飞连门户域名}:{端口}/api/tpslogin/callback/lark
      • 飞书内免登录访问飞连，请配置：https://{飞连门户域名}:{端口}/login
      • 查看飞连 OTP 口令，请配置：https://{飞连门户域名}:{端口}/multiple-pages/third-otp.html

      注意

      • 实现 App 内免登录访问飞连系统后，无需再进行手动登录，在第三方 IM 中可查看飞连 OTP 口令。
      • {飞连门户域名} 是指飞连门户网站的域名，而不是飞连管理后台的域名，请确保填写正确。
8. 获取应用凭证。
   1. 在左侧导航栏，单击凭证与基础信息。
   2. 保存应用凭证的 App ID 和 App Secret。
      
9. 发布应用。
   1. 在左侧导航栏，选择版本管理与发布。
   2. 在页面右上角单击创建版本。
   3. 在版本详情页面，完成以下配置，并单击保存。
      • 应用版本号和更新说明：自定义设置即可。
      • 可用范围：指定能够使用该应用的员工范围。如果企业全员均需使用飞书第三方登录飞连，则选择所有员工。
   4. 单击保存，然后在版本详情页面右上角，单击申请线上发布。

步骤二：在飞连管理后台配置飞书第三方登录

1. 登录飞连管理后台。

2. 在左侧导航栏，选择账号配置。

3. 单击认证源管理页签，单击右上角添加认证源。

4. 在选择认证源对话框中，单击飞书卡片。

5. 参考界面提示配置参数，关键参数说明如下，完成配置后，单击确定。

   模块	配置项	必填	说明
   基本信息	登录显示图标	是	登录界面按钮上显示的身份源图标，单击重新上传可上传自定义显示图标。
   	登录简称（中文）	是	显示在登录界面的按钮下方的名称，例如飞书快捷登录，点击输入框下方的示例了解展示效果。
   	登录简称（英文）	是	显示在登录界面的按钮下方的名称。
   	唯一标志	不涉及	登录源唯一标识，用于区分不同登录认证的租户，由小写字母、数字以及 - 组成，长度小于 32 位字符。由飞连默认提供，不可修改。
   	单位	是	请选择该认证源适用的单位。设置后，该单位的员工可通过此登录方式进行认证。
   	描述	否	认证源描述，非客户端展示字段，仅用于管理后台备注说明，长度小于 40 位字符。
   	登录认证位置	是	请选择该登录认证方式适用的飞连客户端类型，默认飞连手机端软件、桌面端软件或门户网站均可使用该登录认证方式。
   认证信息	App ID	是	填写已保存的飞书应用凭证 App ID。您可以进入飞书开放平台的应用详情中的凭证与基础信息页面获取 App ID。
   	App Secret	是	填写已保存的飞书应用凭证 App Secret。您可以进入飞书开放平台的应用详情中的凭证与基础信息页面获取 App Secret。
   	飞连私有化部署版本	否	如果您使用的是飞连私有化版本，则需要开启此开关，开启后，您必须配置飞书私有化部署地址。
   高级配置	属性映射策略	是	将第三方登录认证源的用户信息直接映射为飞连的用户信息，即在登录过程中建立第三方与飞连用户之间的对应关系： 调整字段映射关系：左侧飞书字段是指飞书内设置的用户字段。右侧飞连字段是指需要配置映射到飞连的用户字段。 开启登录自动更新：如果在对应映射字段后勾选了开启，表示在进行登录时，如果匹配到系统中存在的用户，会用本次登录时的用户属性对系统中的用户属性进行更新。 删除：删除当前映射策略。 添加：如果飞连默认提供的字段不能满足映射需求，可单击添加，手动添加字段映射关系。 添加扩展字段：如果当前字段不能满足映射策略，可单击添加扩展字段，填写说明如下： 字段 Key：定义字段的唯一值。 字段名称：设置字段的显示名称。 字段描述：填写字段的说明。
   	唯一标识优先级	是	通过拖拽设置匹配标识的优先级，飞连将按照优先级顺序匹配上游唯一标识。如果当前标识不能满足需求，可单击添加，手动添加标识。
   	登录未匹配到员工时，选择处置方式	否	企业成员登录飞连时，未在飞连组织架构匹配到用户时，将提供自动创建账号服务，可选： 自动创建员工账号：开启后，登录未匹配到员工时，将自动创建员工账号，将员工关联至指定部门。 员工登录失败，将不会创建账号：开启后，登录未匹配到员工时，将不创建账号。

配置效果

以在 macOS 中登录飞连客户端为例，打开飞连客户端，用户会在更多登录方式区域看到飞书图标。