How to add a 3rd Party CA to allow for SSL between components in IBM Cognos Analytics

Note: Steps below assume a single server environment. For a distributed environment with multiple content managers and dispatchers these steps must be performed on each server. For gateways in a distributed environment see step 12.

2) Make a full backup copy of your ..\configuration directory;

3) Export unencrypted configuration:

In Cognos Configuration tool click ‘File > Export As’

Choose ‘Yes’ at the prompt and save the file. For example, name it ‘backup.xml’, which by default is stored in the c11\configuration folder.

Close Cognos Configuration.

c11\configuration\cogstartup.xml

c11\configuration\caSerial

c11\configuration\certs\CAMCrypto.status

c11\configuration\certs\CAMKeystore

c11\configuration\certs\CAMKeystore.lock

c11\temp\cam\freshness

c11\configuration\csk (delete the directory with all files in it)

5) In the c11\configuration folder, copy ‘backup.xml’ from step 3 to ‘cogstartup.xml’.

That way, exported configuration takes place of the original cogstartup.xml file, and you also retain unencrypted backup.

WARNING #1:  Do not start the Cognos Configuration Tool until step 10 of the document.

6) Generating CSR (Certificate Signing Request)

Important:

Certificates are domain-specific. It is required to use identical fully qualified domain names (FQDN) of the server used everywhere in Cognos configuration and in CSR request. Referencing the server with certificates by a short hostname or IP address or localhost reference will result in certificate host mismatch error and the server won't function properly.

If server has multiple host names, each FQDNs should be specified in Subject Alternative Name (SAN) in CSR request. Multiple SAN names must be separated by space.

"Main" server name (specified in URIs on Environment page) must match CN record in CSR.

Checklist of URIs that must be set to FQDNs:

On Environment page

• Dispatcher URIs for gateway
• External dispatcher URI
• Internal dispatcher URI
• Dispatcher URI for external applications
• Content Manager URIs

In Security > Cryptography > Cognos

• Server common name

Important:

Thirdpartycertificatetool.bat (.sh in Linux) has to be ran from <CA11>\bin directory.

Syntax of CSR command:

ThirdPartyCertificateTool.(bat|sh) -c -e [-p <keystorePassword>] -a <keyPairAlgorithm> -r <path/to/CertOrCSR> -d <dn> [-H <subjectAlternativeNameDnsNames>] [-I <subjectAlternativeIpAddresses>] [-M <subjectAlternativeEmailAddresses>]

Open a command prompt (on Linux - command must be run as the user account that runs Cognos).
Change directory to <ca11_location>\bin

Windows Operating System Request (Change CN, OU, O, L, and C parameters:

Example:
ThirdPartyCertificateTool.bat -c -e -p NoPassWordSet -a RSA -r "request.csr" -d "CN=server.domain.com,OU=Support,O=IBM,L=Ottawa,C=CA" -H "server.domain.com"

Run the command. Output file "request.csr" is the file that needs to be sent to certificate authority.

Tip: in a multi-server environment for convenience use server names for each CSR file, e.g. server111.csr, server222.csr, etc.

Example that uses multiple values for the Subject Alternative Name:

Note: use spaces between values, not a comma

ThirdPartyCertificateTool.bat -c -e -p NoPassWordSet -a RSA -r "request.csr" -d "CN=server.domain.com,OU=Support,O=IBM,L=Ottawa,C=CA" -H "server.domain.com server2.domain"

OR

On unix and Linux Operating System Request (Change CN, OU, O, L, and C parameters:

CN is set to your Domain

./ThirdPartyCertificateTool.sh -c -e -p NoPassWordSet -a RSA -r "request.csr" -d "CN=server.domain.com,OU=Support,O=IBM,L=Ottawa,C=CA" -H "server.domain.com"
 

Cognos CAMKeystore now contains the private key that is used with the certificates for encryption.  If you encounter an issue where the private key is overwritten before you get the signed certificate imported successfully all of the steps would need to be redone if a backup is not available.

Common pitfall is when Cognos environment is started after generating CSR to use the environment without 3-rd party certificates, while waiting for certificate authority to send the certificate back. If installing 3-rd party certificates is incomplete, Cognos generates internal certifcates and that makes impossible importing a 3-rd party certificate when it arrives. Saving backup of CAMKeystore therefore becomes critical, as the 3-rd party certificate must be imported into original CAMKeystore after running CSR command.

6a) If provisioning a 3-rd party certificate has a long turnaround time during which Cognos environment has to be up and running i.e. IBM Cognos system re-started, you should back up CAMKeystore after running CSR command, then use Cognos as needed, and when certificate arrives - you should remove existing cryptographic files again, copy a backup of CAMKeystore taken after CSR command into configuration\certs directory and run the rest of the commands below using that copy of CAMKeystore.

7) Processing 3-rd party certificate

