Configuring single sign-on for IBM Content Navigator by using CA SiteMinder on WebSphere Application Server

The steps in this document are for guidance only. The steps to successfully configure single sign-on for IBM Content Navigator by using CA SiteMinder might be different in your environment. Talk to your web application server administrator to determine if you need to modify the steps based on your environment.

To configure single sign-on (SSO) between CA SiteMinder and IBM Content Navigator on WebSphere Application Server, you must:

1. Configure your SSO environment
   1. Install and configure CA SiteMinder Policy Server
   2. Install and configure CA SiteMinder Web Agent
   3. Install and configure CA SiteMinder Application Server Agent for WebSphere
2. Verify your SSO configuration
3. Configure and deploy IBM Content Navigator with SiteMinder SSO
4. Prevent errors when opening documents in the FileNet viewer

Before you begin
If you plan to use CA SiteMinder SSO, you must be aware of the following restrictions:

• You can use IBM Content Navigator to connect to only IBM FileNet P8 repositories. If you configure the IBM Content Navigator web application to connect to IBM Content Manager or IBM Content Manager OnDemand repositories, you cannot use single sign-on.
• IBM Content Navigator for Microsoft Office is not supported if you deploy IBM Content Navigator with CA SiteMinder SSO. If you use IBM Content Navigator for Microsoft Office, you must deploy IBM Content Navigator in a non-SSO environment or in an SSO environment that supports IBM Content Navigator for Microsoft Office.
  
  For more information, see the Hardware and software requirements for IBM Content Navigator for your installed version of IBM Content Navigator.

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

• Install WebSphere Application Server and enable application level security.
  
  WebSphere Application Server Network Deployment systems: Install the WebSphere Application Server Network Deployment Manager deployment manager and configure application level security. Configure your system according to your needs and requirements.

• Install and configure IBM FileNet P8 Content Engine and IBM FileNet P8 Process Engine. For more information, see http://www.ibm.com/support/docview.wss?uid=swg27021508" target="_blank">Product Documentation for FileNet P8.
• Install and configure IBM FileNet Workplace XT to manage your IBM FileNet P8 workflows. For more information, see http://www.ibm.com/support/docview.wss?uid=swg27021508" target="_blank">Product Documentation for FileNet P8.

In addition, if you plan to use the fully qualified names of servers to access your systems through CA SiteMinder SSO, ensure that your servers and web application servers are configured to use a fully qualified name wherever the fully qualified name is required.

Step 1 - Configure your SSO environment

To configure your SSO environment for IBM Content Navigator, you must install and configure the following CA SiteMinder components:

• CA SiteMinder Policy Server
• CA SiteMinder Web Agent
• CA SiteMinder Application Server Agent for WebsSphere

The following sections include the high level steps for installing and configuring the CA SiteMinder components. For detailed steps on installing CA SiteMinder Policy Server, see the CA SiteMinder documentation on the CA support site.

This document includes links to the CA SiteMinder Release12 Service Pack 3 documentation.

Step 1a - Install and configure CA SiteMinder Policy Server

Install CA SiteMinder Policy Server as a stand-alone server.
 

