Configuring single sign-on for IBM Content Navigator by using SPNEGO/Kerberos on WebSphere Application Server (IBM FileNet P8)

Product documentation


Abstract

This document contains instructions for configuring single sign-on (SSO) for IBM Content Navigator with a FileNet P8 repository by using SPNEGO/Kerberos on IBM WebSphere Application Server.

Content

To configure single sign-on integration between SPNEGO/Kerberos and IBM Content Navigator, you must:


Additional resources
Troubleshooting your deployment

Step 1 - Configure your SSO environment
Before you configure single sign-on for SPNEGO/Kerberos for IBM Content Navigator, you must configure your web application server for SPNEGO/Kerberos.

Remember: You must use Windows Active Directory as your directory service to use Kerberos.


Prerequisites

  • Configure your Active Directory domain and configure all of the client workstations as members of the same domain as your Active Directory server. If you have a more complex configuration, you can configure the client workstations as members of a different domain. However, you must cross certify the servers.
  • 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.

    Important: Session replication is required for failover support in a SPNEGO/Kerberos environment. If you do not enable session replication, users cannot sign into IBM Content Navigator when there is a failover to another node in the cluster.
  • Configure WebSphere Application Server to use the domain controller (also called the KDC) for the LDAP repository. On WebSphere Application Server Network Deployment systems, complete this configuration on the deployment manager.
  • Install and configure IBM FileNet P8 Content Engine and IBM FileNet P8 Process Engine. For more information, see Product Documentation for FileNet P8.
  • Install and configure IBM FileNet Workplace XT to manage your IBM FileNet P8 workflows. For more information, see Product Documentation for FileNet P8.

Procedure
Complete the appropriate task for your environment:

Configure SSO on a single server system
To configure your single server environment for SSO, refer to the Implementing Kerberos in a WebSphere Application Server Environment IBM Redbooks publication. See the sections on configuring your web application server by using SPNEGO.

Configure SSO on a highly available cluster system
The steps in this section are appropriate for a highly available cluster environment in which IBM HTTP Server is installed on a remote server.

