你在使用第三方认证源登录飞连的过程中，遇到问题时可参考以下常见问题及解决方案。

如何配置钉钉作为数据源同步以及第三方授权登录？

具体操作，请参见钉钉组织架构导入与第三方登录配置说明。

如何配置飞书作为数据源同步以及第三方授权登录？

具体操作，请参见飞书组织架构导入与第三方登录配置教程。

配置了钉钉或者飞书作为第三方授权登录后，登录界面没有出现对应登录选项如何处理？

您需要登录飞连管理后台，在账号配置中，确认第三方授权登录配置是否选中了可用终端。

单成员开启二次认证时，是否只支持动态口令？

是的。目前二次认证默认为动态口令，单成员暂不支持使用短信验证码进行二次认证。

是否支持关闭账号密码登录方式，只使用第三方登录？

暂不支持关闭账号密码登录功能。目前仅支持配置登录方式显示的优先级，您可以在飞连管理后台的账号配置中设置。排序越靠左侧优先级越高，其中第一优先级为飞连的主登录方式，其他为次登录方式。
具体操作，请参见配置飞连账号体系和LDAP 组织架构导入与第三方登录配置教程。

使用代填插件登录飞连门户后仍提示未登录

解决方案如下：

1. 解压缩代填插件压缩包。
2. 手动导入代填插件。
3. 在浏览器的扩展程序中打开代填插件扩展程序，清空插件的缓存。
4. 刷新飞连门户页面。

通过钉钉登录飞连 iOS 客户端提示错误

问题现象
通过钉钉登录飞连 iOS 客户端提示错误，登录飞连 Android 客户端正常。
问题原因
在钉钉开放平台中没有配置网页应用功能，导致 iOS 扫码授权异常。
问题解决
参考如下步骤配置网页应用功能，具体请参见配置钉钉第三方登录。

1. 使用企业管理员账号登录钉钉开放平台，单击目标应用，进入应用详情页。
2. 在左侧导航栏单击应用能力 > 添加应用能力，单击网页应用卡片中的添加。
3. 在网页应用配置页面，配置应用首页地址为https://{飞连门户域名}:{端口}/，其中{飞连门户域名}:{端口} 需要替换为实际的飞连门户域名，而不是飞连管理后台域名。
4. 发布应用。

企业微信登录飞连提示授权出现问题

问题现象
用户通过企业微信登录飞连，提示授权出现问题，请重试：无法找到对应的用户。

在飞连管理后台的日志审计 > 员工活动日志中有登录登出的失败日志，但是无法查看到对应的用户姓名。
问题原因

• 企业微信用户未同步到本地。
• 在飞连添加认证源时，没有选择登录未匹配到员工时，选择处置方式为自动创建员工账号。

问题解决

1. 选择账号配置，单点认证源管理页签。
2. 在认证源列表单击对应的企业微信认证源右侧的编辑，在高级配置区域，配置登录未匹配到员工时，选择处置方式为自动创建员工账号。具体请参见企业微信组织架构导入与第三方登录配置说明。
   

通过飞书登录飞连，客户端没有飞书登录的图标或者提示无权限

问题现象
配置了飞书认证，但是输入企业识别码后没有飞书认证的图标或者认证提示没有权限。
问题解决

1. 检查单位管理配置
   • 若已启用“单位管理”功能（即存在主单位和子单位）。
     1. 登录飞连管理后台，导航至身份 > 单位管理，确认您希望配置的员工所属的子单位是否正确。
     2. 导航至 身份 > 账号配置 > 认证源管理。
     3. 在页面顶部的单位下拉列表中，务必选择对应的子单位。
     4. 检查在该子单位下，是否已成功添加并启用了“飞书认证”。如果没有，请为该子单位单独配置飞书认证源。
   • 若未启用“单位管理”功能（即仅存在主单位）。
     5. 请在身份 > 账号配置 > 认证源管理 页面，确认主单位下是否已成功添加并启用了“飞书认证”。
