为 Verdent Team 配置飞书 SSO
了解飞书单点登录的工作方式，并为 Verdent Team 配置统一的企业身份登录
Verdent Team 支持通过飞书单点登录（SSO）验证团队成员身份。配置完成后，使用指定企业邮箱域名的成员登录 Verdent 时，可以通过企业的飞书账号完成身份验证。
飞书 SSO 可以帮助团队：
- 使用现有的企业身份体系登录 Verdent
- 减少成员维护独立登录凭证的需要
- 通过企业邮箱域名，将成员匹配到对应的 SSO 配置
- 由 Team Owner 在统一入口查看、启用、停用或更新登录配置
飞书 SSO 如何工作
Team Owner 需要先在飞书开放平台创建企业自建应用，再将应用凭证和企业邮箱域名添加到 Verdent Team。
配置启用后，成员使用企业邮箱登录 Verdent。Verdent 根据邮箱域名识别所属团队，引导成员前往飞书完成授权，并使用飞书返回的企业邮箱验证其身份。
开始之前
请准备以下信息和权限：
- 可创建企业自建应用的飞书企业管理员账号
- Verdent Team 的 Owner 权限
- 团队使用的企业邮箱域名，例如
yourcompany.com
完整配置通常需要约 5 分钟。
打开 Verdent Team 的 SSO 设置
- 登录 Verdent，并切换到需要配置的 Team。
- 在 Team 控制台中打开 Settings。
- 选择 SSO。
- 点击 Connect SSO，打开飞书 SSO 配置页面。
配置过程中需要在 Verdent 和飞书开放平台之间切换。建议保持两个页面同时打开。
配置飞书企业自建应用
创建企业自建应用
打开飞书开放平台，进入开发者后台，然后点击创建企业自建应用。填写应用名称并上传图标后，完成创建。
获取应用凭证
在应用后台打开凭证与基础信息，找到 App ID 和 App Secret。在 Verdent SSO 配置中，这两个值分别对应：
| 飞书应用凭证 | Verdent SSO 字段 |
|---|---|
| App ID | Client ID |
| App Secret | Client Secret |
App Secret 相当于应用密码，请勿分享或公开。如果你在飞书后台重置了 App Secret，需要同步更新 Verdent 中的 Client Secret。
添加重定向 URL
在飞书应用后台打开开发配置 → 安全设置，在重定向 URL 中添加：
https://login.verdent.ai/passport/sso/callback保存后立即生效。
地址必须逐字符一致：使用 https，结尾不添加 /，并确保前后没有空格。配置错误会导致飞书返回错误码 20029。
开通所需权限
在飞书应用后台打开开发配置 → 权限管理，为应用开通以下权限：
| 权限 | 权限标识 |
|---|---|
| 获取用户基本信息 | contact:user.base:readonly |
| 获取用户邮箱信息 | contact:user.email:readonly |
Verdent 使用这些权限读取成员姓名和企业邮箱，以完成账号识别和匹配。
发布应用
打开版本管理与发布，创建版本并提交发布。应用发布通过后，团队成员才能使用该应用完成飞书登录。
在 Verdent 中完成连接
返回 Verdent 的飞书 SSO 配置页面，填写以下内容：
| Verdent 字段 | 填写内容 |
|---|---|
Client ID | 飞书应用的 App ID |
Client Secret | 飞书应用的 App Secret |
Email domain | 团队使用的企业邮箱域名 |
你最多可以添加 5 个企业邮箱域名。Gmail 等公共邮箱域名不受支持。
保存配置后，在 SSO 配置卡片上确认飞书 SSO 已启用。如果暂时不希望成员使用该配置，可以关闭开关，而无需删除应用信息。
Verdent 保存配置时会校验 Client ID 和 Client Secret，但不会校验飞书后台的重定向 URL。因此，保存成功不代表重定向
URL 已正确配置。
成员如何使用飞书 SSO 登录
启用飞书 SSO 后，团队成员可以：
- 在 Verdent 登录页面输入已配置域名下的企业邮箱。
- 在 SSO 提示页面确认继续登录。
- 跳转至飞书完成身份授权。
- 授权成功后返回 Verdent。
如果成员输入的邮箱与飞书返回的企业邮箱不同，Verdent 会显示邮箱不一致提示。成员确认后，将使用飞书返回的邮箱完成身份验证。
验证配置
建议在向整个团队推广之前，先使用一名普通团队成员的账号完成测试：
- 确认该成员已加入 Verdent Team。
- 确认其飞书账号已绑定配置域名下的企业邮箱。
- 退出当前 Verdent 账号，并使用该企业邮箱重新登录。
- 完成飞书授权，确认能够返回 Verdent 并进入团队。
管理现有配置
Team Owner 可以随时在 Team → Settings → SSO 中：
- 查看当前连接状态和已绑定的邮箱域名
- 启用或停用飞书 SSO
- 更新 App ID、App Secret 或邮箱域名
- 在凭证失效后重新配置
- 删除不再使用的 SSO 配置
删除配置后，团队成员将无法再通过该飞书应用登录 Verdent。
常见问题
飞书提示错误码 20029：重定向 URL 有误
飞书应用中缺少重定向 URL，或配置的地址不完全一致。
返回开发配置 → 安全设置，确认已添加：
https://login.verdent.ai/passport/sso/callback检查协议、结尾斜杠和前后空格，确保地址逐字符一致。
Verdent 提示 Client ID 或 Client Secret 无效
返回飞书应用的凭证与基础信息页面，重新复制 App ID 和 App Secret。如果 App Secret 曾被重置，请在 Verdent 中填写最新值。
登录时提示应用不可用
登录后提示邮箱为空
该成员的飞书账号没有企业邮箱。请先在飞书通讯录中补充企业邮箱，然后重新登录。
成员没有进入飞书 SSO 流程
确认成员输入的邮箱属于 Verdent SSO 配置中绑定的企业邮箱域名，并检查配置卡片上的飞书 SSO 开关是否已启用。