Implement SAML 2.0 for HCL WebSphere Portal

1. Overview
2. Implementation Tasks
3. Error 401 after authentication
4. More information

Overview

WebSphere Application Server v8.5+ only supports IdP initiated SAML SSO. For SP initiated SSO WebSphere is not able to produce the required SAMLRequest as defined by SAML standards for SP initiated SSO.

1. User requests a WAS secured resource.

2. If the user is not already authenticated a SAML TAI redirects the user to the IdP URL.

3. Cookie WasSamlSpReqURL is generated on the browser to identify the URL of the originally requested resource.

4. IdP authenticates the user and then sends the user back to WAS. The redirect is to a SAML Application deployed on WAS called Assertion Consumer Service (ACS).

5. ACS is able to verify and manage the SAMLResponse message that IdP generates and includes in the redirect. This application creates the authenticated session on WAS and the LTPA cookie for the user specified in the message.

6. If WasSamlSpReqURL cookie is available, redirect the user to the original protected resource as authenticated user, otherwise redirect the user to the URL configured in the TAI.

Using this approach will prevent users being requested to select the right link to be redirected to WAS.

Tasks

1. Configure SAML TAI

   1. From the WAS admin console select...
      Security | Global security | Web and SIP security | Trust association | General Properties | Enable trust association (uncheck)

   2. Select...
      Interceptors | New

      ...and for Interceptor class name, set...

      com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor

   3. Under Custom properties, fill in the following custom property information:
      sso_1.sp.acsUrl = https://<hostname>:<sslport>/samlsps/wps/
      sso_1.sp.filter = request-url%=/wps/myportal
      sso_1.sp.idMap = localRealm

      Click OK.

   4. Install the SAML Assertion Consumer Service (ACS) application

      From the WAS admin console go to...

      Applications | New Application | New Enterprise Application | Remote file system

      ...and select...

      C:\IBM\WebSphere\AppServer\installableApps\WebSphereSamlSP.ear

   5. Go to...
      Security | Global security | Custom properties

   6. Look for...
      com.ibm.websphere.security.DeferTAItoSSO

      ...and replace...

      com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl

      ...with...

      com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor

   7. Restart WebSphere Application Server.

   
   

2. Add the identity provider (IDP) as a partner

   1. From the IdP, export Metadata in XML format

      Start the wsadmin command-line utility

      /opt/IBM/WebSphere/AppServer/bin/wsadmin.sh -lang jython

   2. At the wsadmin prompt, enter the following command:
      AdminTask.importSAMLIdpMetadata(‘-idpMetadataFileName /path/to/IdPMetaDataFile.xml -idpId 1 -ssoId 1 -signingCertAlias <idpAlias>’)

      IdpAlias is any alias name that we specify for the imported certificate.

      Save and exit...

      AdminConfig.save()
      quit

   3. Restart the WebSphere Application Server.

   
   

3. Add IdP realms as Trusted Realm

   For each Identity provider used with the WebSphere Application Server service provider, we must grant inbound trust to all the realms that are used by the identity provider.

   Log on to the WebSphere Application Server administrative console and click... Security | Global security | | user account repository | Configure | Trusted authentication realms – inbound | Add External Realm

   Fill in the external realm name.

   Click OK and Save changes to the master configuration.

   
   

4. Export Data for IdP

   Each identity provider used with the WebSphere Application Server service provider needs to be configured to add the service provider as an SSO partner. The procedure for adding the service provider partner to an identity provider depends on the specific identity provider. Refer to the documentation of the identity provider for instructions on how to add a service provider partner for SSO.

   If an identity provider can use a metadata file to add the service provider as a federation partner, we can use the wsadmin command-line utility to export the service provider metadata:

   /opt/IBM/WebSphere/AppServer/bin/wsadmin.sh -lang jython
   AdminTask.exportSAMLSpMetadata(‘-spMetadataFileName <SpMetaDataFile> -ssoId 1’)

   ...where IdpMetaDataFile is the full path name of the SP metadata file generated by the script and that should be used by the IdP.

   
   

5. Configure the WAS security context

   Log on to the WebSphere Application Server administrative console and go to...

   Security | Global security | Web and SIP security | Trust association | com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor

   Add required Custom properties to have following data in place (some of them should be already there)

   Name	Value
   sso_1.sp.acsUrl	https://<hostname>:<sslport>/samlsps/wps/
   sso_1.sp.idMap	localRealm
   sso_1.idp_1.certAlias	<idpAlias>
   sso_1.idp_1.EntityID	https://<idphostname>/<idp required path>
   sso_1.idp_1.SingleSignOnUrl	https://<idphostname>/saml/idp/profile/redirectorpost/sso
   sso_1.sp.login.error.page	Same then sso_1.idp_1.entityID
   sso_1.sp.filter	request-url%=/wps/myportal

   
   

6. Check login attribute

   The IdP will pass in the SAMLrequest the userID to be authenticated. This ID has to be one of the userID values available for standard Portal login.

   Log on to the WebSphere Application Server administrative console and click...

   Security | Global security | user account repository | Configure

   Click on the LDAP where users are stored.

   Check and eventually add attributes (semicolon separation) that are used for login in Federated repository properties for login field. In our case, because IdP passes the email address as userID we set following values:

   Federated repository properties for login = uid;mail

   Click OK and Save

   
   

7. Enable TAI

   After this step the only way to be authenticated to Portal is though IdP and it will work only for users that have a matching email in the Portal User Registry.

   Log on to the WebSphere Application Server administrative console and select...

   Security | Global security | Web and SIP security | Trust association | General Properties | Enable trust association | OK | Save

   Restart Application Server

Error 401 on Portal Server after authentication via SAML

When performing authentication via SAML and being redirected to the URL for the page requested, after login, the customer is receiving a 401 error and/or a message to input login and password again.

Cause

Possible causes are:

1. login and logout cookies have different paths, thus preventing cookies to be cleared in a logout, so when a login occurs again, it may not work and/or get a 401 error (JSESSIONID and LtpaToken2 should be cleared during each logout and prior to any login).

2. cookies for different applications have the same name

3. The HTTP protocol specifies that cookies are uniquely identified by name+domain+path. If paths do not match between the login and logout cookies, the browser does not clear the cookies from its cookie store.

Resolution

JSESSIONID and LtpaToken2 should be cleared during each logout and prior to any login (e.g. if a session timeout occurs). Clearing the cookies with the External Security Manager is development task (custom logout URL; ISAM-hosted login page). HCL and IBM do not support assistance with custom logout mechanisms.

To clear cookies on logout, use a portal logout URL in the theme instead of the one hard-coded to the ESM logout page. In the default Portal 85 theme, this is from commonActions.jsp and looks like this:

<li id="wpthemeLogout">

    <a id="logoutlink" 
       href="${fn:escapeXml(wp.selectionModel.selected.urlGeneration.logout.keepNavigationalState)}">
           <portal-fmt:text key="link.logout" bundle="nls.engine"/> </a>

</li>

Also you will need to make sure that cookies for different applications have different names to avoid conflicts.

More information

1. Web security concepts and considerations for HCL Digital Experience
2. Prerequisite setup for portal transient user support with IBM Application Server SAML TAI
3. Assertion Consumer Service (ACS)
4. Configure transient users
5. Enable the system to use the SAML web single sign-on (SSO) feature
6. Understand the SAML trust association interceptor for the WebSphere Application Server
7. Step by step guide to implement SAML 2.0 for Portal 8.5