Reconfigure Cognos Analytics to Use Third-Party SSL Certificates

This process switches Cognos Analytics over from using the default certificates provided by IBM to using the certificates you have saved for your servers. IBM refers to this process as "recrypting" Cognos Analytics. The process restores the chain of trust, enabling SSL communication between various Cognos Analytics components, as well as between Cognos Analytics and the others servers for FlexNet Manager Suite.

Commence this process while logged in to your Flexera Analytics server, using an account with administrator privileges.

To recrypt Cognos Analytics to use third-party certificates:

Navigate to the Cognos Analytics installation directory (usually C:\Program Files\ibm\cognos\analytics).
Take a protective backup copy of the configuration folder.
Launch the IBM Cognos Analytics Configuration tool as administrator, and stop the Cognos Analytics service if it is running.
Navigate to File > Export As and export the decrypted content as backup.xml in the configuration folder. Choose Yes at the prompt, and save the file.
Without restarting the Cognos Analytics service, close the IBM Cognos Analytics Configuration tool.

Important: Do not re-open the IBM Cognos Analytics Configuration tool until instructed to do so.
Create a backup of the following directory, and move it from the analytics directory: CognosInstallationPath\temp\cam\freshness
Open a command prompt as administrator, and run the following commands to delete existing content.
If you have a non-standard installation path, replace the default Cognos Analytics installation path shown here with the one from your environment.
```
cd "C:\Program Files\ibm\Cognos\analytics"
del .\configuration\cogstartup.xml
del .\configuration\caSerial
del .\configuration\certs\CAMCrypto.status
del .\configuration\certs\CAMKeystore
del .\configuration\certs\CAMKeystore.lock
del .\temp\cam\freshness
rd .\configuration\csk
```
In the CognosInstallationPath\configuration directory, rename backup.xml to cogstartup.xml.

Remember: Do not start the IBM Cognos Analytics Configuration tool until specifically instructed to do so.
Open a command prompt as an administrator, and change to the directory CognosInstallationPath\bin.

Enter a command using the following syntax:

When providing details for your <domainName>, customize the following parameters: CN (set to your domain), OU, O, L, and C.

cd c:\Program Files\ibm\cognos\analytics\bin
ThirdPartyCertificateTool.(bat|sh) -c -e [-p <keystorePassword>] 
-a <keyPairAlgorithm> -r <path/to/CertOrCSR> -d <domainName> 
[-H <subjectAlternativeNameDnsNames>] [-I <subjectAlternativeIpAddresses>] 
[-M <subjectAlternativeEmailAddresses>]

Example:

cd c:\Program Files\ibm\cognos\analytics\bin
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"

Best practice: Take a new backup of the complete CognosInstallationPath\configuration folder immediately after running the CSR command, save it in a different location/folder, and name the backup configuration.waiting_on_certs. Certificate received from certificate authority must be imported into the original CAMKeystore created by the CSR command above. Typical size of CAMKeystore file at that step is around 4 KB.
This backup allows you to recover the cryptographic keys from a known point where we are waiting on the certificate request being signed. This is a natural pause point if you need to bring Cognos Analytics back online, and it prevents having to redo all the steps above in case a problem arises.
Tip: If the Certificate Authority takes longer to issue certificates than your allowed downtime, then you may:
1. Rename the current CognosInstallationPath\configuration directory to CognosInstallationPath\configuration.waiting.
2. Restore the original, backup CognosInstallationPath\configuration directory that you made at step 2.
3. Restart Cognos Analytics.
At this point, Cognos Analytics functions exactly as it did before starting this 'recrypting' process. Later, when the certificates arrive, you may:
1. Stop the Cognos Analytics services.
2. Rename the current CognosInstallationPath\configuration directory to CognosInstallationPath\configuration.original.
3. Rename the CognosInstallationPath\configuration.waiting to CognosInstallationPath\configuration.
4. Resume the remaining steps in this 'recrypting' process.
Get encrypt.csr signed by the Certificate Authority (such as DigiCert or Verisign), and receive back their root, intermediate (optional) and server certificates.