2. 检查应用的授权使用范围

   1. 获取 App ID

      • 复现问题，在浏览器提示“无权限”的页面，查看地址栏中的 URL。
      • 从 URL 参数中，找到并复制 app_id 的值。
        

   2. 检查应用可见范围

      1. 使用管理员账号登录您的飞书开放平台。
      2. 根据上一步获取的 app_id，找到对应的自建应用。
      3. 检查并确认当前遇到问题的员工，是否包含在您设置的“可用性状态”的部门或员工列表中。如果不在，请将其加入。

   3. 检查通讯录权限：

      • 在应用详情的权限管理页面，确保应用已申请了必要的通讯录读取权限，并且这些权限已被管理员审批通过。权限不足也可能导致无法获取用户信息，从而认证失败。

第三方外包转正的员工，如果其飞书上的外包账号（三方账号）被设置为“离职”，为什么会导致其在飞连中的正式员工账号状态也被错误地更新为“离职”？

原因分析
飞书认证默认使用“员工 ID”作为账号唯一标识。当通过飞书的“员工 ID”找不到用户时，飞连会降级使用手机号来匹配。由于外包和正式账号的手机号相同，导致了错误的身份关联。
解决方案

1. 进入飞连管理后台身份 > 账号配置 > 认证源管理。
2. 编辑飞书认证源。
3. 在高级配置 > 唯一标识优先级 处，将 “邮箱” 的匹配优先级提升至最高（高于手机号）。

由于外包和正式账号的邮箱通常不同，系统将能正确区分两个身份，避免状态被错误覆盖。

在飞书中添加了新部门，为什么没有自动同步到飞连？

原因分析
您在飞书应用市场中安装的“飞连同步”应用，其通讯录权限范围未包含这个新创建的部门。
解决方案

1. 以飞书管理员身份，登录飞书管理后台。
2. 导航至应用管理，找到并点击飞连同步应用。
3. 在应用可用范围处，点击配置，确保已勾选新建的部门。

保存设置后，飞连的下一次同步任务即可成功获取到新部门及其成员信息。

自定义动态口令最多可支持额外添加几个？

5 个。

在企业微信后台上传认证文件时，提示“域名所有权检验不通过”如何解决？

原因分析
通常是由于文件名不匹配（如下载时自动添加了后缀），或文件未正确上传至服务器 Web 根目录导致无法访问。
解决方案

1. 核对文件名
   检查上传的文件名是否与企微后台要求的完全一致。若文件名包含系统自动添加的后缀（如 file(1).txt），请重命名去除后缀后重新上传。
2. 验证文件访问
   在浏览器地址栏直接输入校验文件的完整 URL（例如 https://your-domain.com/文件名.txt）。
   • 若无法访问（404 Error）：说明文件未上传至 Web 服务器的根目录，请检查文件路径并重新部署。
   • 若可正常访问：确认文件内容无误后，返回企业微信后台再次点击“提交认证”。

配置飞书实时同步后，新增人员为何未触发同步？

原因分析
飞书应用的“事件订阅”配置中，未正确勾选“通讯录”相关的变更事件，导致飞连无法接收人员变动通知。
解决步骤

1. 登录飞书开放平台，进入用于集成飞连的企业自建应用。
2. 导航至事件订阅页面。
3. 检查并确保通讯录类别下的所有事件（如员工入职、离职、信息变更等）均已勾选并保存。

使用飞书登录飞连时提示“请求非法，请联系应用开发者”，如何处理？

原因分析
飞连后台配置的飞书应用凭证（App ID 或 App Secret）与飞书开放平台实际信息不一致。
解决步骤

1. 登录飞连管理后台，进入身份 > 账号配置 > 认证源管理。
2. 找到飞书认证源。
3. 点击编辑，核对并重新输入正确的 App ID 和 App Secret（请从飞书开发者平台复制，注意避免多余空格）。

如何导入 LarkSuite 或私有化飞书的组织架构？如何配置登录授权？

1. 导入组织架构
   在飞连后台添加数据源时，除填写 App ID 和 App Secret 外，还需正确配置 Lark Host 字段：
   • LarkSuite（海外版）： 填写 https://open.larksuite.com。
   • 私有化飞书： 填写您企业私有化部署的域名（例如 https://open.your-company.com）。
2. 授权第三方登录
   目前 LarkSuite 或私有化飞书的登录集成需要后台配置支持，请联系飞连技术支持团队协助开启。

