Configuring IBM HTTP Server with SSL

If you are using Secure Sockets Layer (SSL) on IBM HTTP Server, you must change the Gateway URI values in IBM Cognos Configuration to be able to access the portal.

To enable SSL on your web server, you must obtain a web server certificate signed by a Certificate Authority (CA) and install it into your web server. For more information about using certificates with your web server, see your web server documentation. These certificates are not provided with IBM Cognos products.

To enable users to access the IBM® Cognos® portal using SSL, you must change the Gateway URI values in IBM Cognos Configuration for each computer where the Application Tier Components and Framework Manager are installed.

Before you begin

IBM HTTP Server must have IBM Global Security Kit (GSKit) installed. For more information about the supported versions of GSKit on IBM HTTP Server, see the IBM Software Compatibility Report.

Procedure

  1. On each computer where the Application Tier Components or Framework Manager are installed, start IBM Cognos Configuration.
  2. Under Local Configuration, click Environment, and change the Gateway URI value from http to https.
  3. In the Gateway URI value, change the port number to the SSL port number defined for your web server.
    For example, the default port number for SSL connections is usually 443.
  4. On each computer where the Application Tier Components or Framework Manager are installed, go to the install_location/bin directory, and import all the certificates that make up the chain of trust, in order starting with the root CA certificate, into the IBM Cognos truststore.

    Import the certificates by typing the following command:

    On UNIX or LINUX, type

    ThirdPartyCertificateTool.sh -T -i -r path/certificate_fileName -p password

    On Windows, type

    ThirdPartyCertificateTool.bat -T -i -r path\certificate_fileName -p password

    Note: If password is not set, the default password is NoPassWordSet.
  5. Type the following command from the web server ihs_install_root/bin directory:
    ihs_install_root/bin/script_name

    Where ihs_install_root is the directory where IBM HTTP Server is installed and script_name is gskver.bat for Microsoft Windows or gskver.sh for UNIX or Linux.

    The GSKit shared libraries and version information are displayed. Verify that the version displayed is the minimum supported version as shown in the support document mentioned in the Before you begin section of this procedure.
  6. Start the iKeyman utility by typing the following command:
    ihs_install_root/bin/script_name

    Where ihs_install_root is the directory where IBM HTTP Server is installed and script_name is ikeyman.bat for Microsoft Windows or ikeyman.sh for UNIX or Linux.

  7. From the menu, select Key Database File > New.
  8. Enter the following values and click OK:
    File Name
    Name of the key database file. The default value is key.kdb.
    Location
    Place to store the key.kdb file. The default value is ihs_install_root/bin.
  9. In the Password Prompt window, enter a password, select the Stash a password to a file check box, and click OK.
    When you select the Stash a password to a file check box, the password is encrypted and is saved as a .sth file in the same directory as the key database file.
    A completed successfully message displays.
  10. Open the ihs_install_root/conf/httpd.conf file in a text editor.
  11. Add the Keyfile directive with the path to your key database file. Put it after the VirtualHost section in the file.
    For example,
    
<VirtualHost *:443> 
...
</VirtualHost>
KeyFile ihs_install_root/key.kdb
  12. Save and close the httpd.conf file.
  13. Extract the Cognos Analytics certificate to a file. Run the following command from the IBM Cognos Analytics server in ca_install/bin. 
    script_name -E -T -r ca_cert_file -p NoPassWordSet

    Where script_name is ThirdPartyCertificateTool.bat for Microsoft Windows or ThirdPartyCertificateTool.sh for UNIX or Linux and ca_cert_file is the name of the certificate file.

  14. Copy the certificate file to ihs_install_root/key_database_file_directory where ihs_install_root is the directory where IBM HTTP Server is installed and key_database_file_directory is the directory where the key database file is stored.
  15. In ihs_install_root/bin, type the following command: 
    script_name -cert -import -db ca_cert_file 
-pw NoPassWordSet -target key.kdb -target_pw key_database_file_password

    Where script_name is gskcapicmd.bat for Microsoft Windows or gskcapicmd.sh for UNIX or Linux and key_database_file_password is the password for the key database file.

  16. Start IBM HTTP Server. Enter the following command in ihs_install_root/bin: 
    script_name -k start

    Where script_name is apchectl.bat for Microsoft Windows or ./apachectl for UNIX or Linux. On Microsoft Windows, you can also start the script as a service.

  17. Verify that IBM HTTP Server is running by entering the following URI in the address field of a web browser: 
    https://web_server_host_name:port

    Where web_server_host_name is the host name of IBM HTTP Server and port is the IBM HTTP Server port number.

  18. Save your configuration, and restart your services.

Results

When you access the portal using https://servername:443/ibmcognos, you are prompted to install a certificate. To avoid being prompted by a security alert for each new session, install the certificate into one of your web browser's certificate stores.