This document will show example scenarios for configuring the TLS protocol on a IBM Cognos Analytics environment. I choosed the 3 most used scenarios for that. All steps are describing a special test environment that I created for this. The Client is using Chrome as the Browser to access IBM Cognos Analytics. There are similiar functions to import the certificates in Firefox and Internet Explorer. Even you just need 1 of the scenarios I highly recommend to read this document completely. I am explaining some steps in detail in 1 of the scenarios and will just mention the steps in a shorter form in the other scenarios.

We have 5 Machines:

1. CAClient – This is the Windows 10 Client Machine

2. CASERVER1 – This is the Server which has the IBM Cognos Gateway installed with Apache

3. CASERVER2 – This is the Server with the first application Tier of IBM Cognos Analytics

4. CASERVER3 – This is the Server with the second application Tier of IBM Cognos Analytics

5. CASERVER4 – This is the Data Tier

The Servers are running Redhat Linux 7.5 in our example. The steps are pretty much equal on Windows. If not we will mention it in the document.

The first step is to determine where we need to enable the TLS protocol. We have an Apache web server for the optional Gateway (if required) and two IBM Cognos Analytics application tiers (running in Websphere Liberty). Thats pretty much where you can configure the TLS protocol. Client access such as Datasource(s) with TLS or LDAPS will not be covered in this document.

We will simulate cases for three options. Let‘s start:

Case 1: Your IT is requesting that you change the communication between users and the IBM Cognos Gateway to use the TLS protocol.

Case 2: Your IT is requesting that you change the communication between users and the IBM Cognos Analytics Dispatcher(s) as well as between the IBM Cognos Application Tier servers caserver2, caserver3 and optionally also the optional Gateway to use the TLS protocol.

Case 3: We will just enable TLS based on the custom certificate authority of your IBM Cognos Analytics Installation.

Case 1: Your IT is requesting that you change the communication between users and the IBM Cognos Gateway to use the TLS protocol.

• We will need to configure the TLS protocol on the Apache web server.

• We will need to import the chain of trust into the IBM Cognos Analytics keystore as the background processes will access the webserver for example to load any pictures.

• We will create an Test Report which just contains a Picture which is hosted by our web server and create an PDF output.

To configure the Apache web server for TLS we need to generate an CSR (certificate signing request) on our caserver1. So we connect to our caserver1 and run the following commands:

openssl genrsa -out caserver1.key.pem 2048

