IBM Support

Configuring IBM Cognos Analytics/BI for an HTTPS enabled Web Server

Troubleshooting


Problem

When HTTPS is enabled on the Gateway, in addition to changing the gateway URL to secure HTTPS, you must set up trust between the web server and IBM Cognos Analytics / Business Intelligence

Symptom

One symptom when executing reports, pictures don't show up in PDF outputs when using SSL, they do appear in other output formats though.
Another symptom could be Transformer or Framework Manager are unable to read their data sources.

Cause

To set up trust, the Cognos administrator must import all the certificates making up the chain of trust for the web server's certificate into IBM Cognos Analytics'/BI's trust store. This chain is made up of all possible intermediate CA certificates and the root CA certificate.

Example: Server Certificate S was signed by Intermediate CA C1, whose certificate in turn was signed by root CA C2.
The administrator would have to import the certificates from C1 and C2, but not S.
The process is as follows:
  • Configure your Web server for SSL and start it.
  • Obtain the certificates that make up the chain of trust for the Web server's certificate,
    (i.e. all intermediate CA certificates and the trusted root's certificate).

    The certificates must be either in Base64 encoded ASCII (PEM) or DER format to be
    readable by ThirdPartyCertificateTool.

    You must not use a self-signed server certificate; only CA certificates are valid.

Resolving The Problem

For every installation running (Batch) Report Service that uses the Web Server (Gateway) that is enabled for HTTPS, apply the following steps:

  • Stop the product
  • Open Cognos Configuration and change the Gateway URL
    to use HTTPS instead of HTTP
  • Save configuration but don't start yet
  • Using the ThirdPartyCertificateTool from the /bin directory of your IBM Cognos installation, import all the certificates from the chain of trust into the IBM Cognos truststore.
    Start with the root CA certificate and work your way down to the last possible intermediate CA certificate
For pre-Cognos BI 10.2.2:
 
For Windows, repeat the following command for each certificate:
ThirdPartyCertificateTool.bat -T -i -r CA_certificate_fileName -D ../configuration/signkeypair -p password

For UNIX and Linux repeat the following command for each certificate:
ThirdPartyCertificateTool.sh -T -i -r CA_certificate_fileName -D ../configuration/signkeypair -p password
 
For Cognos Analytics 11.x and Cognos BI 10.2.2
In Cognos Analytics 11.x and Cognos Business Intelligence version 10.2.2, you can no longer use the -D flag to specify a key store location. For example, the following command:
 
For Windows, repeat the following command for each certificate:
ThirdPartyCertificateTool.bat -T -i -r CA_certificate_fileName -p password

For UNIX and Linux repeat the following command for each certificate:
ThirdPartyCertificateTool.sh -T -i -r CA_certificate_fileName  -p password

Tip: The password is generally set by your administrator, the default is "NoPassWordSet".
Start your IBM Cognos BI system
  • Access the Gateway and import the presented certificate into your browser to avoid getting reprompted on every new session. Follow

To verify the trust, create and run a report containing pictures that are fetched via the Gateway (not local File system) in PDF output format. If they appear trust is established.

the previous steps for all client components on Windows (FM, Transformer, PowerPlay client, Cube Designer, etc....). For Transformer on Linux or UNIX use ThirdPartyCertificateTool.sh.

Tip: Tools such as these can be used to verify the import into the truststore. IKeyMan, OpenSSL, KeyStoreExplorer, or Portecle.
Note that keytool (part of SUN JREs) won't show the signer certificates in a PKCS12 keystore!

iKeyman
choose to open a PKCS12 type file, find <COG_INSTALL>/configuration/signkeypair/jCAKeystore. Make sure you select "Signer Certificates" from the drop down for viewing the imported CA certificates instead of the ca Keypair contained in this file.

For OpenSSL
use a command like like:
OpenSSL pkcs12 -info -in <COG_INSTALL>/configuration/signkeypair/jCAKeystore

For KeyStoreExplorer or Portecle, o
open, o<COG_INSTALL>/configuration/signkeypair/jCAKeystore

[{"Product":{"code":"SSEP7J","label":"Cognos Business Intelligence"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Security","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"10.2.2;10.2.1;10.2;10.1.1;10.1;8.4.1","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}},{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSTSF6","label":"IBM Cognos Analytics"},"ARM Category":[{"code":"a8m0z000000bqDVAAY","label":"Administration->Security->TLS"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
29 April 2020

UID

swg21339658