飞书用户认证失败，提示请求服务器失败

问题现象
使用飞书认证登录时，在浏览器中授权成功并跳转回飞连客户端后，客户端界面提示“请求服务器错误，请重试（21020400）”。
排查步骤

1. 客户端初步诊断

   • 交叉验证：​请该用户在其他设备上登录，或请其他用户在此设备上登录，以排除个别设备或账号的问题。
   • 检查日志：​开启客户端调试模式并复现问题。导出日志，检查 callback 接口的调用是否存在超时或返回错误。
     

2. 服务端日志分析
   登录飞连 server 运维平台，导航至集群管理 > 服务列表 > 用户门户，查看服务日志。在日志中定位对应的 callback 接口请求，检查其响应耗时。如果耗时过长（例如，超过 10 秒），则可确认问题在于服务端处理缓慢。

3. 网络性能排查
   通过 SSH 登录到飞连 server 后台，执行以下命令，测试服务器对飞书开放平台域名的 DNS 解析性能：

   time nslookup open.feishu.cn
   

   关注命令输出的 real time 字段。如果此时间显著过长（例如，超过 2 秒），表明 DNS 解析存在严重性能问题，是导致接口响应缓慢的根本原因。

问题原因
飞连服务器所配置的 DNS 服务器，在解析飞书开放平台域名（open.feishu.cn）时存在严重延迟。这导致飞连服务端在处理认证回调时，因等待上游响应而耗时过长，最终超过了客户端的请求超时阈值，从而引发报错。
此问题在飞连客户端 3.0.20 及以上版本中更为常见，因为新版本客户端对回调接口的超时时间有更严格的控制。
解决方案
更换飞连服务器的 DNS 配置，指向一个更稳定、高效的 DNS 服务器。

飞书认证失败，提示 connection reset by peer

问题现象
在使用飞书认证登录时，在浏览器中扫码授权成功后，页面提示“抱歉...获取登录用户信息失败... (10110308)”，且包含“connection reset by peer”错误信息。
排查步骤

1. 错误定位
   错误信息“connection reset by peer”明确指向一个网络层面的问题。它表示飞连服务器与飞书开放平台之间的 TCP 连接，在数据传输过程中被对端（飞书服务器）或中间网络设备（如防火墙、路由器）强行关闭。

2. 网络连通性测试
   通过 SSH 登录到飞连服务器后台，执行以下命令，以验证服务器到飞书开放平台的基础网络连通性：

   # 测试ICMP连通性
   ping open.feishu.cn
   
   # 测试HTTPS端口连通性
   curl -v https://open.feishu.cn
   

   如果 ping 或 curl 命令失败，表明存在基础的网络访问控制问题。

3. 防火墙策略检查
   请与您的网络/安全管理员确认，企业出口防火墙的出向（Outbound）策略，是否已允许飞连服务器的 IP 地址访问 open.feishu.cn 的 443 (HTTPS) 端口。

问题原因
此问题最常见的原因是，企业网络出口的防火墙策略配置不当，导致飞连服务器发往飞书开放平台的网络请求被拦截或重置。
特别是在高可用（主备）部署的场景下，管理员可能只为集群的虚拟 IP (VIP) 配置了出网权限，而忽略了为每台服务器物理网卡的 IP 地址也配置相同的权限。当飞连服务器实际发起出向请求时，源 IP 为其物理 IP，若该 IP 未被防火墙放行，则连接将被重置。
解决方案
请检查并更新您的出口防火墙策略，确保飞连服务器能够正常访问飞书开放平台。

1. 确认飞连服务器的所有出网 IP 地址。
   • 在单机部署场景下，即为该服务器的物理网卡 IP。
   • 在高可用（主备）部署场景下，需要同时包含两台服务器各自的物理网卡 IP 以及集群的虚拟 IP (VIP)。
2. 在您的企业出口防火墙上，添加一条出向策略，允许上述所有IP地址访问目标域名 open.feishu.cn 的 TCP/443 端口。
3. 策略生效后，可返回服务器后台再次执行 curl -v https://open.feishu.cn 命令进行验证。如果命令能成功返回内容，问题即已解决。