Configuring SAML Web Browser SSO in Liberty

You can configure a Liberty server to function as a SAML web browser Single-Sign-On (SSO) service provider.

1. Add the samlWeb-2.0 Liberty feature to your server.xml file by adding the following element declaration inside the featureManager element.

   <feature>samlWeb-2.0</feature>

2. Liberty provides a default samlWebSso20 element.

   <samlWebSso20 id="defaultSP">
   
   </samlWebSso20>

   In this default configuration, the following default values are assumed:

   • AssertionConsumerService URL:

     https://<hostname>:<sslport> /ibm/saml20/defaultSP/acs

   • Service Provider (SP) metadata URL:

     https://<hostname>:<sslport> /ibm/saml20/defaultSP/samlmetadata

     You can use a browser to download the metadata for this service provider (SP) by using this URL, and provide the URL to the SAML identity provider to establish federation between this SP and Identity Provider (IdP).

   • The IdP metadata file must be copied to the resources/security directory on the server, and named idpMetadata.xml.
   • The issuer name for SAML assertion is used as the security realm, and NameID is used as the principal to create an authenticated subject from the SAML assertion.
   • The SAML AuthnRequest is signed with a private key in the default keystore of the server if the attribute KeyStoreRef is not specified. If the keyAlias is not configured, then samlsp is the default key alias. If the keyAlias is not configured, and the keystore only contains one private key, the private key is used in the signature.

   Note: If you create a new service provider instance, and the defaultSP is no longer required, then you must explicitly disable the defaultSP instance, by adding the following to the server.xml file.

   <samlWebSso20 id="defaultSP" enabled="false">  
   </samlWebSso20>

   Note: It is required that you specify a URL safe String that is not null as the id for samlWebSso20. If the id is missing, then the configuration element is omitted, and is not handled as the defaultSP.

   Note: When SAML is configured and enabled, all unauthenticated requests will use SAML authentication. To configure the types of requests that should and should not use SAML authentication, you must configure an authentication filter as described in step 15.
3. Optional: You can add <samlWebSso20 id="defaultSP"> to the server.xml file, and customize the defaultSP service provider. For example:
   • idpMetadata: Add this parameter to change the IdP metadata location and file name from the default location and file name (${server.config.dir}/resources/security/idpMetadata.xml).
   • userIdentifier: Add this parameter to select a SAML attribute name whose value is used as the principal name.
   • groupIdentifier: Add this parameter to select a SAML attribute name whose values are included as group members in the subject.
   • realmName: Use this parameter to explicitly specify the realm name to identify a SAML principal in this service provider. The default realm name is the SAML issuer name.
4. Optional: You can create one or more new samlWebSso20 elements with a different ID. For example, if you create a new element with an ID as mySP, you effectively create a new SAML SP instance that has a new AssertionConsumerService URL:

   https://<hostname>:<sslport>/ibm/saml20/mySP/acs

   Note: The ID you choose for samlWebSso20 is included in URL of the SP, including the AssertionConsumerService URL and metadata URL. The samlWebSso20 ID must be non-empty and must not contain unsafe URL characters.
5. Optional: You can configure a trust engine. The Liberty SAML SP supports two types of trust engines:
   • Metadata trust engine: Validates the signature against information that is provided in the configured IdP metadata.
   • PKIX trust engine: Validates the trustworthiness of the certificate in the signature through PKIX validation. Certificates that pass this validation are assumed to be trusted.

   Metadata is the default trust engine. If you want to use the PKIX trust engine, you need to add the PKIXTrustEngine element, and define the proper trustAnchor.

6. Optional: You can configure how to create an authenticated subject from SAML. By default the Liberty SP creates a subject from SAML assertion directly without the requirement of a local user registry, which is equivalent to the configuration mapToUserRegistry=No. The other configuration options are mapToUserRegistry=User or mapToUserRegistry=Group.
   • mapToUserRegistry=No: The SAML issuer's name is realm, and the NameID is used to create a principal name and unique security name in the subject, and no group member is included. You can configure the attributes: userIdentifier, realmIdentifier, groupIdentifier, and userUniqueIdentifier to create an authenticated subject with a customized user name, realm name, group memberships, and unique security identifier.
   • mapToUserRegistry=User: Choose this option if you want to validate a SAML user against your on-premises user registry, and create the user subject based on the on-premises registry.
   • mapToUserRegistry=Group: Choose this option if you want to validate a SAML group against your local user registry, and create a subject to contain those validated groups. This option is similar to mapToUserRegistry=No, except for group memberships are verified against the on-premises user registry.
