IBM Support

How to secure Controller client <=> server communication via SSL (HTTPS) when using a separate Gateway server (distributed / DMZ)

Troubleshooting


Problem

Customer is using a gateway with the 't=controller' (10.4.X it is called 'controller') configuration.
  
********************************************************
NOTE: This is very rare. Most customers do not use this configuration
=> Therefore, most customers should instead read separate technote #2004921 for advice on their configuration.
********************************************************
Customer would like to convert their system so that all the communication (between the client and server) is secured via SSL.
  • In other words, they would like to change all client communication from the default (HTTP) to HTTPS.

Symptom

The customer would like their server architecture to look similar to this:

Cause

In most cases, customers decide not to enable SSL (HTTPS) between client (end user) and their server layer.
  • This is because most customers have their entire Controller system located inside a secure private LAN/WAN. This means that they trust the computers inside their network (for example do not worry about 'man in the middle' attacks.
 

However, some customers (rare) want to deploy Controller to users who have no permanent (secure) WAN link. For example, they want to deploy directly across the public (insecure) internet.

  • In this case, there are two options to keep the system secure:
 

(a) Implement a VPN (Virtual Private Network) across the Internet

  • This is generally recommended, because it is typically easier to implement and maintain.
  • This is the most common solution
  • By implementing this, most customers decide that they do not need to use SSL/HTTPS.
 

(b) Create a 'gateway' server (located in a public portion of your infrastructure, called the 'DMZ').

  • This is publicly accessible (reachable) from the internet. After creating it, implement SSL (HTTPS) between the Controller client and this 'Gateway' (DMZ) server to secure all the communication (between client and gateway server).
  • This configuration is rarely used, because it is more complicated to implement and maintain.
    • However, this Technote shall describe how to configure this solution (b).

Environment

The most likely environment (where using SSL would be most appropriate) is where the customer has a distributed environment (multiple servers):

(1) Gateway server (which client machines connect to)

  • This acts as a proxy/relay to route traffic between client <=> main application server

(2) 'Main' Controller application server (never directly accessed by client devices).

In other words, they have already installed a separate Gateway server (for example, inside a DMZ) and a separate 'main' application server (for example, on the LAN).

  • For more information, see the guidelines inside separate technote #1367311.
  • This technote shall assume that this is the environment/architecture that the customer has.

In the above scenario, the customer would now like to configure their Controller 'gateway' server to use SSL (HTTPS) encryption between the users (client) and the server (gateway).
  • In other words, we shall not enable/SSL on the 'main' application server
Therefore we shall still use the default (HTTP) when communicating between the 'gateway' and 'main' application servers.
  • In other words, we shall only enable SSL on the 'gateway' (for client <=> gateway traffic).

Resolving The Problem

Before continuing, make sure you are aware that these instructions are only for gateway ('t=controller' or 'controller') configurations.
  • TIP: See separate IBM technote #563065 for more details.
 

The following instructions are mostly based on Controller 10.1 using Cognos BI.

  • They may need to be modified slightly for different versions of Controller and/or Cognos Analytics (CA)
 

Pre-requisites:

0. If you are using Cognos Analytics (not the older "Cognos BI") product then you will need to upgrade Controller to 10.4.x

  • The "t=controller" mechanism will not work with CA, for Controller 10.3.1 or earlier versions
  • For more details, see APAR PH13509

1. We assume that there is already a working 'main' Controller application server and database server.

2. Create a gateway server

  • For details, see separate IBM technote #1367311.

3. Configure the gateway server to use standard HTTP (not SSL)
  • Test this configuration to make sure that it works OK (before proceeding)
 

4. Decide on whether you want to use 'commercial' or 'self-signed' SSL certificates

  • Commercial - For example purchase one from Verisign or other vendor.
    • This is the easiest method, since all the client devices will already trust the certificate
    • However, naturally there is a cost associated.
  • Self-signed - For example create your own certificate from your own 'certificate authority' in your network
    • This method is the most complicated, since you must manually import the certificate into all your devices (see separate technote #1495669)
    • However, it is the cheapest (no cost).

5. Choose the FQDN name (for example controllerserver.domain.com) that your SSL certificate will refer to

  • IMPORTANT: You must use this same FQDN name for all of the settings (see later on). For example, if you use a different name (for example NetBIOS or IP address) for the server, the SSL certificate will not work correctly.
 

6. Get/purchase/create the SSL certificate

  • Typically this is a file that has a 'CER' extension
 

7. Install/register the SSL certificate on the client and all servers.

  • Typically this is done by simply double-clicking on the '.CER' file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, for importing a '.p7b' certificate, you can instead do the following:
  • In Internet Explorer (e.g. IE6) open Tools/Internet Options
  • Switch to the Content tab
  • Click Certificates
  • Select "Trusted Root Certification Authorities" tab
  • Click Import
  • Browse to the .p7b file and click next
  • Click radio button "Place all certificates in the following store". Certificate store should be "Trusted Root Certification Authorities"
  • Click next
  • Select "Trusted Publishers" tab
  • Click Import
  • Browse to the .p7b file and click next
  • Click radio button "Place all certificates in the following store". Certificate store should be "Trusted Publishers"
  • Click next
  • Start a fresh web browser window.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8. Test that the SSL/HTTPS communication is working OK (between the client devices and the gateway server).
  • Make sure that there is no error appearing.
  • TIP: When testing the HTTPS communication (see later) your browser must use this same FQDN name. For example, https://controllerserver.domain.com will work OK, but https://<IP address> will not work without an error

'Main' Application Server:
As mentioned before, ensure that *all* SSL-related settings (client and server) refer to the correct FQDN name (for example controllerserver.domain.com) not any other version of the name (for example the NetBIOS name 'controllerserver')

1. Launch 'Cognos Configuration'
2. Open section 'Environment'
3. Configure Gateway URI, for example: https://<gateway.domain.com>:443/ibmcognos/cgi-bin/cognos.cgi

4. Launch "Controller Configuration"
5. Open section 'Report Server'
6. Configure 'Report Server', for example: https://<gateway.domain.com>/ibmcognos/cgi-bin/cognos.cgi

Gateway Server:
0. If using Cognos Analytics (not Cognos BI) then you will need to configure CGI gateway
  • A link to the instructions are at the end of this technote
1. Launch 'Cognos Configuration'
2. Open section 'Environment'
3. Configure the settings, for example:
  • Dispatcher URI's for gateway: http://<appserver>:9300/p2pd/servlet/dispatch/ext
  • Controller URI for gateway: http://<appserver>:80/ibmcognos/controllerserver/ccrws.asmx

4. Launch "Controller Configuration"
5. Open section 'Client Distribution Server'
6. Configure the settings, for example:
  • CASURL: https://<gateway.domain.com>/ibmcognos/controllerbin
  • WSSUrl: https://<gateway.domain.com>/ibmcognos/cgi-bin/cognos.cgi?t=controller ( .../ibmcognos/bi/v1/controller for 10.4.x)
  • HelpUrl: https://<gateway.domain.com>/ibmcognos/ControllerHelp

Client PCs:
1. Install/register the SSL certificate on the client.
  • Typically this is done by simply double-clicking on the '.CER' file

2. If you are using a 'self-signed' certificate, then you must also install the SSL certificate into the Java runtime environment (JRE) on the client, so that the JRE trusts the self signed certificate.
  • For steps on how to do this, see separate IBM technote #1495669.

3. When installing/configuring the IBM Cognos Controller client, ensure that all the installation settings/configuration etc. simply refers to "https://" instead of "http://".
This is extremely easy if using the standard 'local' client (CCRLocalClient.MSI). For example, during the installation wizard choose settings similar to:
  • WSSUrl: https://<gateway.domain.com>/ibmcognos/cgi-bin/cognos.cgi?t=controller ( .../ibmcognos/bi/v1/controller for 10.4.x)
  • HelpUrl: https://<gateway.domain.com>/ibmcognos/ControllerHelp

If you have chosen to use the more complicated 'web client', then all the other settings must also refer to HTTPS.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"Component":"Controller","Platform":[{"code":"PF033","label":"Windows"}],"Version":"10.3.0;10.3.1;10.4.0;10.4.1;10.4.2","Edition":"All Editions","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Historical Number

1020540

Document Information

Modified date:
10 November 2021

UID

swg21345570

Page Feedback