openssl req -new -sha256 -key caserver1.key.pem -subj "/C=DE/ST=Hessen/O=IBM/CN=caserver1.fyre.ibm.com" -reqexts SAN -config <(cat /etc/pki/tls/openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:caserver1.fyre.ibm.com,DNS:tlstest.mydomain.com\n")) -out caserver1.csr.pem

Let‘s discover some of the used parameters. We are creating this CSR using sha256 with the subject "/C=DE/ST=Hessen/O=IBM/CN=caserver1.fyre.ibm.com". caserver1.fyre.ibm.com is our FQDN for the server and needs to be provided as the CN. In addition, we need to provide one or more subject alternate names. As this cannot be provided in a command line option we load the openssl.cnf from the server and append the option to it. The subject alternate names must contain all possible FQDN‘s which could be used in URI‘s by our users. As example our server has the FQDN caserver1.fyre.ibm.com. Our IT is also providing an DNS alias tlstest.mydomain.com for external users to connect to the server. Therefore we need to provide that alias in the subject alternate names. If users will navigate there Browser to a URL which is not in the subject alternate names then modern Browsers will complain about the certificate.

We will now send the caserver1.csr.pem to the certificate authority to sign the certificate for us.

The certificate authority sends us 3 files back. The Files are cacert.pem icacert.pem and caserver1.cert.pem. Let‘s have a look with openssl what certificates are in this files:

openssl x509 -in caserver1.cert.pem -noout -subject -issuer

subject= /C=DE/ST=Hessen/O=IBM/CN=caserver1.fyre.ibm.com
issuer= /C=DE/ST=Hessen/L=Frankfurt/O=IBM/OU=Support/CN=Intermediate RootCA TLS Tutorial/emailAddress=andreas.weber@de.ibm.com

This means we have a certificate for caserver1.fyre.com signed from Intermediate RootCA TLS Tutorial.

openssl x509 -in icacert.pem -noout -subject -issuer

subject= /C=DE/ST=Hessen/L=Frankfurt/O=IBM/OU=Support/CN=Intermediate RootCA TLS Tutorial/emailAddress=andreas.weber@de.ibm.com
issuer= /C=DE/ST=Hessen/L=Frankfurt/O=IBM/OU=Support/CN=RootCA TLS Tutorial/emailAddress=andreas.weber@de.ibm.com 

So we have an certificate „Intermediate RootCA TLS Tutorial“ which was signed by CN=Intermediate RootCA TLS Tutorial. When we run „openssl x509 -in icacert.pem -noout -text“ so with the -text option, we can also see the this is an CA certificate.

openssl x509 -in cacert.pem -noout -subject -issuer

subject= /C=DE/ST=Hessen/L=Frankfurt/O=IBM/OU=Support/CN=RootCA TLS Tutorial/emailAddress=andreas.weber@de.ibm.com
issuer= /C=DE/ST=Hessen/L=Frankfurt/O=IBM/OU=Support/CN=RootCA TLS Tutorial/emailAddress=andreas.weber@de.ibm.com 

We see this is the certificate RootCA TLS Tutorial and the issuer is also RootCA TLS Tutorial. This is because every top Root CA is an self signed certificate. Also the -text Option will show as that CA:TRUE again.

At this time we see a complete chain:

CN=caserver1.fyre.ibm.com was signed by CN=Intermediate RootCA TLS Tutorial and CN=Intermediate RootCA TLS Tutorial was signed by CN=RootCA TLS Tutorial. CN=RootCA TLS Tutorial is self signed with the option CA:TRUE so it is a Root certificate (Top level).

It is very important to have the complete chain of trust.

Another Point I have to mention here is that you could get a chain file which contains the two Root certificates. In that case you need to copy them into 2 seperate files. The certificates are starting with -----BEGIN CERTIFICATE----- end ending with -----END CERTIFICATE-----. This is important to know as the ThirdPartyCertificateTool which we use later to import the Root certificates will just process the first certificate in a file. This is for security reasons.

Even it isn‘t really the topic of this document I show my steps to configure the Apache for the TLS protocol.

yum install mod_ssl

mkdir /etc/httpd/ssl

cp cacert.pem icacert.pem caserver1.cert.pem caserver1.key.pem /etc/httpd/ssl/

vim /etc/httpd/conf.d/ssl.conf

I will customize the certificate values in /etc/httpd/conf.d/ssl.conf

And I will Include the cognos.conf in the virtual host

systemctl restart httpd

Let‘s try to browse https://caserver1.fyre.ibm.com/ibmcognos/bi

This is what we get. The reason for that is that Chrome (in my case) does not have the Root certificate in his keystore. Most public certificate authorities should be already in the Keystore. But for purpose of this Tutorial I did create my own custom CA and intermediate CA. If you or your company is also using their own certificate authority you need to ensure that the Root certificates are automatically imported on users machines. So Let‘s import them to get rid of this warning:

For Chrome navigate to chrome://settings expand the advanced section and go to „Manage certificates“. IE and Firefox will have similiar options. Click Import and choose the first certificate.

Click on Browse and select „Intermediate Certification Authorities“ and click OK.

Click Next and Finish.

Repeat the steps for the second file „cacert.pem“ and this Time choose „Trusted Root Certification Authorities“.

Click Next and Finish.

Close the Browser and reopen it.

Let‘s try again to browse https://caserver1.fyre.ibm.com/ibmcognos/bi

Ok, so far so good.

Now let‘s create our Test Report. Just an Blank Report with a Image. Type in „../samples/images/banner_cogsquare.jpg“ behind the relative URL.

The Result will be an IBM logo

Save the Report.

Now use the Run as Option to generate an PDF. The Logo is correctly rendered because it was grabbed from the local file system because ot the relative URL. Go back in authoring mode and change the Image URL to „https://caserver1.fyre.ibm.com/ibmcognos/bi/samples/images/banner_cogsquare.jpg“.

Try to generate an PDF output again. This time you see the following:

There is just an placeholder instead of the picture. That is because the processes on our AppTier servers were acting as a Client and connected to the web server to retrieve the Image. But IBM Cognos Analytics doesn‘t trust the CA certificates as they are unknown.

So Let‘s fix this by importing the 2 CA certificates into the Cognos Keystore of both AppTier Servers.

To simplify our commands we will copy the 2 files cacert.pem and icacert.pem into the bin folder of the IBM Cognos Analytics Installation.

On both servers run the following commands:

./ThirdPartyCertificateTool.sh -i -T -r cacert.pem -p NoPassWordSet


./ThirdPartyCertificateTool.sh -i -T -r icacert.pem -p NoPassWordSet

Recycle the Cognos Service and try again to render the PDF output from our test Report.

This Time the logo is correctly rendered.

Additional Info:

With Openssl installed you can test the connection and show the certificates and settings:

openssl s_client -connect caserver1.fyre.ibm.com:443

You can also see that TLS v1.2 and Cipher ECDHE-RSA-AES256-GCM-SHA384 is used in my test environment.

If you don‘t have the root certificates available you could export them from your web browser if they are already in the Keystore or use the following command: openssl s_client -connect <server>:<port> -showcerts > out.pem. In case the web server is properly set up with TLS the out.pem will contain all required certificates.

Case 2: Your IT is requesting that you change the communication between users and the IBM Cognos Analytics Dispatcher between the IBM Cognos AppTier servers caserver2, caserver3 and optional also the optional Gateway to use the TLS protocol.

• All steps must be done on all Application Tier installations

• We will need to generate an certificate signing request (CSR) and provide this to our certificate authority to sign the certificate.

• We will need to create a backup of the Keystore to avoid loosing the private key which we used to generate the CSR.

• We need to import the chain of trust to the IBM Cognos Analytics Keystore

• As soon as we receive the certificate from the CA we need to import them into the Keystore.

• We need to configure IBM Cognos Analytics to use a 3rd Party CA.

Stop the IBM Cognos services

Take a copy of the folder <ca_install_location>/configuration. In that example I call it configuration_noTLS.

Export the cogstartup.xml file in clear text. You can use IBM Cognos Configuration -> File -> Export As or you can use the command line while you are in the bin64 folder:

./cogconfig.sh -e ../configuration/cogstartup.xml

Delete the following files and folders;

• <ca_install_location>\temp\cam\freshness
• <ca_install_location>\configuration\caSerial
• <ca_install_location>\configuration\certs\CAMCrypto.status
• <ca_install_location>\configuration\certs\CAMKeystore
• <ca_install_location>\configuration\certs\CAMKeystore.lock
• <ca_install_location>\configuration\csk

DO NOT START IBM COGNOS CONFIGURATION ANYMORE!!! ALSO DO NOT START THE SERVICE!!!

Next we create the CSR with the following command:

cd bin

./ThirdPartyCertificateTool.sh -c -e -d "CN=caserver2.fyre.ibm.com,O=IBM,C=DE,ST=Hessen,OU=Support" -r /opt/ibm/cognos/encryptRequest_caserver2.csr -p NoPassWordSet -H "caserver2.fyre.ibm.com caserver1.fyre.ibm.com"

On the second AppTier:

cd bin

./ThirdPartyCertificateTool.sh -c -e -d "CN=caserver3.fyre.ibm.com,O=IBM,C=DE,ST=Hessen,OU=Support" -r /opt/ibm/cognos/encryptRequest_caserver3.csr -p NoPassWordSet -H "caserver3.fyre.ibm.com caserver1.fyre.ibm.com"

As of Version 11.0.13 you need to add the argument -a <RSA|EC>. This argument is mandatory since version 11.0.13.
Example:

./ThirdPartyCertificateTool.sh -c -e -d "CN=caserver3.fyre.ibm.com,O=IBM,C=DE,ST=Hessen,OU=Support" -r /opt/ibm/cognos/encryptRequest_caserver3.csr -p NoPassWordSet -H "caserver3.fyre.ibm.com caserver1.fyre.ibm.com" -a RSA

In my test I am adding caserver1.fyre.ibm.com in addition to the subject alternate names as this server will host an HAProxy and forward Users to my Dispatcher URL‘s. So in that case the users will navigate to https://caserver1.fyre.ibm.com:9300/bi instead of https://caserver2.fyre.ibm.com:9300/bi which is not reachable from their clients (Think of it as a DMZ).

Please note, due of an existing defect we have to use ThirdPartyCertificateTool_OLD.sh on Version 11.0.12. This is the version I installed so the Screenshot differs from the command line in this document.

AGAIN. DO NOT START IBM COGNOS CONFIGURATION!!! DO NOT START THE SERVICE!!!

In the next step we take another Backup.

This Backup contains our private key which was generated for the CSR request and we need to keep it. If we start IBM Cognos Configuration and we save or try to start the service, the private key will be overridden and you will not be able to complete that setup.

If you need to keep IBM Cognos Analytics running until the CA has signed the certificates you can restore the Backup configuration_noTLS and work with this. As soon as you get the certificates back, you need to revert to configuration_CSR.

I send encryptRequest_caserver2.csr and encryptRequest_caserver3.csr to my CA and I received my signed certificates in return. To simplify the commands, I copied the required certificates into the bin folder of each IBM Cognos Analytics installation.

Like we did in the first part of this document we have that custom Root and intermediate CA which I created for purpose of this document.

To import the certificate, we need to have a file containing the chain of trust (complete chain of the root CA‘s). So let us create that file in the next step.

Then we proceed to import the certificates:

./ThirdPartyCertificateTool.sh -i -e -r encrypt_caserver2.cert.pem -t cachain.pem -p NoPassWordSet

The first attempt to run the command yields the following error:

This is because the certificate contains the complete information and the ThirdPartyCertificateTool is not able to read that format.

We just need the certificate itself. So let us fix this quickly (On Windows you can just copy and paste the block starting with -----BEGIN CERTIFICATE----- end ending with -----END CERTIFICATE----- into a new file). Openssl has a command to do this for you.

openssl x509 -in encrypt_caserver3.cert.pem -out encrypt_caserver3_notext.cert.pem

Let‘s try it again.

This time it worked. Now we need to import the CA certificates separately.

Now we can open Cognos Configuration and configure the TLS protocol. There is one setting we should verify and one setting that we need to change.

So we configure the Cryptography to use a third party CA. This is very important. And if there are no compatibility issues with any clients I suggest to keep the TLS 1.2 protocol. If a higher version such as TLS 1.3 is available you should consider to use it instead.

Under Environment change the URI‘s from http to https:

Save the configuration and start the services.

On the client machine navigate to https://caserver2.fyre.ibm.com:9300/bi (Please remember, I need to call caserver1.fyre.ibm.com again as I need to serve over my haproxy).

As you can see it works perfectly fine. Please also test all other Application Tier servers you have.

Because of my forwarding through haproxy I need to use the port 9400 in that case.

Since I used caserver1.fyre.ibm.com in the subject alternate names the certificate is also working for this URL. Let me do another test. I will add something like wronghostname.test.com to my hosts file pointing to on of my AppTier servers to show you what happens if a URL will be used which isn‘t in the subject alternate name.

The same would happen if I use the IP address.

As you can see you need to properly plan your subject alternate names.

Additional Steps if there is an optional Gateway installed:

After setting up TLS between the IBM Cognos Analytics AppTier servers our access through the optional Gateway isn‘t working anymore.

This is because the Gateway also needs to act as an TLS client now. So the Gateway need to have the chain of trust and the Proxy Module need use different methods.

We are going to configure this next. Open the Apache configuration for IBM Cognos Analytics. In my case I am including a standalone file (based on the shipped templates from <ca_install>/cgi-bin/templates) to my Virtual Hosts which contains all Cognos related configuration.

vim /etc/httpd/conf.d/cognos.conf

I will add the following Lines just after my module imports:

SSLProxyEngine On

SSLProxyCACertificateFile "/etc/httpd/ssl/ca-bundle.pem"

Then I will change the URI‘s that point to the Application Tier‘s from http to https

Now we need to create the file /etc/httpd/ssl/ca-bundle.pem which will contain the complete chain of trust (Root CA and intermediate CA)

cat cacert.pem icacert.pem > ca-bundle.pem

Let‘s restart Apache and try it out.

systemctl restart httpd

That‘s it. Our optional Gateway is now able to access the Application Tier‘s.

Case 3: Just enable TLS based on the custom certificate authority of your IBM Cognos Analytics Installation.

This scenario is just recommended in smaller environments as you would have a certificate authority for each AppTier Installation.

I will use two Application Tier installations for this example.

Before you start, take a backup of the configuration folder from IBM Cognos Analytics!!!

Open Cognos Configuration and change the URI‘s under Environment to https on both servers.

Under Cryptography -> Cognos change all the attributes you want to use for this certificate. Ensure that the Server common name is set to the FQDN of the server and that you have all FQDN values you want to use in URI‘s to access this server in the DNS name. DNS names = subject alternate names.

Save the configuration and repeat the steps on the second server.

Start all services and navigate to the first server.

It seems that the Browser is not aware about the Root certificate called CA. We need to expert that certificate from IBM Cognos Analytics and to import it into our browser.

./ThirdPartyCertificateTool.sh -E -T -p NoPassWordSet -r Cognos_CA_caserver2.cert

Copy the exported certificate to the Client and import into Chrome.

Click Next

Choose „Trusted Root Certification Authorities“ and click OK

Click Next and Finish

Click Yes to confirm that you trust this certificate.

Close Chrome and try again to navigate to https://caserver2.fyre.ibm.com:9300/bi/.

This times it works.

Try to access the second server.

We get the same message again because this server is using a different CA. So repeat the steps to export the CA from the 2nd server and to import into your browser.

Close Chrome, reopen it and try again to access the second server.

This times it works. So in this scenario you need to ensure that the users Browser has the CA certificates from each Application Tier installed.