IBM Support

Configuring single sign-on for IBM Content Navigator using SPNEGO/Kerberos on WebSphere Application Servers

Product Documentation


Abstract

This document contains instructions for configuring single sign-on (SSO) for IBM Content Navigator using SPNEGO/Kerberos on IBM WebSphere Application Servers.

Content

To configure single sign-on integration between SPNEGO/Kerberos and IBM Content Navigator follow these steps:
  1. Configure your SSO environment
  2. Verify your SSO configuration
  3. Configure and deploy IBM Content Navigator with SPNEGO/Kerberos SSO.
  4. Verify your deployment of IBM Content Navigator with SPNEGO/Kerberos SSO.
  5. Complete the additional configuration steps for IBM Content Manager and IBM Content Manager OnDemand Repositories
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 ND 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 in to 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 repositories for IBM Content Navigator, such as, IBM FileNet P8 Content Platform Engine, IBM Content Manager, or IBM Content Manager OnDemand. For more information, see the relevant repository product documentation.

For more information on supported configurations, see the Hardware and software requirements for IBM Content Navigator for your installed version of IBM Content Navigator. Use the SPCR site to generate the required report: http://www.ibm.com/software/reports/compatibility/clarity/index.html.
After you configure your environment for SSO, you can install and deploy IBM Content Navigator. Refer to IBM Content Navigator Installation instructions in the online documentation.

Complete all tasks in Installing IBM Content Navigator paragraph in the online documentation. 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. Complete the appropriate tasks to configure SSO in 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 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 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.
         

        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.

        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.

        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 the 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.
        6. 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.
  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 support SPNEGO log ons, refer to the SPNEGO documentation for more details. Following are examples of the steps required for Mozilla Firefox and Microsoft Internet Explorer.

      • 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. Refer to the following link on How to install the Snoop servlet with the WebSphere Integrated Solutions Console

      • 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 link WebSphere Application Server - Default Application

    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 at the end of this document.

  3. Configure and deploy IBM Content Navigator with Kerberos/SPNEGO SSO
    1. Run the IBM Content Navigator Configuration and Deployment Tool. Create a new deployment on WebSphere Application
    2. Run all of the configuration and deployment tasks that apply to your system. For more information, see Configuring and deploying IBM Content Navigator paragraph in IBM Content Navigator online documentation.

      NOTE: 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.
    4. Highly available cluster systems: Restart the IBM Content Navigator cluster, the IBM HTTP Server, and the node agent for each node in the cluster.
  4. Verifying your deployment of IBM Content Navigator with SPNEGO/Kerberos SSO

    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
  5. Additional configurations for IBM Content Manager and/or 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 Content Navigator desktop that is configured with Kerberos SSO and want to avoid an additional login to that repository, you need to configure Content Manager with trusted login. Refer to the following technote for configuration steps or to the Content Manager online 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 Content Navigator desktop that is configured with Kerberos SSO and want to avoid an additional 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

Limitation

The following limitation applies to the IBM Edit Service client.

If the Edit Service client is installed with the "for all users" option on a shared workstation and single sign on is configured, only one user can run the Edit Service client at a time. The Edit Service client uses a single workstation port (13553) to process requests. If additional users are running the Edit Service client on the same workstation at the same time, a different port is assigned to each user's session, and the processing of documents fails.

If a user encounters problems processing documents, ensure all other users on the same workstation stop their instance of the Edit Service client.

Troubleshooting

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:

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSEUEX","label":"IBM Content Navigator"},"Component":"--","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All versions","Edition":"","Line of Business":{"code":"LOB18","label":"Miscellaneous LOB"}}]

Document Information

Modified date:
19 August 2021

UID

swg27036837