7. Optional: You can implement the Liberty SAML SPI, com.ibm.wsspi.security.saml2.UserCredentialResolver as a user feature to dynamically map a SAML assertion to a Liberty subject.
8. Optional: You can define rules to tell the IdP how to authenticate a user by configuring one or more of the following attributes when using an SP-initiated Web SSO flow: forceAuthn, isPassive, allowCreate, authnContextClassRef, and authnContextComparisonType.
9. Optional: You can define a required NameID format in the AuthnRequest by using the nameIDFormat attribute. You can specify any NameID format that is defined in the SAML specification, or use the keyword customize to specify the custom NameId format.
10. Optional: You can configure multiple SP and IdP federation partners by creating multiple samlWebSso20 elements, and each samlWebSso20 refers to one unique authFilter element. All authFilters must exclude each other. With multiple samlWebSso20 configured, each can perform single-sign-on with its federated identity provider, and has its own authentication policy and consuming rules.
11. Optional: Add support for IdP-initiated unsolicited SSO. Liberty SAML SP supports IdP-initiated unsolicited SSO with and without the requirement of IdP metadata on-premises. If you do not have IdP metadata, or if you intend to use unsolicited SSO to federate with multiple identity providers with one Liberty SP, you must add the following configurations:
    • Configure <PKIXTrustEngine>, and import all the IdP signer certificates to the default truststore of the Liberty server, or to the trustAnchor of the PKIXTrustEngine.
    • Configure the trustedIssuers to list the issuer name of the IdP as it appears in the SAML assertion. The issuer name is used as the EntityID in the metadata.
    • If you intend to support unsolicited SSO only, you can configure SP-initiated unsolicited SSO as documented in the next step. This scenario is useful if the user's security context in the SP that is associated with SAML becomes invalid, the SP can redirect the user back to the IdP to start unsolicited SSO again automatically.
12. Optional: Add support for SP-initiated unsolicited SSO. The Liberty SAML SP uses configured IdP metadata to perform a solicited SAML AuthnRequest. It is possible for the Liberty SP to redirect unauthenticated requests to a preconfigured login application without using AuthnRequest. This scenario is useful if a business application performs pre-authentication processing before a user can authenticate to the SAML IdP, or the SAML IdP must be hidden from the Liberty SP. To configure this scenario, you add the loginPageURL attribute, and set its value to a URL that can instruct a user to authenticate to the SAML IdP.
13. Optional: Configure signature requirements with the following considerations:
    • SAML assertion. All SAML assertions must be digitally signed by the SAML IdP. In the rare case that you want to accept an unsigned assertion, you can explicitly configure wantAssertionsSigned=false.
    • The default signature algorithm is SHA256. If you must change the algorithm, use the signatureMethodAlgorithm attribute to modify it.
    • If you do not want to sign the SAML AuthnRequest, you can set authnRequestsSigned=false.
14. Optional: You can configure an SP authentication session and cookie. After SAML assertion is verified and processed, the Liberty SAML SP maintains an authenticated session between the browser and the SP without using an LTPA cookie. The authenticated session timeout is set to SessionNotOnOrAfter in the <saml:AuthnStatement> if presented, or to sessionNotOnOrAfter as configured in the server.xml file, with the default being 120 minutes. The session cookie name is automatically generated, and you can customize the cookie name by using the attribute spCookieName to specify the wanted name.

    If you want the Liberty SP to create an LTPA cookie from the SAML assertion and use the LTPA cookie for subsequent authentication requests, you can add the configuration disableLtpaCookie=false. If you want to share the LTPA cookie with other servers, you must add the configuration attribute allowCustomCacheKey="false".

    Note: If you configure disableLtpaCookie="false" and allowCustomCacheKey="false", ensure that a SAML user name is not directly authenticating to an on-premises user registry that prevents a user from having two accounts.
15. Optional: Configure the Authentication Filter.

    When the samlWeb-2.0 feature is enabled, any unauthenticated request is authenticated through one SAML SP. If you define a customized samlWebSso20 element, all authentication requests are handled by this samlWebSso20 SP instance; otherwise, all authentication is handled by the default instance defaultSP. You can use authnFilter to define which SP instance to handle the authentication request.

    For more information on configuring the authentication filter, see Authentication Filters.

16. Optional: Configure the SAML SP in a cluster.

    If application servers are cluster members, and you use a router or reverse proxy server to route your requests, then you need to perform the following tasks:

    • The router and proxy server must be configured to support session affinity.
    • Add the configuration attribute spHostAndPort to each application server. The format for the value for this attribute is (scheme)://(proxyOrRouterHost):(proxyOrRouterPort). For example, an SSL router endpoint can be specified as spHostAndPort="https://myRouter.com:443", and a non-SSL router endpoint can be specified as spHostAndPort="http://myRouter.com:80".
    • Generate an X509 certificate for signing the SAML AuthnRequest, and use this certificate on all application servers. For example, you can create a keystore to contain this certificate only, and add the KeyStoreRef to reference this keystore on all application servers.
    • If createSession="true" is not set in a cluster environment, then the following error is encountered during the stress execution:

      E CWWKS5029E: The relay state [sp_initial_KGe22fCWKG1lD9VkOMuDz0Ji8pBxFPnU] in the response from the identity provider (IdP) was not recognized.

    Here is a sample cluster configuration:

    <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>

17. Optional: Configure the SP for Single Logout

    Liberty SingleLogoutService URL takes the format https://<hostname>:<sslport>/ibm/saml20/<SP configuration ID>/slo, and can be found from the Liberty SP's metadata, https://<hostname>:<sslport>/ibm/saml20/<SP configuration ID>/samlmetadata.

    For IdP initiated single logout, no additional configuration step is required. Liberty SP listens to the logout request on the SingleLogoutService URL, and will automatically respond to the single logout request.

    Liberty server supports service provider initiated single logout. When you set the spLogout property to true, both the ibm_security_logout URL and the HttpServletRequest.logout() method are upgraded to perform SAML single logout. To set the property, code it as spLogout="true" in the server.xml file:

    <server>
    <samlWebSso20 id="sp2" ... spLogout="true" />
    ...
    </server>

    Important: To avoid trouble, regenerate the service provider metadata by starting the https://<hostname>:<sslport>/ibm/saml20/<SP configuration ID>/samlmetadata endpoint.