IBM Support

How to secure Jupyter for Cognos Analytics 11.1.x with 3rd party certificates

How To


Summary

This article describe the steps for securing Jupyter that uses 3rd party certificates. These steps are examples to help guide in a general overview.

The following general steps are discussed:
- Generating a CSR on the Jupyter Server
- Having the certificate signed
- Manipulating the Jupyter certificates
- Adding the Jupyter certificate to your Jupyter Server
- Creating a CSR on the Cognos Server
- Having the Cognos certificate signed
- Manipulating the Cognos certificates
- Importing the Cognos certificates into Cognos
- Adding the Cognos certificates into Jupyter
- Adding the Jupyter certs into Cognos.

Objective

Step 1: Create a new CSR (certificate signing request) for the Jupyter server

On the Jupyter machine install a tool for creating a CSR on the server. The command you use should create both a private key (.key) and a (certificate signing request) .csr certificate signing request.

An example of a command to generate a CSR and Private Key required for Jupyter can be seen here:

  • openssl req -new -sha256 -keyout <hostname>.key -out <hostname>.csr -newkey rsa:2048

Follow the prompts and do not forget the password you set (to be used later).  Note that it is critically important to set the Common name as the <hostname> of your Jupyter server,  for example: Jupyter1.ibm.com. 

Next, convert the private key (.key) file to an encrypted private key (.rsa.key) file. An example of this can be seen here: 

  • openssl rsa -in <your key file>.key -out <your key file>.rsa.key

Step 2: Request certificates from your certificate authority

Provide the Certificate Authority (CA) with the .csr (certificate signing request).


Step 3: Manipulate the certificates. 

Convert all the certificates returned from your CA to Base-64 encoded X.509 format.
Double click the certificate and select the details tab.

Select Copy to File and then select Base 64-Encoded X.509.

image 2659

image 2660

Rename all the files to .crt

For simplicity, rename the files according to this screenshot: 

  • ca-intermediate.crt
  • ca-root.crt
  • servercertificate.crt
  • ibm.com.key
  • ibm.com.rsa.key
image 2661

Create a file named: ca-chain.chained.pem. In this certificate chain, combine the files from the certificate authority. Open the files in a text editor, combining them as described here. 

The server certificate should come first, followed by any intermediate certs, the root trusted authority certificate, and finally the RSA private key (.rsa.key file). 

  -----BEGIN CERTIFICATE-----  server certificate  -----END CERTIFICATE-----    -----BEGIN CERTIFICATE-----  intermediate certs  -----END CERTIFICATE-----  -----BEGIN CERTIFICATE-----  root certificate  -----END CERTIFICATE-----  -----BEGIN RSA PRIVATE KEY-----  RSA Private Key  -----END RSA PRIVATE KEY-----

Now all of the files should look like the following: 

  • ca-chain.chained.pem
  • ca-intermediate.crt
  • ca-root.crt
  • servercertificate.crt
  • ibm.com.key
  • ibm.com.rsa.key

image 2662


Step 4: Add the Jupyter Server Certificates to the Jupyter server

Place the Jupyter server certificates onto the Jupyter Server. Best practice is to place them outside of the Jupyter Server installation directory.  Note that in order for this to function properly, one will only need the chained.pem file and the .rsa.key file for this step. 

  • mkdir /tmp/JupyterCerts

Navigate to the Jupyter Config.conf file 

  • cd <jupyter installation director>/dist/client-scripts/unix/config.conf

Edit the file using a text editor to point to the certificates. Note that it is important to use absolute paths. 

  PROXY_CERTIFICATE_FILE_PATH: This will point to the `.chained.pem` file    PROXY_KEY_FILE_PATH: This will point to the Jupyter Server's `.rsa.key` file

image 2664

