You need to enable JavaScript to run this app.
导航
飞连
  • 文档首页
    • /飞连/管理员指南/身份管理/账号配置/配置第三方数据源/飞书组织架构导入与第三方登录配置教程
飞书组织架构导入与第三方登录配置教程
最近更新时间：2025.04.14 18:04:26首次发布时间：2023.04.26 11:07:54
我的收藏
有用
有用
无用
无用

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

前提条件

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

操作指引

导入飞书组织架构（飞书作为身份源）

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

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

      注意

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

    4. 单击创建。
  3. 在企业自建应用页签，单击应用卡片进入应用详情页。
    Image
  4. 开通应用权限。
    1. 在左侧导航栏，单击权限管理。
    2. 在权限管理页面单击开通权限。
    3. 分别在应用身份权限 tenant_access_token 页签、用户身份权限 user_access_token 页签，选择以下权限。

      说明

      如果权限同时存在于应用身份权限 tenant_access_token 页签和用户身份权限 user_access_token 页签，则两个页签内的权限都需要选择。

      • 更新通讯录
      • 获取部门基础信息
      • 获取部门组织架构信息
      • 获取角色权限
      • 获取用户基本信息
      • 获取用户组织架构信息
      • 获取用户邮箱信息
      • 获取用户受雇信息
      • 获取用户 user ID
      • （可选）通过手机号或邮箱获取用户 ID：如果需要在飞连管理后台配置飞书机器人接收消息通知，则需要开通此权限。
      • 获取用户手机号
      • 搜索用户
      • 获取通讯录基本信息
      • 获取通讯录部门组织架构信息
    4. 选择完成后，单击页面右下角的确认开通权限。
  5. 设置通讯录、飞书人事（企业版）范围。
    权限开通后，系统会提示您配置通讯录权限范围、飞书人事（企业版）权限范围，该范围即同步至飞连的组织架构范围。如果您已经返回了权限管理页面，也可根据以下操作步骤配置权限范围。
    1. 在权限管理页面的权限列表的可访问的数据范围列，单击配置。
      Image
    2. 在应用身份权限可访问的数据范围界面，依次单击通讯录、飞书人事（企业版）的权限可访问的数据范围右侧的配置，配置各自可访问的数据范围。
      • 通讯录数据范围：可选与应用的可用范围一致、部分成员或全部成员权限范围，并单击保存。
        其中，应用的可用范围在后续发布应用步骤进行配置。
      • 飞书人事（企业版）：可选择全部、按条件筛选权限范围，并单击保存。
  6. 获取应用凭证。
    1. 在左侧导航栏，单击凭证与基础信息。
    2. 保存应用凭证的 App ID 和 App Secret。
      Image
  7. （可选）配置事件订阅。

    说明

    在飞连管理后台进行数据同步时，若需选择实时同步方式，则需要为应用配置事件订阅。

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

      注意

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

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

  1. 登录飞连管理后台。

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

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

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

  5. 在导入配置页面的数据源区域，完成以下配置，并单击下一步。

    • 将步骤一：在飞书开放平台创建企业自建应用中已保存的飞书应用凭证配置在 App ID 和 App Secret 字段。
    • Lark Host 选填，不填写默认为飞书开放平台域名 https://open.feishu.cn。如果选择的是海外 Lark，则默认为 Lark 开放平台域名 https://open.larksuite.com。
    • 在单位字段选择将该数据源同步至哪个单位。
      填写字段值后，单击第三方权限探测区域的开始检测，以帮助您有效检查是否已配置好第三方平台的权限，避免在配置完成后无法正常使用导入功能。

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

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

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

    同步方式

    说明

    操作

    策略

    手动同步

    在配置好数据源后，由人工主动触发数据同步操作。适用于企业管理员配置完成后，当下不想立即执行同步任务，待调试准备完成后，再进行手动同步的工作。

    选择手动同步，后续在数据接入列表中，手动开始导入组织架构数据。

    手动全量同步

    自动同步

    指定时间同步第三方数据源。适用于企业需要在固定时间完成数据同步的场景。

    选择自动同步，并选择导入模式，支持设置每隔多少分钟或小时，或者设置每天固定时间点导入组织架构。

    定时全量同步

    实时同步

    细粒度的同步方式，实时同步会根据组织机构或者人员实时变化的信息，进行差量同步，实时同步的特点是同步速度快、响应及时、无需排队等待。适用于企业员工每日有较大的员工、部门数据信息调整，需要在飞连侧及时获取到变更情况。

    选择实时同步，并填写步骤一：在飞书开放平台创建企业自建应用中已获取到的 Encrypt_key 和 Verification_Token 字段值。

    增量同步（仅同步变更的部门与员工信息）

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

    说明

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

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

    • 同步配置页签：查看基础信息（包含数据源 ID）、同步机制、同步范围信息。

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

      筛选条件

      说明

      变更动作

      可选全部、创建、更新以及删除，仅支持单选：

      • 全部：包含所有变更动作的同步任务。
      • 创建：代表创建了新的同步任务。
      • 更新：代表更新了已有的同步任务。
      • 删除：代表上游数据源删除数据时，同步删除了飞连中的数据。

      同步状态

      可选全部、成功、失败以及忽略，仅支持单选：

      • 全部：包含所有同步状态的同步任务。
      • 成功：代表同步成功的同步任务。
      • 失败：代表同步失败的同步任务。
      • 忽略：代表由于各种原因不入库的情况，例如全量同步任务发现已有实时任务将新数据入库时，飞连选择忽略这些数据，不将其入库。

      搜索部门/员工

      根据同步数据中包含的部门或员工名称进行筛选。

