# 为 Verdent Team 配置飞书 SSO (/zh-CN/docs/account-billing/configure-feishu-sso)

> 了解飞书单点登录的工作方式，并为 Verdent Team 配置统一的企业身份登录



Verdent Team 支持通过飞书单点登录（SSO）验证团队成员身份。配置完成后，使用指定企业邮箱域名的成员登录 Verdent 时，可以通过企业的飞书账号完成身份验证。

飞书 SSO 可以帮助团队：

* 使用现有的企业身份体系登录 Verdent
* 减少成员维护独立登录凭证的需要
* 通过企业邮箱域名，将成员匹配到对应的 SSO 配置
* 由 Team Owner 在统一入口查看、启用、停用或更新登录配置

<Note>
  本文面向 Verdent Team 的 Owner。只有 Team Owner 可以进入团队设置并管理 SSO。
</Note>

## 飞书 SSO 如何工作 [#飞书-sso-如何工作]

Team Owner 需要先在飞书开放平台创建企业自建应用，再将应用凭证和企业邮箱域名添加到 Verdent Team。

配置启用后，成员使用企业邮箱登录 Verdent。Verdent 根据邮箱域名识别所属团队，引导成员前往飞书完成授权，并使用飞书返回的企业邮箱验证其身份。

<Warning>
  成员必须在飞书通讯录中绑定企业邮箱。没有企业邮箱的成员无法通过飞书 SSO 登录。
</Warning>

## 开始之前 [#开始之前]

请准备以下信息和权限：

* 可创建企业自建应用的飞书企业管理员账号
* Verdent Team 的 Owner 权限
* 团队使用的企业邮箱域名，例如 `yourcompany.com`

完整配置通常需要约 5 分钟。

## 打开 Verdent Team 的 SSO 设置 [#打开-verdent-team-的-sso-设置]

1. 登录 Verdent，并切换到需要配置的 Team。
2. 在 Team 控制台中打开 **Settings**。
3. 选择 **SSO**。
4. 点击 **Connect SSO**，打开飞书 SSO 配置页面。

配置过程中需要在 Verdent 和飞书开放平台之间切换。建议保持两个页面同时打开。

## 配置飞书企业自建应用 [#配置飞书企业自建应用]

