> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 單一登入

> 將你已驗證電子郵件網域下的所有人導向你自己的 SAML 2.0 身分提供者登入，並可選擇讓它成為唯一的登入途徑。

單一登入（SSO）把 Alforse 的登入交給貴公司的 SAML 2.0 身分提供者（IdP），例如 Okta、Entra ID 或 Google Workspace。管理員只需設定一次；此後，電子郵件位於已驗證網域的 ERP 與 MES 使用者會自動被導向 IdP。

## 開始之前

* **可用性。**只有當你的帳號啟用了 SSO 時，**單一登入**區段才會出現在**設定 → 安全性**。
* **權限。**儲存 SSO 設定需要 `settings` update。
* **IdP 存取權。**你需要有權在身分提供者中建立 SAML 應用程式。
* **DNS 存取權。**你需要為每個電子郵件網域發布一筆 TXT 記錄。

在你開啟[要求 SAML SSO](#requiring-sso)之前，包括魔術連結在內的其他登入方式都會繼續運作。因此你可以完成所有設定並測試，而不會把任何人鎖在外面。

> [!NOTE]
>
> 改用飛書／Lark、釘釘或 OpenID Connect 登入？請參閱[使用飛書／Lark、釘釘與 OIDC 的單一登入](https://docs.alforse.com/zh-Hant/docs/reference/sso-oidc-feishu-dingtalk.md)。一家公司只有一個連線：儲存其中任何一個提供者，會取代 SAML 連線。

## 連線你的身分提供者

整個設定都在**設定 → 安全性**的「**單一登入**」區段中進行。

Alforse screenshot**設定 → 安全性，單一登入區段與一個啟用中的連線：服務供應商詳情、含「要求 SAML SSO」開關的身分提供者卡片，以及電子郵件網域卡片**

整個 SSO 交換都在同一個設定畫面上完成。

1. **複製 Alforse 的詳細資料。**「**服務供應商詳情**」（Service Provider Details）卡片列出「**ACS URL**」與「**SP 中繼資料 URL**」（SP Metadata URL），各附複製按鈕。
2. **使用這兩個 URL 在你的 IdP 中建立 SAML 應用程式。**請確保斷言（assertion）包含**電子郵件屬性**：Alforse 以電子郵件將每次登入對應到人員與公司。
3. **把 IdP 中繼資料交給 Alforse。**在「**身分提供者**」（Identity Provider）卡片中，輸入「**IdP 中繼資料網址**」（IdP Metadata URL）或原始的「**IdP 中繼資料 XML**」（IdP Metadata XML），兩者擇一、不可同時填寫，然後選取「**連線**」（Connect）。日後修改時，按鈕會顯示「**儲存變更**」（Save changes）。
4. **確認連線已啟用。**Alforse 會回報 "SAML SSO connection saved"（SAML SSO 連線已儲存），卡片現在會顯示「**要求 SAML SSO**」（Require SAML SSO）開關與「**停用**」（Deactivate）按鈕。
5. **在「電子郵件網域」卡片中新增並驗證你的電子郵件網域**，該卡片在連線建立後出現。請加入你的成員用來登入的每個網域，發布各網域所顯示的 DNS 記錄，然後選取「**驗證**」（Verify）。只有已驗證的網域才會導向 SSO 登入。

## 服務供應商 URL

你的身分提供者需要這兩個值。它們與「**服務供應商詳情**」卡片上的相同。

| 你的 IdP 中的設定 | 值 |
| - | - |
| **ACS URL**（Assertion Consumer Service、單一登入 URL、回覆 URL） | `https://api.alforse.com/api/web/auth/v1/sso/saml/acs` |
| **SP 中繼資料 URL**，同時也是 **SP 實體 ID**（entity ID）與**受眾**（audience） | `https://api.alforse.com/api/web/auth/v1/sso/saml/metadata` |

如果你的 IdP 可以匯入服務供應商中繼資料，請把 SP 中繼資料 URL 給它；否則就手動輸入這兩個值。

## 驗證網域

新網域一開始是**待處理**（Pending），並取得專屬的 TXT 挑戰，顯示在卡片上：

| 記錄 | 值 |
| - | - |
| **主機**（Host） | `_alforse-challenge.example.com` |
| **類型**（Type） | `TXT` |
| **值**（Value） | `alforse-domain-verification=<your unique token>` |

你新增網域時，Alforse 會確認："Domain added. Publish the TXT record shown below, then click Verify."（網域已新增。請發布下方顯示的 TXT 記錄，然後按一下「驗證」。）用你的 DNS 供應商發布該記錄之後，選取「**驗證**」。

| 結果 | 訊息 |
| - | - |
| 找到記錄且正確 | "Domain verified — it can now route SAML SSO sign-ins"（網域已驗證——現在可導向 SAML SSO 登入）。網域變為**已驗證**（Verified）。 |
| 尚無記錄 | "No TXT record found yet. DNS changes can take a few minutes to propagate — check the record's host name and try again shortly."（尚未找到 TXT 記錄。DNS 變更可能需要幾分鐘才能傳播——請檢查記錄的主機名稱，稍後再試。） |
| 記錄的值錯誤 | "A TXT record exists but its value does not match this company's verification token. Check that the record's value was copied exactly."（TXT 記錄存在，但其值與此公司的驗證權杖不符。請確認記錄的值是否完全照抄。） |
| 查詢失敗 | "The DNS lookup failed. Check your network's outbound DNS access and try again."（DNS 查詢失敗。請檢查你網路的對外 DNS 存取，然後再試一次。） |

* **驗證只需一次。**之後你可以刪除該 TXT 記錄。
* **待處理的網域不起作用。**在驗證之前，新增網域絕不會改變任何人的登入方式，所以新增是安全的。

HEADS UP

**已驗證的網域只屬於一家公司**

第一家證明擁有 DNS 控制權的公司持有該網域，即使 DNS 的控制權日後轉到別人手上，它仍保有該主張。若要乾淨地移交網域，目前的持有者請選取**移除**（Remove），這會釋出網域，讓新的擁有者進行驗證。

## 使用者的體驗

### 登入

登入頁面先詢問電子郵件。當使用者選取「**繼續**」（Continue）時：

* 若網域有啟用中的 IdP，他們會被重新導向到該 IdP；
* 否則，他們繼續使用標準的魔術連結登入。

在 Alforse 建立工作階段之前，IdP 斷言中的電子郵件網域必須與連線上**已驗證**的網域相符。

### 誰能進入：先邀請再佈建

SSO 不會讓人自行註冊。

| 人員 | 首次 SSO 登入 |
| - | - |
| 現有成員 | SAML 身分會連結到他們的帳號。 |
| 有待處理的邀請 | 邀請被接受，並套用其指派的角色。 |
| 其他任何人 | 被拒絕；不會建立帳號。 |

要讓某人進入，請在[員工目錄](https://docs.alforse.com/zh-Hant/docs/reference/people.md)中建立他們的邀請，並請他們再試一次。

### 雙重驗證

SSO 工作階段會略過 Alforse 自己的[雙重驗證挑戰](https://docs.alforse.com/zh-Hant/docs/reference/two-factor.md)，在受控部署中亦然，因為 IdP 會套用自己的 MFA 政策。以魔術連結登入仍會經過 Alforse 的挑戰。

## 要求 SSO

開啟「**要求 SAML SSO**」，讓 IdP 成為已驗證網域上使用者唯一被接受的登入方式。Alforse 會以 "SAML SSO is now required for covered domains"（涵蓋的網域現在必須使用 SAML SSO）確認，此後這些使用者的魔術連結、Google 與通行金鑰都會被拒絕。

該開關只有在連線啟用後才會出現，所以你可以在強制執行之前先確認 SSO 登入運作正常。

| 若要 | 這樣做 | 結果 |
| - | - | - |
| 再次允許其他方式 | 關閉「**要求 SAML SSO**」 | "SAML SSO is no longer required for covered domains"（涵蓋的網域不再必須使用 SAML SSO）。魔術連結、Google 與通行金鑰再度可用。 |
| 完全移除 SSO | 選取「**停用**」並確認 | "SAML SSO connection deactivated"（SAML SSO 連線已停用）。連線被刪除，其網域主張被釋出，其他方式再度可用。 |
| 停止使用某個網域 | 在該網域上選取**移除** | "Domain removed"（網域已移除）。該主張被釋出，供另一家公司驗證。 |

## 相關內容

**飛書／Lark、釘釘與 OIDC**

透過飛書或 Lark、釘釘，或任何 OpenID Connect 提供者的單一登入。

[Open](https://docs.alforse.com/zh-Hant/docs/reference/sso-oidc-feishu-dingtalk.md)

**雙重驗證**

Alforse 為魔術連結登入提供的自有第二重驗證。

[Open](https://docs.alforse.com/zh-Hant/docs/reference/two-factor.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.