How to configure IBM Cognos Controller Web to use SSL (HTTPS)

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:

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.

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

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

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:

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 (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>

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’

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

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

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>

22. Reboot the application server

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.

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

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:

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": {

            //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 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 …

[{"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"}]

Tips

How to configure IBM Cognos 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?