<Steps>
  <Step title="创建企业自建应用">
    打开[飞书开放平台](https://open.feishu.cn/app)，进入**开发者后台**，然后点击**创建企业自建应用**。填写应用名称并上传图标后，完成创建。
  </Step>

  <Step title="获取应用凭证">
    在应用后台打开**凭证与基础信息**，找到 App ID 和 App Secret。在 Verdent SSO 配置中，这两个值分别对应：

    | 飞书应用凭证         | Verdent SSO 字段  |
    | -------------- | --------------- |
    | **App ID**     | `Client ID`     |
    | **App Secret** | `Client Secret` |

    <Warning>
      App Secret 相当于应用密码，请勿分享或公开。如果你在飞书后台重置了 App Secret，需要同步更新 Verdent 中的 `Client Secret`。
    </Warning>
  </Step>

  <Step title="添加重定向 URL">
    在飞书应用后台打开**开发配置 → 安全设置**，在**重定向 URL** 中添加：

    ```text
    https://login.verdent.ai/passport/sso/callback
    ```

    保存后立即生效。

    <Warning>
      地址必须逐字符一致：使用 `https`，结尾不添加 `/`，并确保前后没有空格。配置错误会导致飞书返回错误码 `20029`。
    </Warning>
  </Step>

  <Step title="开通所需权限">
    在飞书应用后台打开**开发配置 → 权限管理**，为应用开通以下权限：

    | 权限       | 权限标识                          |
    | -------- | ----------------------------- |
    | 获取用户基本信息 | `contact:user.base:readonly`  |
    | 获取用户邮箱信息 | `contact:user.email:readonly` |

    Verdent 使用这些权限读取成员姓名和企业邮箱，以完成账号识别和匹配。
  </Step>

  <Step title="发布应用">
    打开**版本管理与发布**，创建版本并提交发布。应用发布通过后，团队成员才能使用该应用完成飞书登录。
  </Step>
</Steps>

## 在 Verdent 中完成连接 [#在-verdent-中完成连接]

返回 Verdent 的飞书 SSO 配置页面，填写以下内容：

| Verdent 字段      | 填写内容             |
| --------------- | ---------------- |
| `Client ID`     | 飞书应用的 App ID     |
| `Client Secret` | 飞书应用的 App Secret |
| `Email domain`  | 团队使用的企业邮箱域名      |

你最多可以添加 5 个企业邮箱域名。Gmail 等公共邮箱域名不受支持。

保存配置后，在 SSO 配置卡片上确认飞书 SSO 已启用。如果暂时不希望成员使用该配置，可以关闭开关，而无需删除应用信息。

<Note>
  Verdent 保存配置时会校验 `Client ID` 和 `Client Secret`，但不会校验飞书后台的重定向 URL。因此，保存成功不代表重定向
  URL 已正确配置。
</Note>

## 成员如何使用飞书 SSO 登录 [#成员如何使用飞书-sso-登录]

启用飞书 SSO 后，团队成员可以：

1. 在 Verdent 登录页面输入已配置域名下的企业邮箱。
2. 在 SSO 提示页面确认继续登录。
3. 跳转至飞书完成身份授权。
4. 授权成功后返回 Verdent。

如果成员输入的邮箱与飞书返回的企业邮箱不同，Verdent 会显示邮箱不一致提示。成员确认后，将使用飞书返回的邮箱完成身份验证。

## 验证配置 [#验证配置]

建议在向整个团队推广之前，先使用一名普通团队成员的账号完成测试：

1. 确认该成员已加入 Verdent Team。
2. 确认其飞书账号已绑定配置域名下的企业邮箱。
3. 退出当前 Verdent 账号，并使用该企业邮箱重新登录。
4. 完成飞书授权，确认能够返回 Verdent 并进入团队。

## 管理现有配置 [#管理现有配置]

Team Owner 可以随时在 **Team → Settings → SSO** 中：

* 查看当前连接状态和已绑定的邮箱域名
* 启用或停用飞书 SSO
* 更新 App ID、App Secret 或邮箱域名
* 在凭证失效后重新配置
* 删除不再使用的 SSO 配置

删除配置后，团队成员将无法再通过该飞书应用登录 Verdent。

## 常见问题 [#常见问题]

<AccordionGroup>
  <Accordion title="飞书提示错误码 20029：重定向 URL 有误">
    飞书应用中缺少重定向 URL，或配置的地址不完全一致。

    返回**开发配置 → 安全设置**，确认已添加：

    ```text
    https://login.verdent.ai/passport/sso/callback
    ```

    检查协议、结尾斜杠和前后空格，确保地址逐字符一致。
  </Accordion>

  <Accordion title="Verdent 提示 Client ID 或 Client Secret 无效">
    返回飞书应用的**凭证与基础信息**页面，重新复制 App ID 和 App Secret。如果 App Secret 曾被重置，请在 Verdent
    中填写最新值。
  </Accordion>

  <Accordion title="登录时提示应用不可用">
    确认飞书应用已在

    **版本管理与发布**

    中创建版本并完成发布。
  </Accordion>

  <Accordion title="登录后提示邮箱为空">
    该成员的飞书账号没有企业邮箱。请先在飞书通讯录中补充企业邮箱，然后重新登录。
  </Accordion>

  <Accordion title="成员没有进入飞书 SSO 流程">
    确认成员输入的邮箱属于 Verdent SSO 配置中绑定的企业邮箱域名，并检查配置卡片上的飞书 SSO 开关是否已启用。
  </Accordion>
</AccordionGroup>