# 為 Verdent Team 設定飛書 SSO (/zh-Hant/docs/account-billing/configure-feishu-sso)

> 將飛書連接至 Verdent Team，提供統一的企業身分登入



Verdent Team 支援飛書單一登入（SSO）。設定完成後，使用指定企業電子郵件網域的成員，可以透過公司的飛書帳號驗證身分。

飛書 SSO 可讓團隊沿用既有企業身分系統、減少獨立登入憑證，並由 Team Owner 集中管理存取權。

<Note>
  本指南適用於 Verdent Team Owner。只有 Team Owner 可以進入 Team 設定並管理 SSO。
</Note>

## 飛書 SSO 的運作方式 [#飛書-sso-的運作方式]

Team Owner 先在飛書開放平台建立企業自建應用程式，再將應用程式憑證與企業電子郵件網域新增至 Verdent Team。

成員在 Verdent 登入頁輸入符合網域的企業電子郵件後，Verdent 會將其導向飛書授權，並使用飛書傳回的企業電子郵件驗證身分。

<Warning>
  成員必須在飛書通訊錄中綁定企業電子郵件，否則無法透過飛書 SSO 登入。
</Warning>

## 開始之前 [#開始之前]

你需要：

* 可建立企業自建應用程式的飛書企業管理員帳號
* Verdent Team 的 Owner 權限
* 團隊的企業電子郵件網域，例如 `yourcompany.com`

完整設定通常約需 5 分鐘。

## 開啟 SSO 設定 [#開啟-sso-設定]

1. 登入 Verdent，並切換至要設定的 Team。
2. 在 Team 控制台開啟 **Settings**。
3. 選擇 **SSO**。
4. 點擊 **Connect SSO**。

設定期間建議同時開啟 Verdent 與飛書開放平台。

## 設定飛書應用程式 [#設定飛書應用程式]

<Steps>
  <Step title="建立企業自建應用程式">
    開啟[飛書開放平台](https://open.feishu.cn/app)，進入**開發者後台**，點擊**建立企業自建應用程式**，填寫名稱並上傳圖示。
  </Step>

  <Step title="取得應用程式憑證">
    開啟**憑證與基礎資訊**，找到 App ID 與 App Secret：

    | 飛書憑證           | Verdent SSO 欄位  |
    | -------------- | --------------- |
    | **App ID**     | `Client ID`     |
    | **App Secret** | `Client Secret` |

    <Warning>
      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 已啟用。你也可以暫時停用，而不刪除連接。

<Note>
  Verdent 儲存時會驗證憑證，但不會驗證飛書中的重新導向 URL。
</Note>

## 成員登入流程 [#成員登入流程]

啟用後，成員在 Verdent 登入頁輸入企業電子郵件、確認使用 SSO、前往飛書授權，然後返回 Verdent。若輸入的電子郵件與飛書傳回的企業電子郵件不同，Verdent 會要求成員確認，並使用飛書電子郵件完成驗證。

## 測試與管理設定 [#測試與管理設定]

全面啟用前，請使用一名已在飛書綁定企業電子郵件的一般成員測試。登出後以該電子郵件登入、完成飛書授權，並確認可返回 Verdent 及進入 Team。

Team Owner 可在 **Team → Settings → SSO** 查看狀態與網域、啟用或停用 SSO、更新憑證、重新設定失敗的連接，或刪除設定。

## 疑難排解 [#疑難排解]

<AccordionGroup>
  <Accordion title="飛書錯誤碼 20029：重新導向 URL 錯誤">
    在飛書的**開發設定 → 安全設定**中，確認已完整新增 `https://login.verdent.ai/passport/sso/callback`。
  </Accordion>

  <Accordion title="Verdent 顯示 Client ID 或 Client Secret 無效">
    從**憑證與基礎資訊**重新複製 App ID 與 App Secret。若 Secret 已重設，請使用最新值。
  </Accordion>

  <Accordion title="登入時顯示應用程式不可用">
    確認已在

    **版本管理與發布**

    中建立並發布版本。
  </Accordion>

  <Accordion title="登入後電子郵件為空">
    請先在飛書通訊錄中為該成員新增企業電子郵件。
  </Accordion>

  <Accordion title="成員未進入飛書 SSO 流程">
    確認電子郵件符合已設定網域，且 Verdent 中的飛書 SSO 已啟用。
  </Accordion>
</AccordionGroup>