Question & Answer
Question
Customer has an existing working IBM Cognos Controller Web system, which currently uses HTTP. Customer would like to modify this configuration to use SSL (HTTPS).
How do they do this configuration?
Cause
From version 10.3.0 onwards, IBM Cognos Controller comes with a limited (cut-down) version of IBM WebSphere Application Server.
- Specifically, IBM Cognos Controller contains the 'Liberty' feature.
- IBM Cognos Controller's WebSphere Liberty contains an HTTP server function, which hosts the 'Controller Web' site.
By default, IBM Cognos Controller Web is configured to use HTTP (over TCP port 9080).
- This technote helps customers who would like to modify IBM Cognos Controller Web to use HTTPS.
NOTE: The default TCP port (for IBM Cognos Controller Web that uses HTTPS) varies depending on version:
- Version 10.4.0 (or later):
- Backend TCP port = 3443
- Frontend TCP port = 9443
- Version 10.3.0 and 10.3.1.
- Combined TCP port = 9443
Answer
NOTE:
Steps:
2. Launch the standard (HTTP) version of IBM Cognos Controller Web, and make sure that it works OK.
-------------------------------------------------------------------
The next steps create a Java™ keystore (called "key.jks"), which will be used (by IBM Cognos 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 IBM Cognos Controller version)
When prompted:
6. Next, add the ‘regular’ certificate to the key.jks keystore, by running a command similar to:
8. Right-click on the file key.jks 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.jks
=====================================================
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 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 IBM Cognos Controller installed in the default location on Windows 2012.
- The instructions can vary slightly for other environments
- Most of the print screens are from 10.3.0 RTM, although there are some differences explained when IBM Cognos Controller 10.4.0 is used.
- The scripts and examples, on this document, are based on various servers names.
- They 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 or export certificate keys into keystores.
- The author recommends that you use the same password for all keys and keystores.
- In other words, when you create keys (or import those keys into keystores) the author suggests to not use multiple or different passwords (for different certificates and imports). This suggestion is to reduce confusion when it is required to provide passwords in the configuration files later.
- The example 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)
1. Convert your 'main' IBM Cognos Controller application server and client portion to use SSL/HTTPS
- In other words, perform all the steps inside separate IBM technote #563063
In the example that I demonstrate in this technote:
- I used Appendix #1 (of separate technote #563063) to create a 10-year self-signed certificate
- I 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 used Appendix #3 (of technote #563063) to import that certificate onto my application server, and my client device
=> You need to slightly modify the following instructions for your circumstances.
2. Launch the standard (HTTP) version of IBM Cognos Controller Web, and make sure that it works OK.
-------------------------------------------------------------------
The next steps create a Java™ keystore (called "key.jks"), which will be used (by IBM Cognos 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 IBM Cognos Controller version)
Modern versions (for example 10.4.x)
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 (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. 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, by using a command similar to:
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, by 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 (for example 10.4.1) it is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\bin
- For older versions (for example 10.3.0) it 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 (for example 10.4.1) it is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\lib\security
- For older versions (for example 10.3.0) it 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’
- When you use IBM Cognos Controller 10.4.0 (or later), also restart the Windows service ‘IBM Cognos Controller Web’
17. Copy the file: ...jre\bin\key.jks
- For modern versions (for example 10.4.1) it is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\bin
- For older versions (for example 10.3.0) it is here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\jre\jre\bin
Afterward, paste it into here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\resources\security
[This destination folder does not exist until you performed step 14]
18. If you are using CAM authentication (not 'Native'), then you need to edit the following file: C:\Program Files\IBM\cognos\ccr_64\analytics\templates\ps\portal\variables_CCRWeb.xml
[This destination folder does not exist until you performed step 14]
18. If you are using CAM authentication (not 'Native'), then you 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 choose to reconfigure both the 'main' IBM Cognos Controller (WSS) server and the Cognos Analytics server to use HTTPS, then you modify this IBM Cognos Controller Web configuration file: 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 IBM Cognos 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 whether the file 'key.p12' exists
In some environments, this file gets erroneously created. If it exists, then it can cause an error (for example see Scenario #1 inside separate IBM technote #6210360).
=> You must delete the file 'key.p12' (if it exists)
- By default, this file is located here: C:\Program Files\IBM\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\resources\security
21. Starting with IBM Cognos Controller version 11.0.0 IF1, this step is also required. Edit the following two files. As a precaution, create a backup copy, first.
- C:\Program Files\ibm\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\apps\wmc-rest.war\WEB-INF\spring\spring-security.xml
- Find the following lines and add requires-channel="https" to each of them
<intercept-url pattern="/login" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/login/settings" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/api/databasetypes/**" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/resources/**" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/**" access="isAuthenticated()" requires-channel="https"/>
<intercept-url pattern="/login/settings" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/api/databasetypes/**" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/resources/**" access="permitAll" requires-channel="https"/>
<intercept-url pattern="/**" access="isAuthenticated()" requires-channel="https"/>
- C:\Program Files\ibm\cognos\ccr_64\fcmweb\wlp\usr\servers\fcm.web\apps\wmc-rest.war\WEB-INF\web.xml
- Find the following section and add <secure>true</secure>
<session-config>
<session-timeout>60</session-timeout>
<tracking-mode>COOKIE</tracking-mode>
<cookie-config>
<name>FCM_SID</name>
<secure>true</secure>
</cookie-config>
</session-config>
<session-timeout>60</session-timeout>
<tracking-mode>COOKIE</tracking-mode>
<cookie-config>
<name>FCM_SID</name>
<secure>true</secure>
</cookie-config>
</session-config>
22. Reboot the application server
23. The next step depends on what version of IBM Cognos Controller that you are using:
23. The next step depends on what version of IBM Cognos Controller that you are using:
- Version 10.3.0 or 10.3.1 - Simply test the IBM Cognos Controller web url (use 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.
- Version 10.4.0 (or later) - It is not possible to check that the 'backend' system is working OK by launching a website. It 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 - IBM Cognos Controller Web Ui (frontend)
This section is for version 10.4.0 onward. It does not need to be performed for older versions of IBM Cognos Controller (10.3.0, 10.3.1).
- It is because the IBM Cognos Controller Web UI is a new feature (from IBM Cognos Controller 10.4.0 onward).
24. Extract the key and the certificate from the pfx file.
25. Copy both of the resulting files (cert.crt, keyfile.key) to the following folder: ..\ccr_64\frontend
Example
The following steps assume that you installed 'OpenSSL'
- NOTE: It 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
- HINT: You need to type in the password, which you used to create the PFX file
Afterward, 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
HINT: First, you need to type in the password that you used to create the PFX file
- Afterward, you need to specify a 'PEM pass phrase' password (to protect the file)
- IMPORTANT: You must remember the 'PEM pass phrase'. It is the password that you type into the 'config.js' file (see later)
25. Copy both of the resulting files (cert.crt, keyfile.key) to the following folder: ..\ccr_64\frontend
- HINT: By default, it is here: C:\Program Files\ibm\cognos\ccr_64\frontend
26. Inside that 'frontend' folder, as a precaution create a backup copy of: config.js
27. Open the following file inside NOTEPAD: config.js
28. Edit the settings so that:
28. Edit the settings so that:
- Proxies – options – target (Controller web backend connection) – port: 3443
- Proxies – options – target – protocol: “https:”
- Proxies – options – secure: false (Node js trust the WebSphere certificate)
- This 'Proxies' section is new as of IBM Cognos Controller 10.4.2 FP2. This section is to be changed ONLY if you have configured the 'main' application with HTTPS
- Proxies - options - target (Controller Server connection) - port 443
- Proxies – options – target – protocol: “https:”
- Proxies – options – secure: false
- expressJs – port: “9443”
--> config.js image for IBM Cognos Controller previous to 10.4.2 FP2
--> config.js image for IBM Cognos Controller as of 10.4.2 FP2
Inside the section expressJS, inside the 'SSL' portion, perform two changes:
- set the passphrase (password) for the file that contains the private key (it is the password chosen when prompted for a PEM passphrase earlier)
- Enable the ssl section, remove the comment characters out of 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": "your_controllerwebserver.domain.com",
"port": 3443,
"protocol" : "https:"
},
"secure": false
}
}],
//Details for Controller UI service
"expressJs": {
"host": "your_controllerwebserver.domain.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": "your_controllerwebserver.domain.com",
"port": 3443,
"protocol" : "https:"
},
"secure": false
}
}],
//Details for Controller UI service
"expressJs": {
"host": "your_controllerwebserver.domain.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 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
[{"Type":"MASTER","Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"ARM Category":[{"code":"a8m0z000000GnFaAAK","label":"Controller-\u003EBA - Cognos Controller-\u003EController WEB"}],"ARM Case Number":"TS004057991","Platform":[{"code":"PF033","label":"Windows"}],"Version":"All Versions"}]
Was this topic helpful?
Document Information
Modified date:
01 April 2024
UID
swg21998458