Configuring IBM Content Navigator 2.0.3 and 3.0.x by using Security Assertion Markup Language (SAML) single sign-on on WebSphere Application Server

For configuration information for ICN 3.0.7 containers and later, refer to the following technote: https://www.ibm.com/support/pages/node/6570357

Note:

The steps described in this document are for guidance only. The steps might be different in your environment and you might need to modify them depending on your requirements. Consult your administrator for your environmental modifications. Refer to your Identity Provider documentation on how to configure SAML SSO.

To configure federated single sign-on integration between SAML and IBM Content Navigator, you must perform the following steps:

1. Configure Identity Provider Federation (IP).
2. Configure Service Provider (SP) and IBM Content Navigator.
3. Verify your deployment of IBM Content Navigator with SAML SSO.
4. Complete additional configuration steps for IBM Content Manager and IBM Content Manager OnDemand Repositories.

Before you begin

Ensure that the appropriate prerequisite software is installed and configured in your environment.

1. Install your Identity Provider (IDP). For more information, refer to your Identity Provider documentation.
2. Install and configure IBM FileNet P8 Content Platform Engine. For more information, see the Product Documentation for Content Platform Engine.

If you plan to use the fully qualified names of servers to access your systems through federated SSO by using SAML, ensure that the servers and web application servers are configured to use a fully qualified name wherever required.

For the latest support information, see the IBM Content Navigator Software Product Compatibility Report for your installed version of IBM Content Navigator.

Step 1 - Configure Identity Provider Federation

1. Configure IDP Federation by following the configuration steps in your Identity Provider documentation.
2. Export Federation Identity metadata.

Step 2 - Configure Service Provider (SP) and IBM Content Navigator

For more information, refer to SAML web single sign-on in the WebSphere documentation.

This step consists of the following tasks:

Task 1:

Enable WebSphere to use the SAML web SSO feature. Follow the instructions in Enabling your system to use the SAML web single sign-on (SSO) feature.

Install the SAML ACS application.

Enable SAML TAI.

Task 2:

Configure and deploy IBM Content Navigator for SAML SSO.

Before you begin:

Install the IBM Content Navigator software, but do not configure or deploy the IBM Content Navigator web application.

Procedure:

To configure IBM Content Navigator for federated SSO by using SAML

Important:

• When you run the IBM Content Navigator Configuration and Deployment tool tasks, enter the HTTPS proxy protocol, not the HTTP proxy protocol.

• When you run the Configure the IBM Content Navigator Web Application task, ensure that you select Application server authentication for the IBM Content Navigator authentication option. This option configures IBM Content Navigator for federated SSO by using SAML.

1. Run the IBM Content Navigator Configuration and Deployment Tool. Create a new deployment on the WebSphere Application Server.
2. Run all of the configuration and deployment tasks that apply to your system. For more information, see Configuring and deploying IBM Content Navigator in the IBM Content Navigator documentation.
3. Restart the application server where IBM Content Navigator is deployed.

Highly available cluster systems:

Restart the IBM Content Navigator cluster, the web server, and the node agent for each node in the cluster.

Task 3:

Configure SAML TAI custom properties.

Refer to SAML web single sign-on (SSO) trust association interceptor (TAI) custom properties in the WebSphere documentation for more details.

1. Create the following custom properties for the Service Provider.

   The values shown in this table are examples only.

   Name	Value
   sso_1.sp.acsUrl	https://FQNservername.mydomain.com:port/samlsps/acs
   sso_1.sp.idMap	localRealm
   sso_1.sp.login.error.page	https://FQNservername.mydomain.com:port/sps/SAMLforP8/saml20/logininitial?NameIdFormat=Email&PartnerID=https://FQNservername.mydomain.com:port/samlsps/acs&Target=https://FQNservername.mydomain.com:port/navigator
   sso_1.sp.filter	request-url%=navigator

   In the table, FQNservername.mydomain.com represents the fully qualified server name (single-server environments) or load balancer name (HA environments).

2. Import the Identity Provider metadata that was created earlier in Steps 1-2. You can use the wsadmin command-line utility described in the Importing SAML identity provider (IdP) partner metadata using the wsadmin command-line utility section of the WebSphere documentation.

   This step adds the IP-related custom properties.

   The SAML TAI custom properties list should look similar to the data in the following table:

   Name	Value
   sso_1.sp.acsUrl	https://FQNservername.mydomain.com:port/samlsps/acs
   sso_1.sp.idMap	localRealm
   sso_1.sp.login.error.page	https://FQNservername.mydomain.com:port/sps/SAMLforP8/saml20/logininitial?NameIdFormat=Email&PartnerID=https://myproxyserver.mydomain.com/samlsps/acs&Target=https://FQNservername.mydomain.com:port
   sso_1.sp.filter	request-URL%=navigator
   sso_1.idp_1.certAlias	IBM Tivoli Federated Identity Manager
   sso_1.idp_1.entityID	https://FQNservername.mydomain.com:port/sps/SAMLforP8/saml20
   sso_1.idp_1.singleSignOnUrl	https://FQNservername.mydomain.com:port/sps/SAMLforP8/saml20/login