Tip: You cannot use self-signed certificates, as self-signed certificates are not trusted by IBM Cognos components.
Download the root, intermediate, and server certificates onto the Cognos Analytics server.
Use the following steps to convert each certificate to Base-64 encoded X.509 (.CER) format:
1. In Windows Explorer, identify the certificate, and right-click and select Open (or simply double-click the file name).
2. Click the Details tab.
3. Click Copy to File.
  A Certificate Export Wizard dialog appears.
4. In the Certificate Export Wizard dialog, click Next.
5. From the available options, select Base-64 encoded X.509 (.CER) format.
6. Click Next.
7. Enter the appropriate file name from these options, saving in the CognosInstallationPath\bin directory:
  - root.cer
  - server.cer
  - intermediate.cer (if you have an intermediate certificate).
8. Click Next.
9. Click Finish.
10. Click OK to dismiss the message box and all pop-up windows.
11. Loop back and repeat for each remaining certificate.
If you did not receive an intermediate certificate, skip ahead to step 16. If you did receive an intermediate certificate, you must also create a chain certificate, and then import all the certificates, as follows:
1. In your preferred text editor, open the newly created root certificate and copy the entire text. Close the root.cer without saving it (so that it remains unchanged).
2. In your preferred text editor, open the newly-created intermediate certificate (intermediate.cer), and paste the copied root certificate text below the intermediate certificate text.
3. Save the modified file into the CognosInstallationPath\bin folder with the new name chain.cer.
4. Open a command prompt as administrator, and run the following commands in the order shown to import the certificates:
```
cd c:\Program Files\ibm\cognos\analytics\bin
ThirdPartyCertificateTool.bat -i -T -r root.cer -p NoPassWordSet
ThirdPartyCertificateTool.bat -i -T -r intermediate.cer -p NoPassWordSet
ThirdPartyCertificateTool.bat -i -e -r server.cer -t chain.cer -p NoPassWordSet
```
  Continue from step 17.
Because you have no intermediate certificate (and therefore no need to create a chain certificate), open a command prompt as administrator, and run the following commands in the order shown to import your two certificates:
```
cd c:\Program Files\ibm\cognos\analytics\bin
ThirdPartyCertificateTool.bat -i -T -r root.cer -p NoPassWordSet
ThirdPartyCertificateTool.bat -i -e -r server.cer -t root.cer -p NoPassWordSet
```
Continue with the following steps.
In your preferred text editor, open CognosInstallationPath\configuration\FLEXnet.properties, and update the protocol in the URL to read HTTPS.
Launch the IBM Cognos Analytics Configuration tool as an administrator.
Navigate to Cryptography, and:
1. Change Common symmetric key store password to NoPassWordSet.
2. If your enterprise policy does not allow versions of TLS prior to 1.2, edit SSL Protocols accordingly.
Tip: We recommend using TLS 1.2. You may wish to refer to this knowledge base article for configuration details: https://community.flexera.com/t5/FlexNet-Manager-Knowledge-Base/Analytics-Cognos-Connection-to-SQL-Server-Fails-When-Server-is/ta-p/113351.
Navigate to Cryptography > Cognos, and:
1. Change Key store password to NoPassWordSet.
2. Change Server common name to the fully-qualified domain name (FQDN) of your Analytics server.
3. Change Country or region code to match the country code of your saved certificates.
4. Set Use third party CA? to True.
5. Change Certificate Authority service common name to match the Common Name (CN) of the CA root certificate.
6. Change Certificate Authority password to NoPassWordSet.
7. Change the Certificate lifetime in days figure to reflect time until the expiry date of the server certificate.
Navigate to Environment, and change all URIs (Gateway URI, Dispatcher URIs for gateway, External dispatcher URI, Internal dispatcher URI, Dispatcher URI for external applications and Content Manager URI) to use the HTTPS protocol. In Gateway URI and Controller URI for gateway, also replace port 80 with 443. Ensure to enter the fully qualified host name in all the values for all URIs.
Save the updated configuration.
Start the Cognos Analytics service.
Close the configuration tool.

Flexera Analytics, powered by Cognos Analytics, is now using the certificates in your preferred chain to certify SSL communications.