When the certificate arrives, you need to process it before importing into the keystore.
 

Get encrypt.csr signed by your certificate authority. Typically there's a Root, 1 or more Intermediate (optional), and the server certificate in the bundle. Verify the bundle (if necessary rename the file to have .cer or .crt extension). Windows can open .cer or .crt files and display certificate properties.

Using www.ibm.com certificate as an example we can identify Root (DigiCert), Intermediate (DigiCert TLS RSA SHA256 2020 CA1) and Server (www.ibm.com) certificates:

Extract the Root and Intermediate certificates on the server.

Convert all the certificates to Base-64 encoded X.509 (.CER) format
 

For simplicity, rename the certificates as shown in the screen capture:

In a text editor create chain certificate made of Intermediate certificate, followed up by Root certificate, and save it as chain.cer file.

Save as chain.cer

Special cases:

- If there is only a root certificate and no intermediate - use root.cer as a chain certificate, and reference root.cer instead of chain.cer in the command at step 8.3.

- If there are 2 or more intermediate certificates, then chain certificate must have all intermediate certificate saved in a reverse order: lowest intermediate certificate in the chain comes first, then then next intermediate certificate, and the root comes last.

Copy all these certificates to ca11_location\bin location.

8) Importing certificate

8a) If have performed steps in section 6a) to start IBM Cognos system until the server certificates are provisioned, then perform steps below, otherwise, if IBM Cognos services down since creation of the initial CSR command, then skip and proceed to step 8.1.)

 - Stop IBM Cognos services
 - Rename the current c11\configuration\certs directory to c11\configuration\certs.YYYYMMDD

- Important: make sure that c11\configuration\certs\CAMKeystore file is original CAMKeystore after CSR command. Use backup taken on step 6 if necessary. Typically CAMKeystore at that step is only 4KB large. If you have a larger file (100KB or more) - this is likely a wrong copy. Review the steps above and fix the errors before proceeding.
 

- Import the certificate in the following order with these commands:

8.1.) Root:

ThirdPartyCertificateTool.bat -i -T -r root.cer -p NoPassWordSet

8.2) Intermediate

ThirdPartyCertificateTool.bat -i -T -r intermediate.cer -p NoPassWordSet

8.3) Chain and server:

ThirdPartyCertificateTool.bat -i -e -r server.cer -t chain.cer -p NoPassWordSet

OR

On unix or Linux Operating systems, accordingly:

ThirdPartyCertificateTool.sh -i -T -r root.cer -p NoPassWordSet

ThirdPartyCertificateTool.sh -i -T -r intermediate.cer -p NoPassWordSet

ThirdPartyCertificateTool.sh -i -e -r server.cer -t chain.cer -p NoPassWordSet

 

9) Switching Cognos to use 3-rd party certificates.

This step is Cognos version-specific. Steps differ for Cognos 11.x and 12.x

9.1) Steps for CA 11.x

Launch the Cognos Configuration Tool.

It is critical to perform the steps below in exact order. Saving configuration BEFORE these steps are performed can wipe out 3-rd party certificates and you will have to start all over again.

Navigate to Security > Cryptography > Cognos:

Change 'Use third-party CA?' setting to "True"

9.2) Steps for CA 12.x

Right-click on Cognos under Security > Cryptography and select Delete

 

 

Then Right-click on Security > Cryptography, select New resource > Certificate authority

 

 

Give new resource any name and select "Third party certificate authority" from the drop down list:

 

9.3) Change the following URIs from HTTP to HTTPS on Environment page

• Dispatcher URIs for gateway
• External dispatcher URI
• Internal dispatcher URI
• Dispatcher URI for external applications
• Content Manager URIs

There must be no mix of http and https for URIs running on the same port.

Example:

10) Save configuration

Start IBM Cognos Service.
 

When Cognos starts - open Dispatcher URI or Content Manager URI in a web browser and check certificate properties to ensure correct certificate is installed.