Task 4:

Export the WebSphere service provider metadata by following the instructions in this section of the WebSphere documentation: Exporting SAML web service provider metadata using the wsadmin command-line utility

Task 5:

Configure the partner service to your Identity Provider Federation and import the Service Provider metadata created in the previous task. In our example using the Tivoli Federated Identity Manager Identity Provider, the following section in the documentation describes how to create a Partner:

Adding a partner to your WS-Federation single sign-on federation

Restart the Identity Provider application server and the Service Provider application server where IBM Content Navigator is deployed.

Highly available cluster systems: Restart the IBM Content Navigator cluster, the web server, and the node agent for each node in the cluster.

Step 3 - Verify your deployment of IBM Content Navigator with SAML SSO

1. From a client machine, open a browser window and enter the following URL:

   https://FQservername:port/navigator

   Where, FQservername is the fully qualified name of the server where IBM Content Navigator is deployed (single-server environments) or the load balancer name (HA environments).

   You are redirected to the Security Identity Manager login page and, in this example, to the Federated Identity Manager SAML login page.

2. Log in to IBM Content Navigator with LDAP credentials. The ICN desktop loads for the user.

Step 4 - Additional configurations for IBM Content Manager and IBM Content Manager OnDemand Repositories with Single Sign-on

IBM Content Manager Configurations

If you are planning to connect to an IBM Content Manager repository from an IBM Content Navigator desktop that is configured with SSO and want to avoid an extra login to that repository, you need to configure Content Manager with trusted logins. Refer to the following technote for configuration steps or to the Content Manager documentation topic “Enabling Single Sign-on”:

https://www.ibm.com/support/pages/configuring-single-sign-ibm-content-navigator-ibm-content-manager

IBM Content Manager OnDemand Configurations

If you are planning to connect to an IBM Content Manager OnDemand repository from an IBM Content Navigator desktop that is configured with SSO and want to avoid an extra login to that repository, you need to configure Content Manager OnDemand server with SSO. Refer to the following technote for further configuration details:

https://www.ibm.com/support/pages/single-sign-sso-ibm-content-navigator-icn-and-ibm-content-manager-ondemand-cmod

Troubleshooting your Deployment and Known Issues

To troubleshoot issues, enable SAML tracing on both the identity provider and the service provider by following the documentation for these products.

On SP WebSphere

:com.ibm.ws.security.web.saml.*=all

Link to the WebSphere MustGather information: https://www.ibm.com/support/pages/mustgather-web-single-sign-problems-websphere-application-server

Configuring a SAML SSO environment to prevent a desktop reload

In a SAML environment, the Tivoli Federated Identity Manager 6.2.2 Identity Provider server has a default session timeout of 120 minutes. The IBM Content Navigator WebSphere Application Server session has a default timeout value of 30 minutes. If the IBM Content Navigator WebSphere Application Server session expires and the SAML IdP server token has not expired, the user's IBM Content Navigator desktop reloads and temporary data in the IBM Content Navigator desktop might be lost. For example, if a user selects a document and enters a document name, and then the session expires, the desktop reloads and the user must re-select the document and re-enter the document name.

To prevent your user desktops from reloading, complete the following steps to configure the WebSphere Application Server session timeout:

1. Log in to the WebSphere Application Server administration console as an administrator. If IBM Content Navigator is a cluster, log in to the DMGR console server that manages the IBM Content Navigator cluster.
2. Open the list of IBM Content Navigator servers, Servers > All servers.
3. Open the session setting of the IBM Content Navigator server, IBM Content Navigator Server > Session management.
4. Change the session timeout value to match, or be greater than, the session timeout value on the Tivoli Federated Identity Manager server. The default timeout value in Tivoli Federated Identity Manager 6.2.2 is two hours.

Enabling cache replication in a SAML SSO environment

To ensure that your users can work with IBM Content Navigator in a browser without interruptions, it is recommended that you enable cache replication for every node of an IBM Content Navigator cluster in a SAML environment.

To enable cache replication, complete the following steps:

1. Log in to the DMGR console of the IBM Content Navigator cluster using WebSphere Application Server administrator credentials.
2. Open the IBM Content Navigator node server, Servers > Application Servers > your_node_server_name. The properties for the selected server are shown. In the Container Setting section, expand Container Services. Click Dynamic Cache Service.
3. If cache replication does not exist, click Create a new replication domain in the Consistency settings section.
4. Select Enable cache replication in the Consistency settings section. Set the following three properties:
   • Full group replication domain: The cache replication domain name that was created in Step 3.
   • Replication type: Select Both push and pull.
   • Push frequency: Set to 0 seconds.