Liberty 中配置 SAML Web 浏览器 SSO

可配置 Liberty 服务器以充当 SAML Web 浏览器单点登录 (SSO) 服务提供者。

关于此任务

通过在 Liberty 中启用 samlWeb-2.0 功能部件以及输入其他配置信息,可将 Liberty 服务器配置为 SAML Web SSO 服务提供者。

过程

  1. 通过在 featureManager 元素中添加以下元素声明,将 samlWeb-2.0 Liberty 功能部件添加至 server.xml 文件。
    <feature>samlWeb-2.0</feature>
  2. Liberty 提供缺省 samlWebSso20 元素。
    <samlWebSso20 id="defaultSP">
    
    </samlWebSso20>
    在此缺省配置中,将采用以下缺省值:
    • AssertionConsumerService URL:
      https://<hostname>:<sslport> /ibm/saml20/defaultSP/acs
    • 服务提供者 (SP) 元数据 URL:
      https://<hostname>:<sslport> /ibm/saml20/defaultSP/samlmetadata

      可使用浏览器以通过此 URL 下载此服务提供者 (SP) 的元数据,并提供 SAML 身份提供者的 URL 以在此 SP 与身份提供者 (IdP) 之间建立联合。

    • 必须将 IdP 元数据文件复制到服务器上的 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 的标识。如果缺少标识,那么配置元素将被省略,并且不会作为 defaultSP 处理。
    注: 如果已配置并启用了 SAML,那么所有未认证请求将使用 SAML 认证。要配置应使用 SAML 认证和不应使用 SAML 认证的请求类型,必须按步骤 15 中所述配置认证过滤器。
  3. 可选:可将 <samlWebSso20 id="defaultSP"> 添加至 server.xml 文件,并定制 defaultSP 服务提供者。例如:
    • idpMetadata:添加此参数以更改 IdP 元数据位置和文件名(缺省位置和文件名为 (${server.config.dir}/resources/security/idpMetadata.xml))。
    • userIdentifier:添加此参数以选择其值将用作主体名称的 SAML 属性名。
    • groupIdentifier:添加此参数以选择其值在主题中包含为组成员的 SAML 属性名。
    • realmName:使用此参数显式指定用于在此服务提供者中标识 SAML 主体的域名。缺省域名为 SAML 签发者名称。
  4. 可选:可使用另一标识创建一个或多个新 samlWebSso20 元素。例如,如果使用 mySP 作为标识创建新元素,那么实际将创建具有新 AssertionConsumerService URL 的新 SAML SP 实例:
    https://<hostname>:<sslport>/ibm/saml20/mySP/acs
    注: 您为 samlWebSso20 选择的标识将包含在 SP 的 URL(包括 AssertionConsumerService URL 和元数据 URL)中。samlWebSso20 标识必须为非空,并且不能包含非安全 URL 字符。
  5. 可选:可配置信任引擎。Liberty SAML SP 支持两种信任引擎类型:
    • 元数据信任引擎:针对所配置 IdP 元数据中提供的信息验证签名。
    • PKIX 信任引擎:通过 PKIX 验证来验证签名中的证书的可信任度。通过此验证的证书被认为可信。

    元数据是缺省信任引擎。如果要使用 PKIX 信任引擎,您需要添加 PKIXTrustEngine 元素并定义相应 trustAnchor

  6. 可选:可配置如何通过 SAML 创建已认证的主体集。缺省情况下,Liberty SP 直接通过 SAML 断言创建主体集而不需要本地用户注册表(相当于配置 mapToUserRegistry=No)。其他配置选项为 mapToUserRegistry=UsermapToUserRegistry=Group
    • mapToUserRegistry=No:SAML 签发者的名称为域,NameID 用于在主体集中创建主体名称和唯一安全名称,组成员未被包括。可配置 userIdentifierrealmIdentifiergroupIdentifieruserUniqueIdentifier 属性以创建带有定制用户名、领域名、组成员资格和唯一安全标识的认证主体集。
    • 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. 可选:可使用 nameIDFormat 属性定义 AuthnRequest 中的必需 NameID 格式。可指定 SAML 规范中定义的任何 NameID 格式,或使用关键字 customize 来指定定制 NameId 格式。
  10. 可选:可通过创建多个 samlWebSso20 元素(每个 samlWebSso20 引用一个独有 authFilter 元素)来配置多个 SP 和 IdP 联合合作伙伴。所有 authFilters 都必须互斥。对于所配置的多个 samlWebSso20,每个 samlWebSso20 可使用其联合身份提供程序执行单点登录,并具有自己的认证策略和使用规则。
  11. 可选:添加对 IdP 启动的非请求式 SSO 的支持。Liberty SAML SP 支持 IdP 启动的非请求式 SSO,不管其是否需要在本地 IdP 元数据都支持。如果没有 IdP 元数据,或者您计划使用非请求式 SSO 以通过一个 Liberty SP 与多个身份提供者联合,那么必须添加以下配置:
    • 配置 <PKIXTrustEngine>,并将所有 IdP 签署者证书导入至 Liberty 服务器的缺省信任库,或导入至 PKIXTrustEnginetrustAnchor
    • 配置 trustedIssuers 以列示 IdP 出现在 SAML 断言中时的签发者名称。签发者名称在元数据中用作 EntityID
    • 如果计划仅支持非请求式 SSO,那么可按下一步中所述配置 SP 启动的非请求式 SSO。如果与 SAML 相关联的 SP 中的用户安全上下文变为无效,那么此方案很有用,SP 可将用户重定向回 IdP 以再次自动启动非请求式 SSO。
  12. 可选:添加对 SP 启动的非请求式 SSO 的支持。Liberty SAML SP 使用所配置 IdP 元数据执行请求式 SAML AuthnRequestLiberty SP 可将未认证请求重定向至预先配置的登录应用程序而不使用 AuthnRequest。如果业务应用程序执行预认证处理(之后用户才能向 SAML IdP 认证)或者必须对 Liberty SP 隐藏 SAML IdP,那么此方案很有用。要配置此方案,应添加 loginPageURL 属性,并将其值设置为可指示用户向 SAML IdP 认证的 URL。
  13. 可选:配置签名需求并考虑以下事项:
    • SAML 断言。所有 SAML 断言必须由 SAML IdP 以数字方式签名。如果您想要接受未签名的断言(极少情况),那么您可显式配置 wantAssertionsSigned=false
    • 缺省签名算法为 SHA256。如果必须更改算法,请使用 signatureMethodAlgorithm 属性进行修改。
    • 如果不想签署 SAML AuthnRequest,那么可设置 authnRequestsSigned=false
  14. 可选:可配置 SP 认证会话和 cookie。验证并处理 SAML 断言后,Liberty SAML SP 在不使用 LTPA cookie 的情况下维护浏览器与 SP 之间的已认证会话。已认证会话超时值在 <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。

    如果应用程序服务器是集群成员,并且您使用路由器或逆向代理服务器来路由请求,那么需要执行以下任务:

    • 路由器和代理服务器必须配置为支持会话亲缘关系。
    • 将配置属性 spHostAndPort 添加至每个应用程序服务器,并将其值设置为路由器或代理服务器主机名和端口。例如,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 身份提供者进行单点登录)时所需的配置。

用于指示主题类型的图标 任务主题

文件名:twlp_config_saml_web_sso.html