跳至主要內容

設定 SAML 單一登入 (SSO)

只需極少設定，即可透過此連接器整合任何基於 SAML 的身分提供者 (IdP, Identity Provider)。

提示:

如需更多關於單一登入 (SSO) 的資訊以及如何在 Logto 中配置 SSO，請參閱 企業級單一登入 (Enterprise SSO) (SAML & OIDC) 文件以開始使用。

步驟 1：在你的 IdP 上建立 SAML SSO 應用程式​

在 IdP 端創建應用程式以啟動 SAML 單一登入 (SSO) 整合。從 Logto 獲取以下配置，代表你的服務提供者 (SP)：

  • 受眾 URI (Audience URI, SP Entity ID)：它作為 Logto 服務的全域唯一識別符，作為 SP 在向 IdP 發送驗證請求時的 EntityId。此識別符對於 IdP 與 Logto 之間安全交換 SAML 聲明和其他驗證相關數據至關重要。
  • ACS URL：Assertion Consumer Service (ACS) URL 是以 POST 請求發送 SAML 聲明的位置。此 URL 由 IdP 用於將 SAML 聲明發送至 Logto。它充當回呼 URL，Logto 預期在此接收並處理包含使用者身分資訊的 SAML 回應。

在你的 IdP SAML 應用程式中填寫受眾 URI 和 ACS URL 配置，然後繼續從你的 IdP 獲取以下配置。

步驟 2：在 Logto 上設定 SAML SSO​

要使 SAML 單一登入 (SSO) 整合正常運作，你需要將 IdP 元資料提供給 Logto。IdP 元資料是一個 XML 文件，包含 Logto 與 IdP 建立信任所需的所有資訊。

導航至 Connection 標籤。Logto 提供三種不同方式來配置 IdP 元資料：

  1. 元資料 URL：提供 IdP 元資料 XML 文件的 URL。Logto 將從該 URL 獲取元資料並自動配置 SAML 單一登入 (SSO) 整合。
  2. 上傳元資料：上傳 IdP 元資料 XML 文件。Logto 將解析該 XML 文件並自動配置 SAML 單一登入 (SSO) 整合。
  3. 手動配置：手動配置 IdP 元資料。
  • IdP 實體 ID：IdP 的實體 ID。
  • 單一登入 URL：IdP 單一登入服務的 URL。
  • 簽署憑證：x509 憑證，用於驗證來自 IdP 的 SAML 回應的簽名。

使用上述任一配置方式，Logto 將解析 IdP 元資料並相應地配置 SAML 單一登入 (SSO) 整合。

步驟 3：設定使用者屬性對應​

從 IdP 返回的使用者屬性可能會根據 IdP 的配置而有所不同。Logto 提供了一種靈活的方法，將從 IdP 返回的使用者屬性映射到 Logto 中的使用者屬性。你可以在 SAML 單一登入 (SSO) 整合體驗標籤中配置使用者屬性映射。

  • id：使用者的唯一識別符。Logto 將從 SAML 回應中讀取 nameId 宣告作為使用者 SSO 身分識別 id。
  • email：使用者的電子郵件地址。
  • name：使用者的名稱。

步驟 4：設定電子郵件網域並啟用 SSO 連接器​

在 Logto 的連接器 SSO 體驗 標籤中提供你組織的 電子郵件網域。這將啟用 SSO 連接器作為這些使用者的驗證 (Authentication) 方法。

擁有指定網域電子郵件地址的使用者將被重定向，使用 SAML SSO 連接器作為他們唯一的驗證 (Authentication) 方法。

選用：簽署 SAML 驗證請求 (Authentication request)​

預設情況下，Logto 傳送的 SAML 驗證請求（AuthnRequests）是不簽章的。如果你的身分提供者 (IdP, Identity provider) 需要簽章的驗證請求，Logto 可以使用產生的服務提供者 (SP, Service Provider) 憑證來簽署這些請求。簽署行為完全由連接器的 簽署驗證請求 (Sign authentication request) 設定控制 —— Logto 不會從 IdP metadata 讀取 WantAuthnRequestsSigned 旗標。

請依照以下順序設定，以避免登入流程中斷：

  1. 在連接器的 Connection 分頁中，找到 請求簽署憑證 (Request signing certificate) 區段並點擊 產生新金鑰 (Generate new key)。第一把金鑰會自動啟用；之後產生的金鑰會以非啟用（待輪替）狀態儲存。
  2. 下載啟用中金鑰的憑證，並在你的 IdP 註冊。
  3. 啟用 簽署驗證請求 (Sign authentication request) 並儲存。啟用時必須有啟用中的簽署金鑰 —— 若沒有則無法儲存。
  4. 如果你的 IdP 有額外選項要求或驗證簽署請求，請現在開啟，然後測試登入流程。
注意:

請保持雙方設定同步。若在憑證註冊前啟用 簽署驗證請求 (Sign authentication request)，或在 Logto 開始簽署前於 IdP 端要求驗證，將導致此連線的登入失敗，直到另一方設定完成。未驗證請求簽章的 IdP 會直接忽略簽章。

金鑰管理與開關獨立運作：

  • 最多僅有一把金鑰為 啟用 (active) 狀態，且所有請求都由啟用金鑰簽署。金鑰操作（產生、啟用、停用、刪除）立即生效。
  • 若要無停機輪替憑證：先產生新金鑰（預設為非啟用），將其憑證註冊到 IdP，然後啟用新金鑰 —— 先前的金鑰會自動停用，之後可刪除。
  • 啟用中的金鑰無法被刪除，且在 簽署驗證請求 (Sign authentication request) 啟用時無法停用 —— 請先關閉簽署功能。
  • 關閉開關時所有金鑰都會保留，因此重新啟用時會繼續使用同一憑證簽署 —— 無需在 IdP 端重新設定。

Logto 預設使用 RSA-SHA256 為請求簽章。若需使用 RSA-SHA512，請在連接器設定中透過 Logto Management API 將 requestSignatureAlgorithm 設為 http://www.w3.org/2001/04/xmldsig-more#rsa-sha512。

SAML 安全性備忘清單