To configure your highly available cluster environment for SSO:

    1. Add a new user ID for the application server to the Active Directory domain. You can use any user name and password. This user ID is reserved for the WebSphere Application Server instance as the Service Principal Name (SPN) that is used to authenticate to Active Directory.

      Restriction: The user ID cannot be the same user ID as the WebSphere Application Server administrator user ID if the LDAP registry is configured and security is turned on.

    2. Assign the Service Principal Name (SPN) to the Active Directory user and map the SPN to the HTTP Server by running the following command from the Active Directory 2003 server command line:

      setspn -a HTTP/fully_qualified_HTTP_Server_host_name AD_user

      The following variables are used in this command:

      - fully_qualified_HTTP_Server_host_name is the fully qualified host name of the IBM HTTP Server.

      - AD_user is the Active Directory user ID that you created in step 1.

    3. Create the keytab file by running the following command from the command line on the Active Directory 2003 server:

      ktpass -out keyfile_name-princ HTTP/fully_qualified_HTTP_Server_host_name@AD_DOMAIN_NAME -pass password -ptype KRB5_NT_PRINCIPAL

      Important: When you enter the command, you must enter HTTP and the Active Directory domain name in all capital letters.

      The following variables are used in this command:

      - keyfile_name is the name of the keytab file name that you are creating. You can use any file name. However, it is recommended that you use the default file name, krb5.keytab. The keytab file is created in the directory from which you run the command unless you specify the full path of the file.

      - fully_qualified_HTTP_Server_host_name is the fully qualified host name of the IBM HTTP Server.

      - AD_DOMAIN_NAME is the name of the Active Directory domain. This value must be entered in all capital letters.

      - password is the password of the Active Directory user ID that you created in step 1.

      Active Directory 2000 users only. Active Directory 2003 sets RC4-HMAC as the default cryptography when you run the ktpass command. However, Active Directory 2000 does not support RC4-HMAC cryptography.

      The DES-CBC-MD5 cryptography is supported on both Windows Server 2000 and WebSphere Application Server. However, the DES-CBC-MD5 cryptography is not the default cryptography on Windows Server 2000. When you run the ktpass command on Windows 2000, you must specify the DES-CBC-MD5 cryptography.

      To run the ktpass command on Windows Server 2000, enter the following command:

      ktpass -out keyfile_name-princ HTTP/fully_qualified_HTTP_Server_host_name@AD_DOMAIN_NAME -pass password -ptype KRB5_NT_PRINCIPAL -crypto DES-CBC-MD5

      Important: When you enter the command, you must enter HTTP and the Active Directory domain name in all capital letters.

    4. Create a Kerberos configuration file. The Kerberos configuration file, krb5.conf or krb5.ini, contains all of the information that WebSphere Application Server needs to authenticate itself with Active Directory and to authenticate Kerberos clients by using the SPNEGO protocol.
      1. Copy the keytab file that you created from the Active Directory server to a directory on the application server where you will deploy IBM Content Navigator.
      2. Start WebSphere Application Server.
      3. Start the command-line utility by running the wsadmin command from the app_server_root/bin directory.
      4. At the wsadmin command prompt, change to the directory where you copied the keytab file and run the following command:

        $AdminTask createKrbConfigFile {-krbPath configuration_file_name -realm KERBEROS_REALM -kdcHost AD_host_name -dns dns_domain -keytabPath fully_qualified_keytab_path}

        The following variables are used in this command:

        - configuration_file_name is fully qualified path of the Kerberos configuration file that you are creating. The configuration file should be created in the same directory as the keytab file. The file extension depends on the operating system on which you are running WebSphere Application Server. On AIX, Linux, and Linux for System z, the configuration file must have a .conf file extension. On Windows, the configuration file must have a .ini file extension. It is recommended that you use the default file name, krb5.conf or krb5.ini.

        - KERBEROS_REALM is the Active Directory domain name. This value must be entered in all capital letters.

        - AD_host_name is the fully qualified host name of the Active Directory server.

        - dns_domain is the domain name service (DNS) of the KDC.

        - fully_qualified_keytab_path is the fully qualified path of the Kerberos keytab file.

        For example, enter:
        $AdminTask createKrbConfigFile {-krbPath C:\SSO\krb5.ini –realm ADDOMAIN.HOME.COM -kdcHost adservername.addomain.home.com -dns addomain.home.com –keytabPath C:\key\appserver1.keytab}
      5. Copy the Kerberos configuration file to the same directory on all of the other application servers in the cluster.

        Important: For each machine in the cell that will participate in the SSO configuration, you must place the Kerberos configuration file and the keytab file in the same directory. For example, for each node in the cluster, place the files in the C:\SSO directory.

    5. Configure Kerberos and SPNEGO on the deployment manager server:
      1. Open the WebSphere Application Server administrative console and go to Security > Global Security and ensure that application level security is enabled.
      2. Go to Web and SIP security and select Single sign-on (SSO). Select Enabled to enable single sign-on and enter the domain name of the KDC. Click OK.
      3. Go to Web and SIP security and select SPNEGO Web authentication. Select Enable SPNEGO to enable WebSphere Application Server to authenticate Kerberos clients by using the SPNEGO protocol. Browse to and select the keytab file and the Kerberos configuration file.
      4. Create a new SPNEGO filter. Enter the host name of the system where WebSphere Application Server is running and the name of your Kerberos realm. Select Trim Kerberos realm from principal name. Click OK.
      5. Click OK and then save your changes to the master configuration.
      6. Restart the deployment manager server and each application server in the cluster.

Step 2 - Verify your SSO configuration
To verify that SPNEGO/Kerberos is configured correctly, you must configure the web browsers on the client workstations in your environment and attempt to authenticate to the LDAP server by using SSO.

Prerequisite
Ensure that the browsers that are installed on the client workstations support SPNEGO authentication.

