簡化開發者的 SAML 認證整合

單一登入（SSO） 是現代應用程式的關鍵，SAML 讓企業身份系統間的認證更安全親切。本指南用清楚步驟和實用範例，幫助開發者與設計師高效實踐 SAML。

什麼是 SAML 認證和 SAML 應用？#

安全聲明標記語言（SAML） 是基於 XML 的標準，讓企業間的**身分提供者（IdP）和服務提供者（SP）**交換認證與授權資料。這是在企業內建構單一登入（SSO）的常見解決方案，讓企業使用者只需登入一次即可存取多個應用。

身分提供者（IdP） 負責管理和驗證使用者憑證，如使用者名稱和密碼。當使用者嘗試存取受保護服務時，IdP 會確認其身分並將認證訊息發送給服務。

• **例子：**想像你在一家大型公司上班，公司用 Microsoft Azure AD 管理員工帳號。當你要登入 Salesforce 時，Azure AD 作為 IdP，檢查你的憑證並告訴 Salesforce 你有權限登入。

服務提供者（SP） 是使用者實際想存取的應用或服務，它倚賴 IdP 負責繁複的認證工作。

• **例子：**延續上述場景，Salesforce 就是 SP。它仰賴 Microsoft Azure AD（IdP）確認你的身份。一旦 Azure AD 擔保你，Salesforce 就讓你登入。

當人們提到「SAML 應用」時，通常指的是 SP。

利用 SAML 協議，你可以將服務設為 IdP 來支援應用整合（例如 Azure AD 或 Google Workspace）；或設為 SP（像 Salesforce 或 Slack），讓使用者享有 SSO。

**SAML Assertion（敘述）**是 SAML 協議的核心。這是一份由 IdP 創建並發送給 SP 的數位「證明」：“我已確認此使用者的身份。”接下來我們會說明 IdP 和 SP 的流程。

作為 SAML 身分提供者時#

當你的服務作為 IdP 時，你能讓多個應用通過 SAML 認證。如此一來，使用者就能用單一企業身份存取多個服務。

以下是常見 IdP SAML SSO 流程：

1. 使用者試圖存取應用（SP），例如 Salesforce。
2. 應用將使用者導向你的 IdP 認證頁面。
3. 使用者在 IdP 登入頁輸入憑證。
4. IdP 檢查憑證。
5. 驗證通過後，IdP 將 SAML Assertion 傳回 SP。
6. SP 處理 Assertion，確認有效後給使用者授權。

作為 SAML 服務提供者時#

如果你的服務是 SP，你將需整合多個身分提供者，為使用者提供 SSO 能力。這讓不同企業的使用者都能安全有效存取你的應用。

以下是 SP 發起的 SSO 流程：

1. 使用者嘗試登入你的應用。
2. 你的應用建立 SAML 請求並導向使用者到 IdP 的登入頁。
3. 使用者在 IdP 登入（或若已登入則略過此步）。
4. IdP 驗證身份後，把使用者資訊封裝進 SAML Assertion。
5. IdP 把 Assertion 傳回你的應用。
6. 你的服務驗證 Assertion，如果有效，使用者即可登入你的應用。

SAML SSO 的關鍵參數#

順利整合 SAML SSO，IdP 與 SP 必須溝通特定參數。重點如下：

IdP 提供的參數#

1. **IdP Entity ID：**SAML 通訊中 IdP 的唯一識別碼，就像數位名牌一樣。
2. **SSO URL：**SP 導轉使用者做認證的登入端點（網址）。
3. **X.509 憑證：**簽署 SAML Assertion 的公鑰，確保安全性。這是用來驗證真偽的“印章”。

小提示：若 IdP 提供 SAML Metadata URL，整合更簡單。這網址包含所有必要資訊（如憑證、SSO URL 和 IdP Entity ID），可減少手動複製產生失誤，也免去更新憑證檔案的麻煩。

SP 提供的參數#

1. **SP Entity ID：**SP 的唯一識別碼，概念與 IdP Entity ID 相同。
2. **Assertion Consumer Service (ACS) URL：**SP 接收來自 IdP SAML Assertion 的端點。
3. **RelayState（選填）：**在 SAML 流程中傳遞資料（如原本想訪問的網址）。

