在 Liberty 中配置 SAML Web 瀏覽器 SSO

您可以將 Liberty 伺服器配置成以 SAML Web 瀏覽器單一登入 (SSO) 服務提供者形式來運作。

關於這項作業

您可以在 Liberty 中啟用 samlWeb-2.0 特性,外加提供其他的配置資訊,將 Liberty 伺服器配置成 SAML Web SSO 服務提供者。

程序

  1. server.xml 檔中新增 samlWeb-2.0 Liberty 特性,作法是在 featureManager 元素內新增下列元素宣告。
    <feature>samlWeb-2.0</feature>
  2. 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 的說明,來配置鑑別過濾器。
  3. 選用:您可以在 server.xml 檔中新增 <samlWebSso20 id="defaultSP">,並自訂 defaultSP 服務提供者。例如:
    • idpMetadata:新增這個參數,以變更 IdP meta 資料的預設位置和檔名 (${server.config.dir}/resources/security/idpMetadata.xml)
    • userIdentifier:新增這個參數,來選取一個 SAML 屬性名稱,以便使用其值作為主體名稱。
    • groupIdentifier:新增這個參數,來選取一個 SAML 屬性名稱,以便將其值當成群組成員包含在主體中。
    • realmName:這個參數用來明確指定網域範圍名稱,以便在這個服務提供者中識別 SAML 主體。預設網域範圍名稱是 SAML 簽發者名稱。
  4. 選用:您可以使用不同的 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 字元。
  5. 選用:您可以配置信任引擎。Liberty SAML SP 支援兩種類型的信任引擎:
    • meta 資料信任引擎:根據所配置之 IdP meta 資料中提供的資訊,來驗證簽章。
    • PKIX 信任引擎:透過 PKIX 驗證,來驗證簽章中之憑證的可信度。通過這項驗證的憑證會假設是授信的。

    meta 資料是預設信任引擎。如果您想要使用 PKIX 信任引擎,您需要新增 PKIXTrustEngine 元素,並定義適當的 trustAnchor

  6. 選用:您可以配置如何從 SAML 建立受鑑別的主體。依預設,Liberty SP 會直接從 SAML 主張建立主體,而不需使用本端使用者登錄,這等同於 mapToUserRegistry=No 配置。其他的配置選項是 mapToUserRegistry=UsermapToUserRegistry=Group
    • mapToUserRegistry=No:SAML 簽發者名稱是網域範圍,並使用 NameID 在主體中建立主體名稱和唯一安全名稱,且不包含群組成員。您可以配置 userIdentifier, realmIdentifiergroupIdentifieruserUniqueIdentifier 等屬性,以便使用自訂的使用者名稱、網域範圍名稱、群組成員資格和唯一的安全 ID,來建立受鑑別的主體。
    • mapToUserRegistry=User:如果您想根據您的內部部署使用者登錄,來驗證 SAML 使用者,並根據內部部署登錄來建立使用者主體,請選擇這個選項。
    • mapToUserRegistry=Group:如果您想根據您的本端使用者登錄,來驗證 SAML 群組,並建立主體來包含那些已驗證的群組,請選擇這個選項。這個選項類似於 mapToUserRegistry=No,只不過會根據內部部署使用者登錄來驗證群組成員資格。
  7. 選用:您可以採使用者特性形式來實作 Liberty SAML SPI com.ibm.wsspi.security.saml2.UserCredentialResolver,以便將 SAML 主張動態對映至 Liberty 主體。
  8. 選用:您可以定義規則,以告知 IdP 如何鑑別使用者,作法是在使用由 SP 起始的 Web SSO 流程時,配置下列一或多個屬性: forceAuthnisPassiveallowCreateauthnContextClassRefauthnContextComparisonType
  9. 選用:您可以在 AuthnRequest 中使用 nameIDFormat 屬性,來定義必要的 NameID 格式。您可以指定 SAML 規格中所定義的任何 NameID 格式,或使用關鍵字 customize 來指定自訂 NameId 格式。
  10. 選用:您可以建立多個 samlWebSso20 元素,且每一個 samlWebSso20 各參照一個唯一的 authFilter 元素,以配置多個 SP 和 IdP 聯合夥伴。所有 authFilter 必須彼此排除。當配置多個 samlWebSso20 時,每一個都可以利用其聯合的身分提供者來執行單一登入,且各有自己的鑑別原則和耗用規則。
  11. 選用:新增由 IdP 起始的自發性 SSO 支援。Liberty SAML SP 支援由 IdP 起始的自發性 SSO,以及需要和不需要使用就地部署的 IdP meta 資料。如果您沒有 IdP meta 資料,或者您打算使用自發性 SSO,將多個身分提供者與一個 Liberty SP 聯合在一起,您必須新增下列配置:
    • 配置 <PKIXTrustEngine>,並將所有 IdP 簽章者憑證匯入至 Liberty 伺服器的預設信任儲存庫,或匯入至 PKIXTrustEnginetrustAnchor
    • 配置 trustedIssuers,以便在 IdP 出現於 SAML 主張中時,列出其簽發者名稱。在 meta 資料中,會以簽發者名稱作為 EntityID
    • 如果您打算只支援自發性 SSO,您可以按照下一步的說明,配置由 SP 起始的自發性 SSO。如果 SAML 相關聯 SP 中的使用者安全環境定義變成無效,則這項實務很有用,因為 SP 可將使用者重新導向回 IdP,以自動重新啟動自發性 SSO。
  12. 選用:新增由 SP 起始的自發性 SSO 支援。Liberty SAML SP 使用所配置的 IdP meta 資料,來執行請求的 SAML AuthnRequest。Liberty SP 可能將未經鑑別的要求重新導向至預先配置的登入應用程式,而不使用 AuthnRequest。如果商業應用程式會先執行預先鑑別處理程序,之後使用者才能接受 SAML IdP 的鑑別,或者必須隱藏 SAML IdP,不讓 Liberty SP 發現,則此實務很有用。如果要配置這項實務,請新增 loginPageURL 屬性,並將其值設為一個可指示使用者接受 SAML IdP 鑑別的 URL。
  13. 選用:配置簽章需求,注意事項如下:
    • SAML 主張。所有 SAML 主張必須由 SAML IdP 數位簽署。在極少數情況下,如果您想接受未簽署的主張,您可以明確配置 wantAssertionsSigned=false
    • 預設簽章演算法是 SHA256。如果您必須變更演算法,請使用 signatureMethodAlgorithm 屬性來修改它。
    • 如果您不想簽署 SAML AuthnRequest,可設定 authnRequestsSigned=false
  14. 選用:您可以配置 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 使用者名稱不會直接接受內部部署使用者登錄的鑑別,因為內部部署使用者登錄不讓使用者有兩個帳戶。
  15. 選用:配置「鑑別過濾器」。

    當啟用 samlWeb-2.0 特性時,會透過一個 SAML SP 來鑑別任何未經鑑別的要求。如果您定義自訂 samlWebSso20 元素,所有鑑別要求會交由這個 samlWebSso20 SP 實例來處理;否則,所有鑑別會交由預設實例 defaultSP 來處理。您可以使用 authnFilter,來定義由哪個 SP 實例來處理鑑別要求。

    如需配置鑑別過濾器的相關資訊,請參閱鑑別過濾器

  16. 選用:在叢集中配置 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 伺服器配置成 SAML 服務提供者,而能夠利用 SAML 身分提供者進行單一登入。

指示主題類型的圖示 作業主題



「時間戳記」圖示 前次更新: 2016 年 11 月 30 日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_config_saml_web_sso
檔名:twlp_config_saml_web_sso.html