Procedure

  1. Log in to the client workstation by using an Active Directory user ID.
  2. Configure your web browser:
    • To configure Mozilla Firefox:
      1. Enter about:config in the address bar.
      2. In the Filter field, enter auth.
      3. Edit the value of the following parameters to point to your SSO domain:
        • network.negotiate-auth.delegation-uris
        • network.negotiate-auth.trusteduris
    • To configure Microsoft Internet Explorer:
      1. Click Tools > Internet Options > Security.
      2. Select Local Intranet.
      3. Click Sites.
      4. Click Advanced.
      5. Enter your SSO domain using the following format: *.domain_name_service.

        For example, enter: *.addomain.home.com
      6. Click Add and then click Close.
      7. Click OK to close the Local intranet window.
      8. Enable Integrated Windows Authentication. In the Internet Options window, select the Advanced tab. In the Security section, ensure that Enable Integrated Windows Authentication is selected.
      9. Restart Internet Explorer for your changes to take effect.
  3. From your web browser, connect to the snoop servlet by using the fully qualified host name of the WebSphere Application Server instance where you plan to deploy IBM Content Navigator. When SSO is correctly configured, the snoop servlet issues an authentication challenge to your web browser, which initiates the SPNEGO/Kerberos exchange.

    WebSphere Application Server Network Deployment systems: The snoop servlet is in the DefaultApplication.ear file. You must deploy the DefaultApplication.ear file before you can use the snoop servlet.

    • On a single server system, enter the host name with the following format:
      http://fully_qualified_hostname:port/snoop

      For example, enter: http://appserver1.addomain.home.com:9080/snoop

    • On a highly available cluster system, enter the host name with the following format:
      http://fully_qualified_HTTP_Server_hostname/snoop
    On the resulting page, ensure that the following statements are true:
    • In the User Principal field, your Windows user name is displayed.
    • In the Authorization section of the request headers, the value Negotiate is displayed and is followed by a long string of characters.
    For details about the information that is returned by the snoop servlet, see the following pages of the WebSphere with a side of SPNEGO white paper:
    • For single server systems, see the screen capture on page 26.
    • For highly available cluster systems, see the screen capture on page 37.

      Tip: The server name should point to the load balancer or IBM HTTP Server in a highly available cluster environment.

    If the snoop servlet runs successfully, you can configure and deploy IBM Content Navigator. If the snoop servlet does not run successfully, troubleshoot your SSO configuration before you continue. For more information, see Troubleshooting your deployment at the end of this document.


Step 3 - Configure and deploy IBM Content Navigator with Kerberos/SPNEGO
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 Kerberos/SPNEGO:
  1. Run the IBM Content Navigator Configuration and Deployment Tool. Create a new deployment on WebSphere Application Server.

    Remember: If you want to use SSO, you cannot configure the IBM Content Navigator web application to connect to IBM Content Manager or IBM Content Manager OnDemand servers.

    IBM Content Navigator, Version 2.0.1 users: Wen you complete the Connect to WebSphere Application Server task, ensure that you select the Configure IBM Content Navigator for SSO (P8 only) option. This option creates the user and group security on WebSphere Application Server when you deploy IBM Content Navigator.
  2. Run all of the configuration and deployment tasks that apply to your system. For more information, see Configuring and deploying IBM Content Navigator.

    IBM Content Navigator, Version 2.0.2 users: 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 SPNEGO/Kerberos.
  3. Restart the application server where IBM Content Navigator is deployed.

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


Step 4 - Verifying your deployment of IBM Content Navigator with SPNEGO/Kerberos
To verify that IBM Content Navigator was successfully deployed in your SPNEGO/Kerberos SSO environment, enter the following URL in your web browser to ensure that you are not prompted to provide any additional login credentials:
  • For a single server system, enter http://<fully_qualified_IBM_Content_Navigator_server_name>:<port>/navigator
  • For an HA system, enter http://<fully_qualified_HTTP_Server_name>/navigator

Troubleshooting your deployment


If you encounter a problem when IBM Content Navigator is deployed in a SPNEGO/Kerberos SSO environment on WebSphere Application Server, you can use the following resources to troubleshoot your deployment:


Your IBM Content Navigator session expires when you access IBM FileNet P8 workflows
If you do not enable cookies for IBM Content Navigator on the IBM Content Navigator web application server, you might see session expiration messages, which require you to log in again, when you work with IBM FileNet P8 workflows.

To prevent session timeouts:
  1. Open the WebSphere Application Server administrative console and select Applications > Application Types > WebSphere enterprise applications.
  2. Select the instance of the IBM Content Navigator web application that you are trying to access.
  3. Under Web Module Properties, select Session management.
  4. Select Override session management.
  5. Select Enable cookies.
  6. Click Enable cookies and specify a different name in the Cookie name field. For example, enter ICNJSESSIONID.
  7. Click OK and save your changes to the master configuration.
  8. Highly Available systems: Update the web server plug-in with the new cookie name. Under Server Types in Network Deployment Manager administrative console, click on Web servers. Click on your web server name > Plug-in properties. Update the name of the cookie. Click Apply followed by OK. Save changes to the master configuration.
  9. Restart the web application server to apply your changes.

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

Content Navigator

Software version:

2.0.1, 2.0.2

Operating system(s):

AIX, Linux, Linux on System z, Windows

Reference #:

7036837

Modified date:

2013-08-30

Translate my page

Machine Translation

Content navigation