• Prerequisites:
  See the following topics on the CA SiteMinder support site:
  • Policy Server Installation Requirements
  • Policy Server Considerations for Windows systems
  • Policy Server Considerations for UNIX systems
  
  Procedure:
  1. Install Policy Server. See the appropriate instructions for installing Policy Server on the SiteMinder support site:
     • Installing the Policy Server on Windows Systems
     • Installing the Policy Server on UNIX Systems
  2. Install the Policy Server Administrative user interface. See Installing the Administrative UI on the SiteMinder support site.
  3. Prepare Policy Server for the Web Agent and the Application Server Agent installation. See Prepare for Web Agent Installation on the SiteMinder support site.
     
     Tip: Review the definitions in Prepare for Web Agent Installation for the following configuration objects: host configuration objects and agent configuration objects.
     
     Important: You must set up Policy Server for communication with the Web Agent before you take the following actions:
     • • Install a Web Agent or Application Server Agent for WebSphere
       • Register a trusted host from the systems where you install a Web Agent or Application Server Agent for WebSphere
          
     • a. Create host configuration objects for IBM Content Navigator. See Create a Host Configuration Object on the SiteMinder support site.
       
       A host configuration object defines the communication between the trusted host and the Policy Server after the initial connection between the systems is made.
       
       Create the following host configuration objects:
       • A host configuration object for your HTTP proxy server
       • A host configuration object for WebSphere Application Server
         
         Highly available cluster systems: You can use the same host configuration object for all of the nodes in the cluster.
       b. Create agent objects for IBM Content Navigator. See Create an Agent Object to Establish a Web Agent Identity on the SiteMinder support site.
       
       Create the following agent objects:
       • An agent object for the Web Agent that operates with the web application server where your HTTP proxy server is deployed
       • An agent object for the Application Server Agent that operates with the web application server where you plan to deploy IBM Content Navigator
         
         Highly available cluster systems: You can use the same agent object for all of the nodes in the cluster.
          
       c. Create agent configuration objects for IBM Content Navigator. See Set the Configuration Parameters in the Configuration Object on the SiteMinder support site.
       
       Create the following agent configuration objects:
       • An agent configuration object for your HTTP proxy server
         
         Modify the following parameters for your HTTP proxy server.
         
         Important: The following parameters are recommended but not required. You can modify the parameters according to your system requirements.
         • ProxyAgent - Set to Yes
         • SecureApps - Edit the #SecureApps entry, delete the leading #, and set the value to No
         • CookieDomain - Enter the network domain in which the web agent for the HTTP proxy server is running. Include a leading period, for example: .gcbi.com.au.
         • UseHTTPOnlyOnlyCookies - Edit the #UseHTTPOnlyOnlyCookies entry, delete the leading #, and set the value to No.
       • An agent configuration object for the web application server where you plan to deploy IBM Content Navigator.
         
         Highly available cluster systems: If WebSphere Application Server is not installed in the same directory on the Deployment Manager and on each node in the cluster, you must create this agent configuration object for each node in the cluster. If WebSphere Application Server is installed in the same directory on each node in the cluster, you can use the same agent configuration object for all of the nodes in the cluster.
         
         Modify the following parameters for your web application server.
         
         Important: The following parameters are recommended but not required. You can modify the parameters according to your system requirements.
         • ChallengeForCredentials - Set to Yes
         • ProxyAgent - Set to Yes
         • ProxyTrust - Set to Yes
       d. Configure your user directory. See User Directories on the SiteMinder support site.
       
       e. Create authentication schemes for IBM Content Navigator. See Authentication Schemes on the SiteMinder support site.
       
       Create the following authentication schemes:
       • Create a new https://support.ca.com/cadocs/0/CA%20SiteMinder%20r12%20SP3-ENU/Bookshelf_Files/HTML/idocs/index.htm?toc.htm?345842.html" target="_blank">HTML form authentication scheme with the following parameters:
         • Authentication Scheme Type - HTML Form Template
         • Web Server Name - The fully qualified name of the HTTP proxy server
         • Port - 80
       • Create a new anonymous authentication scheme with the following parameters:
         • Authentication Scheme Type - Anonymous
         • User DN - Enter the distinguished name of the SiteMinder guest user, for example: cn=smuser,cn=Users,dc=gcbi,dc=com,dc=au
       f. Create the policy domain for IBM Content Navigator. See How to Configure a Policy Domain on the SiteMinder support site.
       
       Add the user directory that you configured in step 3d to the policy domain.
       
       g. Create realms for IBM Content Navigator. See Configure a Realm Protected by a SiteMinder Web Agent on the SiteMinder support site.
       
       Create the following protected realms:
       • Create a realm for the HTTP proxy server with the following parameters:
         • Agent - Select the agent object that you created for the HTTP proxy server in step 3b.
         • Resource filter - /navigator
         • Authentication scheme - Select the authentication scheme that you configured in step 3e.
       • Create a realm for the application server where you plan to deploy IBM Content Navigator with the following parameters:
         • Agent - Select the agent object that you created for the web application server where you plan to deploy IBM Content Navigator in step 3b.
         • Resource filter - /navigator
         • Authentication scheme - Select the authentication scheme that you configured in step 3e.
       h. Create rules for IBM Content Navigator. See Configure a Rule for Web Agent Actions and the Web Agent Configuration Guide on the SiteMinder support site.
       
       Create the following rules:
       • • Create a rule for the HTTP proxy server with the following parameters:
           • Resource - /*
           • Allow/Deny - Allow access to the protected resource
           • Enable/Disable - Enable access to the protected resource
           • Actions - Add the following web agent actions to the Action List:
             • Get
             • Post
         • Create a rule for the web application server where you plan to deploy IBM Content Navigator with the following parameters:
           • Resource - /*
           • Allow/Deny - Allow access to the protected resource
           • Enable/Disable - Enable access to the protected resource
           • Actions - Add the following web agent actions to the Action List:
             • Get
             • Post
       i. Create policies for IBM Content Navigator. See How to Configure a Policy on the SiteMinder support site.
       
       Create the following policies:
       • Create a policy for the HTTP proxy server. Add the rule that you created for the HTTP proxy server in step 3h to the policy.
       • Create a policy for the web application server where you plan to deploy IBM Content Navigator. Add the rule that you created for the web application server where you plan to deploy IBM Content Navigator in step 3h to the policy.

Step 1b - Installing and configuring CA SiteMinder Web Agent
Install CA SiteMinder Web Agent on an HTTP proxy server.

Prerequisites

1. Install the unlimited strength encryption security policy files on the HTTP proxy server:
   
   Highly available cluster systems: Complete the following steps for each node in the cluster.
   1. Upgrade the Java Runtime Environment (JRE) that is used by the HTTP proxy server. Ensure that the version supports unlimited key strength in the Java Cryptography Extension (JCE) package.
      
      Important: If you do not complete this task, the host registration task fails during the SiteMinder Agent installation, and WebSphere Application Server will not start after the SiteMinder Agent is installed in WebSphere Application Server.
   2. Download the unlimited strength encryption security policy files from the IBM Software Support site.
   3. Stop the HTTP server where you are installing the unlimited strength encryption security policy files.
   4. Make a backup copy of the following files in the HTTPServer\java\jre\lib\security subdirectory of the HTTP proxy server installation directory:
      • US_export_policy.jar
      • local_policy.jar
   5. Copy the unlimited strength encryption security policy JAR files that you downloaded into the HTTPServer\java\jre\lib\security subdirectory of the HTTP proxy server installation directory.

• Procedure:
  1. Configure the HTTP proxy server as a reverse proxy server:
     1. Stop the HTTP service
     2. Open the configuration file for your HTTP proxy server. For example, on IBM HTTP Server, the httpd.conf configuration file is located in the conf subdirectory of the IBM HTTP Server installation directory.
     3. Remove the comment symbols from the beginning of the following lines in the LoadModule section:
        • LoadModule headers_module modules/mod_headers.so
        • LoadModule proxy_module modules/mod_proxy.so
        • LoadModule proxy_http_module modules/mod_proxy_http.so
     4. Add the following lines to the end of the configuration file.
        
        Important: IBM Content Navigator supports only transparent junctions.
        
        When you add the lines to the configuration file, make the following replacements:
        -
        - http:// proxyservername is the fully qualified host name of your HTTP proxy server.
        - http:// appservername is the fully qualified host name of the web application server where you plan to deploy IBM Content Navigator
        - http:// httpservername is the fully qualified host name of the HTTP server or the load balancing server.
        
         
        • For stand-alone web application servers, add the following lines:
          
          
          ### Proxy Configuration
ProxyRequests Off
<Proxy http:// proxyservername/*>
Order deny,allow
Allow from all
</Proxy>
<Location /*>
ProxyPass http:// appservername:9080/ ProxyPassReverse http:// appservername:9080/
</Location>
          
           
        • For highly available cluster environments, add the following lines:
          
          
          ### Proxy Configuration
ProxyRequests Off
<Proxy http:// proxyservername/*>
Order deny,allow
Allow from all
</Proxy>
<Location /*>
ProxyPass http:// httpservername/
ProxyPassReverse http:// httpservername/
</Location>
           
  2. Install CA SiteMinder Web Agent. See the Web Agent Installation Guide on the SiteMinder support site.
     
     Important: It is strongly recommended that you register the HTTP server as a trusted host before you configure CA SiteMinder Web Agent. See Register a Trusted Host in GUI or Console Mode on the SiteMinder support site.
  3. Configure CA SiteMinder Web Agent. See the https://support.ca.com/cadocs/0/CA%20SiteMinder%20r12%20SP3-ENU/Bookshelf_Files/HTML/idocs/index.htm?toc.htm?agent-guide.html" target="_blank">Web Agent Configuration Guide on the SiteMinder support site.

Step 1c - Installing and configuring CA SiteMinder Application Server Agent for WebSphere

You must install CA SiteMinder Application Server Agent for WebSphere on the web application server where you plan to install IBM Content Navigator.

The SiteMinder Agent for IBM WebSphere resides in a WebSphere Application Server and enables you to extend the SiteMinder environment to protect WebSphere-hosted resources (specifically resources in the Web and EJB containers).

For more information, see CA SiteMinder for IBM WebSphere Agent Guide (R12.0 SP2) on the SiteMinder Support Site.

• Prerequisites
  1. Ensure that you have completed all of the steps in the previous sections of this document. See Preconfiguring Policy Objects for the SiteMinder Agent on the SiteMinder Support Site.
  2. Install the unlimited strength encryption security policy files on the web application server where you plan to deploy IBM Content Navigator:
     
     Highly available cluster systems: Complete the following steps for each node in the cluster.
     1. Upgrade the Java Runtime Environment (JRE) that is used by WebSphere Application Server. Ensure that the version supports unlimited key strength in the Java Cryptography Extension (JCE) package.
        
        Important: If you do not complete this task, the host registration task fails during the SiteMinder Agent installation, and WebSphere Application Server will not start after the SiteMinder Agent is installed in WebSphere Application Server.
     2. Download the unlimited strength encryption security policy files from the IBM Software Support site.
     3. Stop WebSphere Application Server on the server where you are installing the unlimited strength encryption security policy files.
     4. Make a backup copy of the following files in the AppServer\java\jre\lib\security subdirectory of the WebSphere Application Server installation directory:
        • US_export_policy.jar
        • local_policy.jar
     5. Copy the unlimited strength encryption security policy JAR files that you downloaded into the AppServer\java\jre\lib\security subdirectory of the WebSphere Application Server installation directory.
  Procedure:
  1. Install the Application Server Agent for WebSphere. See Installing and Upgrading the Agent on the SiteMinder Support Site.
     
     Highly available cluster systems: Install the Application Server Agent for WebSphere on the deployment manager server and on each node in the cluster. It is strongly recommended that you install the Application Server Agent for WebSphere in the same directory on the the deployment manager server and on each node in the cluster.
  2. Configure the Application Server Agent for WebSphere, SiteMinder-side. See Configuring the SiteMinder Agent, SiteMinder-Side on the SiteMinder Support Site.
  3. Configure the Application Server Agent for WebSphere, WebSphere-side. See Configuring the SiteMinder Agent, WebSphere-Side on the SiteMinder Support Site.
     1. Create a Java system environment variable called smasa.home that points to the Application Server Agent installation directory. For example, smasa.home=c:\smwasasa.
        
        Highly available cluster systems: Create the smasa.home Java system environment variable on each application server.
     2. Configure the SiteMinder TAI in WebSphere. See Configuring the SiteMinder TAI in WebSphere on the SiteMinder Support Site.
        
        Highly available cluster systems: Complete this step in the WebSphere Application Server Network Deployment deployment manager server administrative console.
     3. Add a web server in the WebSphere Application Server administrative console. For more information, see the WebSphere Application Server documentation for creating web servers.
        
        Highly available cluster systems: By default, a web server is included in your configuration as part of the highly available cluster environment setup.

Step 2 - Verify your SSO configuration

To verify that SiteMinder SSO is configured correctly on your system you can use a snoop server.

See one of the following resource for more information about using a snoop server to verify that SiteMinder SSO is configured correctly:

• https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=e8206aad-10e2-4c49-b00c-fee572815374#fullpageWidgetId=Wf2c4e43b120c_4ac7_80ae_2695b8e6d46d&file=1296eb67-201f-4f61-93a7-428be49546bd" target="_blank">Configuring the SiteMinder TAI in WebSphere on the IBM developerWorks site.
• Verifying SiteMinder Agent Installation and Configuration Verifying SiteMinder Agent Installation and Configuration on the SiteMinder Support Site.

Step 3 - Configuring and deploying IBM Content Navigator with SiteMinder SSO

After you configure your environment for SSO, you can install and deploy IBM Content Navigator.
 

• Prerequisites
  Complete all of the tasks in Installing IBM Content Navigator. 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 SSO by using SiteMinder:
  1. Run the IBM Content Navigator Configuration and Deployment Tool. Create a new deployment on WebSphere Application Server.
  2. Run all of the configuration and deployment tasks that apply to your system. For more information, see http://www.ibm.com/support/knowledgecenter/SSEUEX_2.0.3/com.ibm.installingeuc.doc/eucde000.htm" target="_blank">Configuring and deploying IBM Content Navigator.
     
     Important: 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 CA SiteMinder SSO.
     
     Remember: If you want to use SiteMinder SSO, you cannot configure the IBM Content Navigator web application to connect to IBM Content Manager or IBM Content Manager OnDemand repositories.
  3. Restart the application server where IBM Content Navigator is deployed.
     
     Highly available cluster systems: Restart the IBM Content Navigator cluster, the webserver and the node agent for each node in the cluster.

Step 4 - Preventing errors when opening documents in the FileNet viewer

If IBM Content Navigator is configured to open documents in the FileNet viewer, you must edit the serverSupportsHeadRequestMethod parameter to prevent users from encountering an error when opening documents.

If you do not edit the serverSupportsHeadRequestMethod parameter, users see the following message when they open documents:

Error.ji.net.jiServerException: Server did not respond with OK
Error: IO error: null

Important: If you plan to deploy IBM Content Navigator in a highly available cluster, you must complete the following steps for each node in the cluster.

To prevent users from encountering an error when opening documents:

1. Open the ivewpro.streamer.properties file, which is in the config subdirectory of the IBM Content Navigator installation directory.
2. Change the value of the serverSupportsHeadRequestMethod parameter to false.
3. Save your changes to the ivewpro.streamer.properties file.