IBM Support

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

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


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

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


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

13. Save the file
14. 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

15. 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]

16. 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:
image-20190712140044-1
17. Reboot the application server

18. 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).
19.    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)

20. 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
21. Inside that 'frontend' folder, as a precaution create a backup copy of:    config.js
22. Open the following file inside NOTEPAD:      config.js
23. 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.
=====================================================

Internal Use Only

RC 7th Feb 2017: Information via SameTime with Claudiu.

  • Using a self signed certificate:

    1. Create a self signed certificate using the keytool

    Ex: >keytool - genkey -keyalg RSA -alias key - keystore key.jks -storePass [yourpassword] -validity 360 -keysize 2048

    Complete the required fields

    2. Copy the .jks file into

    [websphereHome]\usr\servers\[my server]\resources\security

    3. Edit the server.xml to match the created keystore

    Ex: <keyStore id="defaultKeyStore" password="[your password]" sslProtocol="SSL_TLS" />



    Using an authentic certificate

    1.Convert your key and certificate to the pkcs12 (note: the private key must be included as well in the keystore)

    Import the certificate in IIS and then export the private key: Certificate Manager - Personal - Certificates, select your certificate, right click->all tasks->export and select to export the private key

    2. Import the pfx file in a keystore

    >keytool -importkeystore -destkeystore key.jks -srckeystore [privatekey].pfx -srcstoretype PKCS12

    3. Copy the .jks file into

    [websphereHome]\usr\servers\[my server]\resources\security

    4. Edit the server.xml to match the created keystore

    Ex: <keyStore id="defaultKeyStore" password="[your password]" sslProtocol="SSL_TLS" />



    Note:
    In case of getting "java.io.IOException: Keystore was tampered with, or password was incorrect" when updating WebSphere and using a previous key.jks try starting the web server with the --clean option

[{"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:
17 July 2019

UID

swg21998458