SAML 屬性映射和加密#

1. **NameID Format：**定義使用者標識格式（例如電子郵件或使用者名稱）。
2. **SAML 屬性：**IdP 向 SP 傳送的其它使用者資料，如角色、電子郵件、部門等。
   • 例子：假設 IdP 簽署的 SAML Assertion 包含 email（[email protected]）、role（admin）、department（engineering），SP 可用 role 指派管理者權限或用 department 將使用者分組。雙方需協議屬性如何對應，例如 IdP 使用 “department” 代表 team，但 SP 期望用 group。正確對應有助於順暢通訊。
3. **加密 Assertion（選填）：**為保護敏感認證資料，SAML Assertion 可加密。
   • **IdP 角色：**用 SP 的公開金鑰加密 Assertion。
   • **SP 角色：**用私鑰解密 Assertion 以讀取使用者細節。

現在，你已擁有設定 SAML 連線的必要資訊。若要將 Salesforce（服務提供者）與 Azure AD（身分提供者）整合，可遵循這些步驟：

• 從 Azure AD 取得 IdP Entity ID、SSO URL、憑證並設於 Salesforce。
• 將 Salesforce 的 SP Entity ID 和 ACS URL 提供給 Azure AD。

Logto 讓 SAML 整合變簡單#

Logto 可以作為 IdP 或 SP，支援你的應用程式進行 SAML SSO。

將 Logto 作為 SAML IdP#

Logto 讓其他應用信賴其身分整合認證，並支援 多因素認證（MFA） 強化安全性。

1. 建立 Logto App 前往 Logto Console > 應用程式 建立新的 SAML 應用。
2. 設定 SAML 參數 設定應用的服務提供者（SP）Assertion Consumer Service URL 與 SP Entity ID。
3. 提供 Metadata URL Logto 提供 IdP Metadata URL，讓 SP 自動取得 SSO URL、憑證等必要細節。
4. 進階設定（選填）
   • 可建立多張新憑證（附指紋，可設到期日）但僅一張有效。
   • 調整 Name ID format 以符合業務需求。
   • 啟用 SAML Assertion 加密，從 SP 複製 x509 憑證來加密 Assertion。
5. 屬性映射（選填） 輕鬆自訂要如何將使用者屬性分享給 SP。

詳細指引請見官方文件：SAML App

將 Logto 作為 SAML SP#

Logto 同時能和任何企業 IdP 透過 SAML 或 OIDC 整合。不論你要為統一登入頁設計 SP 發起的 SSO，或配置 IdP 發起 SSO，流程都很直覺。

1. 建立企業連接器 前往 Logto Console > 企業 SSO 建立新的企業連接器，並選擇 SAML 協定。
2. 設定 SAML 參數 使用你的 IdP 提供的 Metadata URL 或 Metadata XML 檔案。如無 Metadata，可手動輸入 IdP Entity ID、SSO URL 與上傳簽署憑證。
3. 分享 ACS URL 及 SP Entity ID 提供 Logto 的 ACS URL 及 SP Entity ID 給 IdP 以完成整合設置。
4. 映射屬性（選填） 配置如 email、名稱等使用者資料對應，確保 IdP 和 Logto 資訊互通。
5. 新增企業電子郵件網域 於企業連接器「SSO 體驗」分頁新增一個或多個 email 網域，僅有指定網域的帳號可 SSO 登入。
6. 啟用 IdP 發起 SSO（選填） 如企業客戶有此需求，啟用 IdP 發起登入功能。這讓使用者可直接從 IdP 控制台登入你的應用。

詳細指引見官方文件：企業 SSO 文件。

結語#

SAML 提供標準又安全的 SSO 方式，讓認證流程順暢。Logto 讓設定 IdP 或 SP 皆更加簡單易用。無論是 雲端 或 開源 版本，Logto 的直觀介面大幅降低 SAML 整合複雜度。只需簡單配置幾個參數，你就能讓你的服務與任一 SAML IdP 或 SP 串接，專注於創造出色的用戶體驗。