飞书 SSO

配置飞书 SSO（单点登录）后，成员可以使用飞书身份进入千问办公-旗舰版。配置需要在两个后台完成：在千问办公填写应用凭证并取得回调链接，再到同一个飞书应用中登记该链接、开通权限并完成应用发布。

开始前准备

请准备飞书企业自建应用，以及飞书应用和千问办公两边的管理权限。应用凭证、重定向 URL、权限和成员可用范围必须属于同一个应用。

准备项	从哪里取得	用途
App ID、App Secret	飞书开放平台 → 凭证与基础信息	标识应用并访问飞书接口
`contact:user.employee_id:readonly`	权限管理	读取默认身份标识 `user_id`
`contact:user.email:readonly`	权限管理，按需申请	读取成员邮箱
`contact:user.phone:readonly`	权限管理，按需申请	读取成员手机号
重定向 URL	千问办公的飞书认证源配置	登录完成后返回千问办公

在飞书创建并授权应用

同一应用兼作通讯录同步时，还需按“飞书用户同步”配置通讯录读取权限。

管理后台：飞书应用凭证、回调链接和字段关联设置。

新建飞书认证源时，页面默认使用以下字段：

保留「第三方用户 ID」和「用户姓名」两项必填映射。
邮箱、手机号、工号、账号中至少映射一项。自动创建用户时，成员实际返回的数据中也必须至少有一项非空。
来源字段可在页面提供的选项中调整；右侧的千问办公目标字段固定。修改前先确认实际返回字段，并让 SSO 与用户同步使用同一成员标识。
如果飞书用户同步也在使用，让登录侧 user.user_id 与同步侧 user_id 对应同一个成员。不要把 user_id、open_id 和 union_id 当成同一个字段。

点击【保存配置】。配置完整后即可回到列表启用认证源。
如需排查 App ID 和 App Secret 是否可用，可以点击【测试连接】。该操作只检查服务端能否取得飞书访问令牌，不检查重定向 URL、权限、成员范围、字段值或完整登录，因此不是启用前置条件。
在认证源列表中打开飞书的「启用状态」。同一企业一次只能启用一个 SSO 认证源。
在「身份认证-登录方式」菜单下，开启「SSO 登录」。
请一名普通成员从企业登录入口完成飞书登录，确认能够返回千问办公，并核对企业、姓名、部门和席位。

现象	处理方法
飞书提示重定向地址不合法	重新复制千问办公的完整回调链接，检查飞书安全设置中的保存值
应用创建者能登录，普通成员不能	检查应用可用范围、权限生效版本以及目标成员所属企业
登录后提示找不到用户	核对 `user.user_id` 与千问办公用户的第三方 ID；确认用户已存在或已开启自动创建
自动创建失败	确认已选择默认部门，并且邮箱、手机号、工号、账号至少有一项映射且实际返回非空
姓名正常但邮箱为空	检查飞书应用是否添加 `contact:user.email:readonly`权限、应用是否已重新发布，以及成员邮箱资料
提示暂时无法登录；SSO 创建千问办公账户失败，请联系管理员。	请到管理后台-身份认证-自动创建用户查看失败原因： 1、必要身份字段缺失；检查飞书管理后台成员资料中邮箱、手机号、工号字段必须至少有一项非空。 2、邮箱域名未验证；检查管理后台-身份认证-可信邮箱域名与飞书管理后台成员资料中邮箱域名是否一致

SSO 只通过三方 ID 查找未删除用户。三方 ID 只有已删除记录时，系统不会恢复旧 QID：自动创建关闭时登录失败；开启且本次返回的账号、邮箱、手机号和工号没有冲突时，系统按当前资料、默认部门和席位策略创建新用户和新 QID。旧角色、密码、席位和部门不会继承，旧历史仍保留。完整规则见身份认证。