Verify the last line is commented out (# CERT_NOVERIFY='-e NO_VERIFY='). If the line is commented out, the Jupyter server will validate the Cognos Server Certificates. If the line is active, the Jupyter server will respond to any Cognos requests without validating the certificates. 

To have this take effect, one must rebuild and restart the Jupyter server. However, the process is not currently finished. At this point, the Jupyter Server is secured with the Jupyter Server certificates, but it is not yet configured to accept connections from Cognos.


Step 5: Complete a CSR on the Cognos Server

For a more detailed approach follow this technote: How to add a 3rd Party CA to allow for SSL between components in IBM Cognos Analytics 11

Consider the appropriate backups prior to beginning: 

Backup the whole server before trying this on an environment. 

  • First ensure entire IBM Cognos system is shut down. Use appropriate operating system tools to make sure there are no Orphan processes.
  • Ensure that the JAVA_HOME environment variable is set properly to the JRE bing used.

Backup specific files:
Make a backup copy of your ..\configuration directory;
Create a backup of the following files

  • 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

On the Content Manager computer, click ‘File > Export As’. Choose ‘Yes’ at the prompt and save the file. For example, name it ‘backup_date.xml’ 
 

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

Follow this by deleting the Cryptographic keys on the server: 

Stop the running of your service in Cognos Configuration.

On the Content Manager computer, click ‘File > Export As’. Choose ‘Yes’ at the prompt and save the file. For example, name it ‘backup.xml’ which will be stored in the c11\configuration folder.

Close Cognos Configuration.

Delete the following files (as during the cryptographic keys regeneration process they will be re-created):

  • 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

In the c11\configuration folder, rename ‘backup.xml’ to ‘cogstartup.xml’.

*** WARNING:  Do not start the Cognos Configuration Tool until explicitly instructed, which occurs later in the document. ***

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

Generate the CSR on the Cognos server: 

Change directory to ca11_location\bin

Run the following command (replace CN, OU, O, L, CA, and -H with your server values):

  • 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"

OR (Linux/Unix):

  • ./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"

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

One should be left with a request.csr 

image 2665


Step 6: Request a certificate from your certificate authority

Provide your Certificate Authority (CA) with your .csr (certificate signing request).


Step 7: Manipulate the certificates. 

Convert all the certificates that you received from your CA to Base-64 encoded X.509 format. 
Double click the certificate and select the details tab.

image 2666

image 2667

Select Copy to File and then select Base 64-Encoded X.509

Rename all the files to .crt

For simplicity, rename the files according to this screenshot: 

  • ca-intermediate.crt
  • ca-root.crt
  • servercertificate.crt
  • request.csr

image 2668

Create a “chain.crt” file and include the intermediate and root cert

  -----BEGIN CERTIFICATE-----    intermediate cert    -----END CERTIFICATE-----    -----BEGIN CERTIFICATE-----    root certificate    -----END CERTIFICATE-----

Now all of the certificates should look like the following: 

  • ca-intermediate.crt
  • ca-root.crt
  • certificate.crt
  • chain.crt
  • request.csr

Step 8: Import the Cognos Server Certificates into Cognos 

Verify Cognos is stopped.

Run a new CMD as administrator.

Change directory to the <cognos_install>/bin

Import the certificate in the following order with these commands:

Windows Operating System:

  • ThirdPartyCertificateTool.bat -i -T -r c:/path/to/cert/ca-root.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.bat -i -T -r c:/path/to/cert/ca-intermediate.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.bat -i -e -r c:/path/to/cert/certificate.crt -t /path/to/cert/chain.crt -p NoPassWordSet

Linux:

  • ThirdPartyCertificateTool.sh -i -T -r /path/to/cert/ ca-root.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.sh -i -T -r /path/to/cert/ ca-intermediate.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.sh -i -e -r /path/to/cert/certificate.crt -t /path/to/cert/chain.crt -p NoPassWordSet

Now that the certificates have been imported, one must set up Cognos configuration to accept connections over HTTPS

Open Cognos Configuration

Navigate to the "environment" tab

  • Replace the following instances of HTTP with HTTPS in the paths on the right side.
    • Change External dispatcher URI
    • Change Internal dispatcher URI
    • Change Dispatcher URI for external applications
    • Change Content Manager URIs

Navigate to the “Cryptography > Cognos” tab

  • Change Use third party CA? to "True"; 
  • Alter the following entries according to the specific environment: 
    • Certificate Authority
    • DNS names
    • IP addresses

image 2669
Save the configuration. Start Cognos to test HTTPS is working as expected.

Stop Cognos.

Up until this point, all the Cognos Server certificates have been added into the Cognos trust store and the Cognos Configuration has been configured to accept https connections.


Step 9: Add the Jupyter server certificates to Cognos

Place the Jupyter Server certificates from Step 3 onto the Cognos Server.

Verify that the Cognos services are stopped.

Run a new CMD as administrator.

  • Change directory to the <cognos_install>/bin

Import the certificates in the following order with these commands:

  • ThirdPartyCertificateTool.bat  -i -T -r c:/path/to/cert/ca-root.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.bat -i -T -r c:/path/to/cert/ca-intermediate.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.bat -i -T -r c:/path/to/cert/servercertificate.crt -p NoPassWordSet

Linux:

  • ThirdPartyCertificateTool.sh -i -T -r /path/to/cert/ca-root.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.sh -i -T -r /path/to/cert/ca-intermediate.crt -p NoPassWordSet
  • ThirdPartyCertificateTool.sh -i -T -r /path/to/cert/servercertificate.crt -p NoPassWordSet

Step 10: Add the Cognos certificates into the Jupyter Server

Take the Cognos server certificates and place them on the Jupyter Server in their own directory. Best practice is to place them outside of the Jupyter Server installation directory.

  • mkdir /tmp/CognosCerts

Navigate to the Jupyter Config.conf file 

  • cd <jupyter installation director>/dist/client-scripts/unix/config.conf

Edit the file using a text editor to point to the certificates. It is important to use absolute paths. 

image 2671

It's required to rebuild the server by running the build script

  • <jupyter installation director>/dist/client-scripts/unix/build.sh

Restart the server by running the start script

  • <jupyter installation director>/dist/client-scripts/unix/start.sh

Note that it will now start up as: wss://Jupyter1.ibm.com:8000 and will be reachable on the browser at https://Jupyter1. ibm.com:8000

image 2672

docker ps will show the Hub and the Viewer Running

image 2673

At this point,  the Jupyter Server container is up and running. It has its own certificates as well as trusts the Cognos server certificates.

Document Location

Worldwide

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSTSF6","label":"IBM Cognos Analytics"},"Component":"","Platform":[{"code":"PF016","label":"Linux"}],"Version":"Cognos Analytics Jupyter 11.1.2 +","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
03 November 2021

UID

ibm16116296