在 Liberty 中配置 SAML Web 瀏覽器 SSO
您可以將 Liberty 伺服器配置成當作 SAML Web 瀏覽器單一登入 (SSO) 服務提供者。
關於這項作業
您可以在 Liberty 中啟用 samlWeb-2.0 特性,外加其他的配置資訊,將 Liberty 伺服器配置成 SAML Web SSO 服務提供者。
程序
- 在 server.xml 檔中新增 samlWeb-2.0
Liberty 特性,作法是在 featureManager 元素內新增下列元素宣告。
<feature>samlWeb-2.0</feature>
- Liberty 提供預設 samlWebSso20 元素。
<samlWebSso20 id="defaultSP"> </samlWebSso20>
在這項預設配置中,假設預設值如下:- AssertionConsumerService URL:
https://<hostname>:<sslport> /ibm/saml20/defaultSP/acs
- 服務提供者 (SP) meta 資料 URL:
https://<hostname>:<sslport> /ibm/saml20/defaultSP/samlmetadata
您可以利用瀏覽器,使用這個 URL 來下載這個服務提供者 (SP) 的 meta 資料,並提供 SAML 身分提供者的 URL,以便在這個 SP 和「身分提供者 (IdP)」之間建立聯合。
- IdP meta 資料檔必須複製到伺服器上的 resources/security 目錄,並命名為 idpMetadata.xml。
- 會以 SAML 主張的簽發者名稱作為安全網域範圍,以 NameID 作為主體,以便從 SAML 主張建立受鑑別的主體。
- 如果沒有指定 KeyStoreRef 屬性,會使用伺服器預設金鑰儲存庫中的私密金鑰,來簽署 SAML AuthnRequest。如果沒有配置 keyAlias,則預設金鑰別名是 samlsp。如果沒有配置 keyAlias,則金鑰儲存庫只包含一個私密金鑰,且會在簽章中使用該私密金鑰。
註: 如果您建立新的服務提供者實例,且不再需要 defaultSP,您必須在 server.xml 檔中新增下列項目,以明確停用 defaultSP 實例。<samlWebSso20 id="defaultSP" enabled="false"> </samlWebSso20>
註: 您必須指定一個非空值的 URL 安全字串,來作為 samlWebSso20 的 ID。如果遺漏 ID,會忽略配置元素,且不會當成 defaultSP 來處理。註: 一旦配置和啟用了 SAML,所有未經鑑別的要求都會採用 SAML 鑑別。如果要配置應該和不應使用 SAML 鑑別的要求類型,您必須根據步驟 15 的說明,來配置鑑別過濾器。 - AssertionConsumerService URL:
- 選用:您可以在 server.xml 檔中新增 <samlWebSso20 id="defaultSP">,並自訂 defaultSP 服務提供者。例如:
- idpMetadata:新增這個參數,以變更 IdP meta 資料的預設位置和檔名 (${server.config.dir}/resources/security/idpMetadata.xml)。
- userIdentifier:新增這個參數,來選取一個 SAML 屬性名稱,以便使用其值作為主體名稱。
- groupIdentifier:新增這個參數,來選取一個 SAML 屬性名稱,以便將其值當成群組成員包含在主體中。
- realmName:這個參數用來明確指定網域範圍名稱,以便在這個服務提供者中識別 SAML 主體。預設網域範圍名稱是 SAML 簽發者名稱。
- 選用:您可以使用不同的 ID 來建立一或多個新的 samlWebSso20 元素。比方說,如果您建立新元素,且其 ID 是 mySP,您可以有效建立新的 SAML SP 實例,並使用新的 AssertionConsumerService URL:
https://<hostname>:<sslport>/ibm/saml20/mySP/acs
註: 您選給 samlWebSso20 的 ID 會包含在 SP 的 URL 中,其中包括 AssertionConsumerService URL 和 meta 資料 URL。samlWebSso20 ID 必須非空白,且不得包含不安全的 URL 字元。 - 選用:您可以配置信任引擎。Liberty SAML SP 支援兩種類型的信任引擎:
- meta 資料信任引擎:根據所配置之 IdP meta 資料中提供的資訊,來驗證簽章。
- PKIX 信任引擎:透過 PKIX 驗證,來驗證簽章中之憑證的可信度。通過這項驗證的憑證會假設是授信的。
meta 資料是預設信任引擎。如果您想要使用 PKIX 信任引擎,您需要新增 PKIXTrustEngine 元素,並定義適當的 trustAnchor。
- 選用:您可以配置如何從 SAML 建立受鑑別的主體。依預設,Liberty SP 會直接從 SAML 主張建立主體,而不需使用本端使用者登錄,這等同於 mapToUserRegistry=No 配置。其他的配置選項是 mapToUserRegistry=User 或 mapToUserRegistry=Group。
- mapToUserRegistry=No:SAML 簽發者名稱是網域範圍,並使用 NameID 在主體中建立主體名稱和唯一安全名稱,且不包含群組成員。您可以配置 userIdentifier, realmIdentifier、groupIdentifier 和 userUniqueIdentifier 等屬性,以便使用自訂的使用者名稱、網域範圍名稱、群組成員資格和唯一的安全 ID,來建立受鑑別的主體。
- mapToUserRegistry=User:如果您想根據您的內部部署使用者登錄,來驗證 SAML 使用者,並根據內部部署登錄來建立使用者主體,請選擇這個選項。
- mapToUserRegistry=Group:如果您想根據您的本端使用者登錄,來驗證 SAML 群組,並建立主體來包含那些已驗證的群組,請選擇這個選項。這個選項類似於 mapToUserRegistry=No,只不過會根據內部部署使用者登錄來驗證群組成員資格。
- 選用:您可以採使用者特性形式來實作 Liberty SAML SPI com.ibm.wsspi.security.saml2.UserCredentialResolver,以便將 SAML 主張動態對映至 Liberty 主體。
- 選用:您可以定義規則,以告知 IdP 如何鑑別使用者,作法是在使用由 SP 起始的 Web SSO 流程時,配置下列一或多個屬性:forceAuthn、isPassive、allowCreate、authnContextClassRef 和 authnContextComparisonType。
- 選用:您可以在 AuthnRequest 中使用 nameIDFormat 屬性,來定義必要的 NameID 格式。您可以指定 SAML 規格中所定義的任何 NameID 格式,或使用關鍵字 customize 來指定自訂 NameId 格式。
- 選用:您可以建立多個 samlWebSso20 元素,且每一個 samlWebSso20 各參照一個唯一的 authFilter 元素,以配置多個 SP 和 IdP 聯合夥伴。所有 authFilter 必須彼此排除。當配置多個 samlWebSso20 時,每一個都可以利用其聯合的身分提供者來執行單一登入,且各有自己的鑑別原則和耗用規則。
- 選用:新增由 IdP 起始的自發性 SSO 支援。Liberty SAML SP 支援 IdP 所起始需要及不需要使用 IdP meta 資料內部部署的自發性 SSO。如果您沒有 IdP meta 資料,或者您打算使用自發性 SSO,將多個身分提供者與一個 Liberty SP 聯合在一起,您必須新增下列配置:
- 配置 <PKIXTrustEngine>,並將所有 IdP 簽章者憑證匯入至 Liberty 伺服器的預設信任儲存庫,或匯入至 PKIXTrustEngine 的 trustAnchor。
- 配置 trustedIssuers,以便在 IdP 出現於 SAML 主張中時,列出其簽發者名稱。在 meta 資料中,會以簽發者名稱作為 EntityID。
- 如果您打算只支援自發性 SSO,您可以按照下一步的說明,配置由 SP 起始的自發性 SSO。如果 SAML 相關聯 SP 中的使用者安全環境定義變成無效,則這項實務很有用,因為 SP 可將使用者重新導向回 IdP,以自動重新啟動自發性 SSO。
- 選用:新增由 SP 起始的自發性 SSO 支援。Liberty SAML SP 使用所配置的 IdP meta 資料,來執行請求的 SAML AuthnRequest。Liberty SP 可能將未經鑑別的要求重新導向至預先配置的登入應用程式,而不使用 AuthnRequest。如果商業應用程式會先執行預先鑑別處理程序,之後使用者才能接受 SAML IdP 的鑑別,或者必須隱藏 SAML IdP,不讓 Liberty SP 發現,則此實務很有用。如果要配置這項實務,請新增 loginPageURL 屬性,並將其值設為一個可指示使用者接受 SAML IdP 鑑別的 URL。
- 選用:配置簽章需求,注意事項如下:
- SAML 主張。所有 SAML 主張必須由 SAML IdP 數位簽署。在極少數情況下,如果您想接受未簽署的主張,您可以明確配置 wantAssertionsSigned=false。
- 預設簽章演算法是 SHA256。如果您必須變更演算法,請使用 signatureMethodAlgorithm 屬性來修改它。
- 如果您不想簽署 SAML AuthnRequest,可設定 authnRequestsSigned=false。
- 選用:您可以配置 SP 鑑別階段作業和 Cookie。在驗證和處理 SAML 主張之後,Liberty SAML SP 會維護瀏覽器和 SP 之間的受鑑別階段作業,而不使用 LTPA Cookie。受鑑別的階段作業逾時值會設為 <saml:AuthnStatement> 中的
SessionNotOnOrAfter(若有的話),或設為 server.xml 檔中所配置的 sessionNotOnOrAfter
(其預設值為 120 分鐘)。會自動產生階段作業 Cookie 名稱,您可以使用 spCookieName 屬性來指定想要的名稱,以自訂 Cookie 名稱。
如果您希望 Liberty SP 從 SAML 主張建立 LTPA Cookie,並在後續的鑑別要求中使用 LTPA Cookie,可新增 disableLtpaCookie=false 配置。如果您想提供 LTPA Cookie 給其他伺服器共用,必須新增配置屬性 allowCustomCacheKey="false"。
註: 如果您配置 disableLtpaCookie="false" 和 allowCustomCacheKey="false",請確定 SAML 使用者名稱不會直接接受內部部署使用者登錄的鑑別,因為內部部署使用者登錄不讓使用者有兩個帳戶。 - 選用:配置「鑑別過濾器」。
當啟用 samlWeb-2.0 特性時,會透過一個 SAML SP 來鑑別任何未經鑑別的要求。如果您定義自訂 samlWebSso20 元素,所有鑑別要求會交由這個 samlWebSso20 SP 實例來處理;否則,所有鑑別會交由預設實例 defaultSP 來處理。您可以使用 authnFilter,來定義由哪個 SP 實例來處理鑑別要求。
如需配置鑑別過濾器的相關資訊,請參閱鑑別過濾器。
- 選用:在叢集中配置 SAML SP。
如果應用程式伺服器是叢集成員,且您使用路由器或反向 Proxy 伺服器來遞送要求,則您需要執行下列作業:
- 路由器和 Proxy 伺服器必須配置成支援階段作業親緣性。
- 將配置屬性 spHostAndPort 新增至每一部應用程式伺服器,並將其值設為該路由器或 Proxy 伺服器的主機名稱和埠。例如,spHostAndPort="https://myRouter.com:443"。
- 產生 X509 憑證,以用來簽署 SAML AuthnRequest,並在所有應用程式伺服器上使用此憑證。比方說,您可以建立金鑰儲存庫,使其只包含此憑證,並新增 KeyStoreRef,以便在所有應用程式伺服器上參照這個金鑰儲存庫。
- 如果未在叢集環境中設定 createSession="true",在高壓執行期間會遇到下列錯誤:
E CWWKS5029E: 無法辨識身分提供者 (IdP) 回應中的中繼狀態 [sp_initial_KGe22fCWKG1lD9VkOMuDz0Ji8pBxFPnU]。
以下是範例叢集配置:<keyStore id="samlKeyStore" password="<password>" location="${server.config.dir}/resources/security/<samlKey.jks>" /> <samlWebSso20 id="defaultSP" spHostAndPort="https://<IHS host>:<port>" keyStoreRef="samlKeyStore" createSession="true" allowCustomCacheKey="false" disableLtpaCookie="false" mapToUserRegistry="User"> </samlWebSso20>
結果
上層主題: 在 Liberty 中鑑別使用者

檔名:twlp_config_saml_web_sso.html