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 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:
Steps:
2. Launch the standard (HTTP) version of Controller Web, and make sure that this works OK.
-------------------------------------------------------------------
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)
When prompted:
5. OPTIONAL: The following steps 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:
6. Next, add the ‘regular’ certificate to the key.jks keystore, by running a command similar to:
8. Right-click on the file key.jsk and choose ‘copy’
9. Paste it into the folder: ...\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:
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):
15. Save the file
16. Restart the Windows service ‘IBM Cognos Controller Web UI’
17. Copy the file: ...jre\bin\key.jsk
=====================================================
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:
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.
=====================================================
- 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 import/export certificate keys
- The default password is: changeit
- The author recommends that you use the same password for ALL exports/imports (do not use multiple/different passwords for different certificates)
- This is to reduce confusion when typing in passwords in configuration files later.
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 #2004920
In the example that I demonstrate below (in this Technote):
- I have previously used Appendix #1 (of separate Technote #2004920) 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 #2004920) 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.
-------------------------------------------------------------------
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
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
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. OPTIONAL: The following steps 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
- 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.jsk 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>
<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>
<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.jsk
- 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
[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. Reboot the application server
21. The next step depends on what version of Controller you are using:
21. 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).
22. Extract the key and the certificate from the pfx file.
23. Copy both of the above resulting files (cert.crt , keyfile.key) to the following folder: ..\ccr_64\frontend
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
"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)
23. 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
24. Inside that 'frontend' folder, as a precaution create a backup copy of: config.js
25. Open the following file inside NOTEPAD: config.js
26. Edit the settings so that:
26. 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": {
{
"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"
}
},
//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": {
"debug": {
// websockets/realtime
"ws" : true
}
},
}
"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.
=====================================================
[{"Business Unit":{"code":"BU002","label":"Business Analytics"},"Product":{"code":"SS9S6B","label":"Cognos Controller"},"Component":"Controller","Platform":[{"code":"PF033","label":"Windows"}],"Version":"10.3.0, 10.3.1, 10.4.0","Edition":""}]
Document Information
Modified date:
24 January 2020
UID
swg21998458