How to configure Controller Web to use SSL (HTTPS)

Question & Answer

Question

Customer has an existing working Controller Web system, which currently uses HTTP. Customer would like to modify this to use SSL (HTTPS).

How do they do this?

Cause

From Controller 10.3.0 onwards, Controller comes with a limited (cut-down) version of IBM Websphere Application Server.

Specifically, Controller contains the 'Liberty' feature.
Controller's Websphere Liberty contains an HTTP server function, which hosts the 'Controller Web' site.

By default, Controller Web is configured to use HTTP (over TCP port 9080).

This Technote helps customers who would like to modify Controller Web to use HTTPS.

NOTE: The default TCP port (for Controller Web using HTTPS) varies depending on version:

Controller 10.4.0 (or later):
- Backend TCP port = 3443
- Frontend TCP port = 9443
Controller 10.3.0/10.3.1.
- Combined TCP port = 9443

Answer

NOTE:

The following instructions are based on Controller installed in the default location on Windows 2012.
- The instructions may need to vary slightly for other environments
Most of the printscreens are from 10.3.0 RTM, although there are some differences explained if using Controller 10.4.0.
The scripts below are based on a server named: vbracont8ap11.hursley.ibm.com
- They will need to be modified for your server's FQDN name.
At several stages of the process, you are asked to provide a password to:
- create keys
- then import/export certificate keys into keystores.
The author recommends that you use the same password for all keys and keystores.
- In other words, when creating/exporting keys (or importing those keys into keystores) the author suggests not using multiple/different passwords (for different certificates/imports). This is to reduce confusion when typing in passwords in configuration files later.
The example/default password (used in this Technote) is: changeit
- However, the author recommends you use a different (stronger) password from this example.

Steps:

PART ONE - Controller Web (backend)

This section has to be performed for all versions of Controller (10.3.0, 10.3.1, 10.4.0 and so on).

1. Convert your 'main' Controller application server/client portion to use SSL/HTTPS

In other words, perform all the steps inside separate IBM Technote #563063

In the example that I demonstrate below (in this Technote):

I have previously used Appendix #1 (of separate Technote #563063) to create a 10-year self-signed certificate
- I have exported it (from IIS) to: C:\UTILS\self_signed_vbracont8ap11.hursley.ibm.com_2027.pfx
- password = changeit
- I exported it (from Internet Explorer) to: c:\utils\self_signed_vbracont8ap11.hursley.ibm.com_expires_2027.cer
I also previously used Appendix #3 (of Technote #563063) to import that certificate onto my application server, and my client device

=> You will therefore have to slightly modify the following instructions (below) for your circumstances.

2. Launch the standard (HTTP) version of Controller Web, and make sure that this works OK.

For example: http://vbracont8ap11.hursley.ibm.com:9080/fcm.web/login

-------------------------------------------------------------------
The next steps create a java keystore (called "key.jks"), which will be used (by Controller Web) to store the SSL certificate(s).
-------------------------------------------------------------------

3. Right-click on ‘Start’ and choose ‘Command Prompt (Admin)’
4. Run the following commands (depending on your Controller version)

Modern versions of Controller (for example 10.4.1)

cd c:\Program Files\ibm\cognos\ccr_64\fcmweb\jre\bin
keytool -keystore key.jks -importcert -file C:\UTILS\self_signed_vbracont8ap11.hursley.ibm.com_expires_2027.cer

Older versions of Controller (for example 10.3.0)

cd c:\Program Files\ibm\cognos\ccr_64\fcmweb\jre\jre\bin
keytool -keystore key.jks -importcert -file C:\UTILS\self_signed_vbracont8ap11.hursley.ibm.com_expires_2027.cer

When prompted:

password = changeit
New password = changeit
‘Trust this certificate’ = y

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5. RARE/OPTIONAL: This step is only required in some environments (where the SSL certificate is chained to an issuing root certificate).

Import the issuing root certificate to the key.jks keystore, using a command similar to:

keytool -import -trustcacerts -alias issue -file c:\utils\self_signed_vbracont8ap11.hursley.ibm.com_expires_2027.cer -keystore key.jks

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

6. Next, add the ‘regular’ certificate to the key.jks keystore, by running a command similar to:

keytool -importkeystore -destkeystore key.jks -srckeystore C:\UTILS\self_signed_vbracont8ap11.hursley.ibm.com_2027.pfx -srcstoretype PKCS12 -srcstorepass changeit

NOTE:
- Replace ‘changeit’ with the password that your ‘pfx’ file was given (when it was created)
- When prompted for ‘destination keystore password’ = changeit

7. Launch Windows explorer, and browse to the folder: ...\jre\bin