配置飞书第三方登录（飞书作为认证源）

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

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

      注意

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

    4. 单击创建。
  3. 在企业自建应用页签，单击应用卡片进入应用详情页。
    Image
  4. 开通应用权限。
    1. 在左侧导航栏，单击权限管理。
    2. 在 API 权限页签下的权限配置区域左侧，单击通讯录。
    3. 勾选以下权限，单击右上角的批量开通。
      • 更新通讯录
      • 获取部门基础信息
      • 获取部门组织架构信息
      • 获取角色权限
      • 获取用户基本信息
      • 获取用户组织架构信息
      • 获取用户邮箱信息
      • 获取用户受雇信息
      • 获取用户 user ID
      • （可选）通过手机号或邮箱获取用户 ID：如果需要在飞连管理后台配置飞书机器人接收消息通知，则需要开通此权限。
      • 获取用户手机号
      • 搜索用户
      • 获取通讯录基本信息
      • 获取通讯录部门组织架构信息
  5. 设置通讯录、飞书人事（企业版）范围。
    权限开通后，系统会提示您配置通讯录权限范围、飞书人事（企业版）权限范围，该范围即同步至飞连的组织架构范围。如果您已经返回了权限管理页面，也可根据以下操作步骤配置权限范围。
    1. 在权限管理页面的权限列表的可访问的数据范围列，单击配置。
      Image
    2. 在应用身份权限可访问的数据范围界面，依次单击通讯录、飞书人事（企业版）的权限可访问的数据范围右侧的配置，配置各自可访问的数据范围。
      • 通讯录数据范围：可选与应用的可用范围一致、部分成员或全部成员权限范围，并单击保存。
        其中，应用的可用范围在后续发布应用步骤进行配置。
      • 飞书人事（企业版）：可选择全部、按条件筛选权限范围，并单击保存。
  6. 配置网页。
    1. 在左侧导航栏，单击添加应用能力。
    2. 在按能力添加页签的网页应用卡片，单击添加。
      Image
    3. 在网页应用页面，配置桌面端主页和移动端主页，并单击保存。
      Image
      将桌面端主页、移动端主页填写为 https://{飞连门户域名}。

      注意

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

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

      注意

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

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

  1. 登录飞连管理后台。
  2. 在左侧导航栏，选择账号配置。
  3. 单击认证源管理页签，单击右上角添加认证源。
    Image
  4. 在选择认证源对话框中，单击飞书卡片。
  5. 参考界面提示配置参数，关键参数说明如下，完成配置后，单击确定。

    • 基本信息
      Image

      配置项

      必填

      说明

      登录显示图标

      是

      登录界面按钮上显示的身份源图标，单击重新上传可上传自定义显示图标。

      登录简称

      是

      显示在登录界面的按钮下方的名称，例如飞书快捷登录。

      • 点击输入框下方的示例了解展示效果。
      • 点击输入框右侧的图标可设置多语种简称。

      唯一标志

      不涉及

      登录源唯一标识，用于区分不同登录认证的租户，由小写字母、数字以及 - 组成，长度小于 32 位字符。由飞连默认提供，不可修改。

      单位

      是

      请选择该认证源适用的单位。设置后，该单位的员工可通过此登录方式进行认证。

      描述

      否

      认证源描述，非客户端展示字段，仅用于管理后台备注说明，长度小于 40 位字符。

      登录认证位置

      是

      请选择该登录认证方式适用的飞连客户端类型，默认飞连手机端软件、桌面端软件或门户网站均可使用该登录认证方式。

    • 认证信息
      Image

      配置项

      必填

      说明

      App ID

      是

      填写已保存的飞书应用凭证 App ID。您可以进入飞书开放平台的应用详情中的凭证与基础信息页面获取 App ID。

      App Secret

      是

      填写已保存的飞书应用凭证 App Secret。您可以进入飞书开放平台的应用详情中的凭证与基础信息页面获取 App Secret。

      飞连私有化部署版本

      否

      如果您使用的是飞连私有化版本，则需要开启此开关，开启后，您必须配置飞书私有化部署地址。

    • 高级配置
      Image

      配置项

      必填

      说明

      属性映射策略

      是

      将第三方登录认证源的用户信息直接映射为飞连的用户信息，即在登录过程中建立第三方与飞连用户之间的对应关系：

      • 调整字段映射关系：左侧飞书字段是指飞书内设置的用户字段。右侧飞连字段是指需要配置映射到飞连的用户字段。
      • 开启登录自动更新：如果在对应映射字段后勾选了开启，表示在进行登录时，如果匹配到系统中存在的用户，会用本次登录时的用户属性对系统中的用户属性进行更新。
      • 删除：删除当前映射策略。
      • 添加：如果飞连默认提供的字段不能满足映射需求，可单击添加，手动添加字段映射关系。
      • 添加扩展字段：如果当前字段不能满足映射策略，可单击添加扩展字段，填写说明如下：
        • 字段 Key：定义字段的唯一值。
        • 字段名称：设置字段的显示名称。
        • 字段描述：填写字段的说明。

      唯一标识优先级

      是

      通过拖拽设置匹配标识的优先级，飞连将按照优先级顺序匹配上游唯一标识。如果当前标识不能满足需求，可单击添加，手动添加标识。

      登录未匹配到员工时，选择处置方式

      否

      企业成员登录飞连时，未在飞连组织架构匹配到用户时，将提供自动创建账号服务，可选：

      • 自动创建员工账号：开启后，登录未匹配到员工时，将自动创建员工账号，将员工关联至指定部门。
      • 员工登录失败，将不会创建账号：开启后，登录未匹配到员工时，将不创建账号。

配置效果

  • 登录飞连管理后台时，在更多登录方式区域选择飞书图标。
    Image
  • 以在 macOS 中登录飞连客户端为例，打开飞连客户端，用户会在更多登录方式区域看到飞书图标。
    Image

常见问题

身份源是什么？飞连身份源同步能做什么？

身份源存储了所有部门、员工的信息，且是最根本、可信的一个用户目录。通过飞连身份源同步，企业无需在飞连在搭建重复的员工账号身份体系，仅需对接上游数据源，即可实现上游同步变更，飞连及时获取并联动变更。例如：上游入职新成员时，飞连自动授予入职成员相应权限。

飞书支持版本有哪些？

支持飞书、Lark。如果是飞书私有化版本请联系飞连供应商提供支持。

是否支持飞书的角色、用户组？

仅支持同步飞书角色，暂不支持同步用户组。