For modern versions of Controller (for example 10.4.1) this is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\bin
For older versions of Controller (for example 10.3.0) this is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\jre\bin

8. Right-click on the file key.jks and choose ‘copy’
9. Paste it into the folder: ...\lib\security

For modern versions of Controller (for example 10.4.1) this is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\lib\security
For older versions of Controller (for example 10.3.0) this is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\jre\lib\security

10. Open the following file inside NOTEPAD:
C:\Program Files\ibm\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\server.xml

11. Inside the section “<featureManager>” look for this line:

12. Remove the comment brackets (to activate SSL usage), so it looks similar to:

<featureManager>
<feature>jpa-2.1</feature>
<feature>localConnector-1.0</feature>
<feature>jaxrs-2.0</feature>
<feature>ssl-1.0</feature>
<feature>jsp-2.3</feature>
<feature>websocket-1.1</feature>
</featureManager>

13. Scroll all the way down to the bottom, to find the section that looks like:

14. Add an extra line, so that this section now looks similar to the following (remember to modify 'changeit' for your system's password):

</webApplication>
<keyStore id="defaultKeyStore" password="changeit" sslProtocol="SSL_TLS" />
</server>

15. Save the file
16. Restart the Windows service ‘IBM Cognos Controller Web UI’

If using Controller 10.4.0 (or later), the also restart the Windows service ‘IBM Cognos Controller Web’

17. Copy the file: ...jre\bin\key.jks

For modern versions of Controller (for example 10.4.1) this is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\bin
For older versions of Controller (for example 10.3.0) this is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\jre\bin

Afterwards, paste it into here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\resources\security

[This destination folder will not exist until you have performed step 14]

18. If you are using CAM authentication (not 'Native') then you will now need to edit the following file: C:\Program Files\IBM\cognos\ccr_64\analytics\templates\ps\portal\variables_CCRWeb.xml

Specifically, change the port number from the current (9080) to 9443 for example:

19. Assuming you have chosen to reconfigure both the 'main' Controller (WSS) server and the Cognos Analytics ('BI') server to use HTTPS, then you will need to modify this Controller Web configuration file accordingly: com.ibm.cognos.fcm.web.properties

Browse to this folder: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web
Open the following file inside NOTEPAD: com.ibm.cognos.fcm.web.properties
Search for "ccrwsUrl" and modify it to be the HTTPS version of your Controller application server, for example: ccrwsUrl=https://myserver.companyname.com/ibmcognos/controllerserver/ccrws.asmx
Search for "biUrl" and modify it to be the HTTPS version of your CA server, for example: ccrwsUrl=https://myserver.companyname.com/ibmcognos/bi/v1/disp
Save changes

For example:

20. Check if the file 'key.p12' exists

In some environments, this file gets erroneously created. If it exists, then it can cause error/problems (for example see Scenario #1 inside separate IBM Technote #6210360).

=> You must delete the file 'key.p12' (if it exists)

TIP: By default, this is located here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\resources\security

21. Reboot the application server

22. The next step depends on what version of Controller you are using:

Controller 10.3.0/10.3.1 - Simply test the Controllerweb url (via a URL similar to: https ://vbracont8ap11.hursley.ibm.com:9443/fcm.web/login) to make sure everything is working OK.
- Assuming it works OK, there is no more work that needs to be done.
Controller 10.4.0 (or later) - It is not possible to check that the 'backend' system is working OK by launching a website. This is because the 'backend' is only a 'rest API'.
- Instead, you must open (inside Notepad) the log file: C:\Program files\ibm\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\logs\com.ibm.cognos.fcm.log
- Assuming that there are no strange errors (in that log file), continue to the next section ("Part Two")

PART TWO - Controller Web Ui (frontend)

This section is for Controller 10.4.0 onwards. It does not need to be performed for older versions of Controller (10.3.0, 10.3.1).

This is because the Controller Web UI is a new feature (from Controller 10.4.0 onwards).

23. Extract the key and the certificate from the pfx file.

Example

The following steps assume that you have already installed 'OpenSSL'

NOTE: This is a third-party (non-IBM) tool. Customers therefore use it at their own risk.

Run a command similar to:
"C:\Program Files\OpenSSL-Win64\bin\openssl.exe" pkcs12 -in C:\UTILS\mysvr.mycorp.com.pfx -clcerts -nokeys -out cert.crt

TIP: You will need to type in the password which you used to create the PFX file

Afterwards, run a command similar to:

"C:\Program Files\OpenSSL-Win64\bin\openssl.exe" pkcs12 -in C:\UTILS\mysvr.mycorp.com.pfx -nocerts -out keyfile.key

TIP: You will first need to type in the password which you used to create the PFX file

Afterwards, you will need to specify a 'PEM pass phrase' password (to protect the file)
IMPORTANT: You must remember the 'PEM pass phrase'. This is the password that you will type into the 'config.js' file (see later)

24. Copy both of the above resulting files (cert.crt , keyfile.key) to the following folder: ..\ccr_64\frontend

TIP: By default, this is here: C:\Program Files\ibm\cognos\ccr_64\frontend

25. Inside that 'frontend' folder, as a precaution create a backup copy of: config.js

26. Open the following file inside NOTEPAD: config.js
27. Edit the settings so that:

Proxies – options – target – port : 3443
Proxies – options – target – protocol : “https:”
Proxies – options – secure : false (Node js will trust the WebSphere certificate)
expressJs – port : “9443”

Inside the section expressJS, inside the 'SSL' portion, perform two changes:

set the passphrase (password) for the file containing the private key (this is the password chosen when prompted for a PEM passphrase earlier)
Enable the ssl section, by uncommenting out the relevant lines. In other words, delete the following characters (inside the SSL section):
- /*
- */

~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

Example

module.exports =
{
    "proxies": [{
        "urlPath": "fcm.web", //root context for Controller Web backend
        "enabled": true,      //forward requests through UI service

        "options": {
            "ws": true,

           // details for Controller web backend connection
            "target": {
                "host": "roconttrain.ro.eurolabs.ibm.com",
                "port": 3443,
                "protocol" : "https:"
            },
   "secure": false

        }
    }],
   //Details for Controller UI service
    "expressJs": {
        "host": "roconttrain.ro.eurolabs.ibm.com", //interface used by Controller Web UI Service
        "port": "9443",              //port used by Controller Web UI Service
        "options": {

            //Enable the below for using HTTPS
            //Note: the protocol in proxies section must also be set to HTTPS

            "ssl": {
                "key": fs.readFileSync(__dirname+"/keyfile.key"),
                "cert": fs.readFileSync(__dirname+"/cert.crt"),
               "passphrase": "changeit"

            }
        },

// enable disable debug messages in browser console
"debug": {

            // websockets/realtime
            "ws" : true
        }
    },
}

~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

=====================================================
Appendices:

Appendix #1
To see the current content of the keystore (for all certificates), run the following command: keytool -list -v -keystore key.jks

Appendix #2
To diagnose/check-for problems:

Browse to here: C:\Program Files\ibm\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\logs
Open the file: console.log

Example:
Launching fcm.web (WebSphere Application Server 8.5.5.9/wlp-1.0.12.cl50920160227-1523) on IBM J9 VM, version pwa6480sr3fp10-20160720_02 (SR3 FP10) (en_GB)
[AUDIT ] CWWKE0001I: The server fcm.web has been launched.
[AUDIT ] CWWKG0028A: Processing included configuration resource: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\shared\config\datasources\dbconfiguration.xml
[AUDIT ] CWWKG0028A: Processing included configuration resource: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\shared\config\datasources\jdbcdrivers.xml
[AUDIT ] CWWKG0028A: Processing included configuration resource: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\shared\config\datasources\datasources.xml
[AUDIT ] CWWKZ0058I: Monitoring dropins for applications.
[AUDIT ] CWWKT0016I: Web application available (default_host): http://vbracont8ap11.hursley.ibm.com:9080/fcm.web/
11:07:44,119 INFO [wmc.base.admin.Log4jConfigurator] Initializing log configuration. Environment: prod
11:07:44,119 INFO [wmc.base.admin.Log4jConfigurator] Loading default log configuration from /prod-log4j.properties
11:07:44,135 INFO [wmc.base.admin.Log4jConfigurator] Extending default log configuration from custom configuration file: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\shared\config\log4j.properties
[AUDIT ] CWWKZ0001I: Application web-ui started in 22.032 seconds.
[AUDIT ] CWWKF0012I: The server installed the following features: [jsp-2.3, servlet-3.1, ssl-1.0, jndi-1.0, localConnector-1.0, jdbc-4.1, appSecurity-2.0, jaxrs-2.0, jaxrsClient-2.0, el-3.0, json-1.0, distributedMap-1.0, websocket-1.1, jpa-2.1].
[AUDIT ] CWWKF0011I: The server fcm.web is ready to run a smarter planet.
=====================================================

Related Information

563063 - How to configure main Controller client (CCR.

6210360 - ** Troubleshooting ** "Server is not reachable or still initializing …

[{"Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"ARM Category":[{"code":"a8m0z000000GnFaAAK","label":"Controller WEB"}],"ARM Case Number":"TS004057991","Platform":[{"code":"PF033","label":"Windows"}],"Version":"10.3.x;10.4.x"}]

Tips

How to configure Controller Web to use SSL (HTTPS)

Question & Answer

Question

Cause

Answer

Related Information

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?