IBM Support

How to configure main Controller client (CCR.EXE) to use HTTPS (SSL)

Question & Answer


Question

Customer would like to convert the system so that all the communication (between the client and server) is secured via SSL.
  • In other words, they would like to change the CCR.EXE client to communicate from the default (HTTP) to HTTPS.

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, if a customer would like to secure the network traffic by SSL, then they can use the technique described inside this Technote.

Answer

===========================================

IMPORTANT:

  • This Technote specifically relates to the scenario where the customer is not using a dedicated 'Gateway' server. In other words, they are not using the 't=controller' configuration.
    • (RARE) If you are using a gateway (t=controller) then see separate IBM Technote #1345570 for more guidance.
  • It also does not cover the steps needed to convert the 'Controller Web' website (a new feature from Controller version 10.3 onwards) to using HTTPS
    • If you are using Controller Web then see separate IBM Technote #291423 for more guidance.
For more details, see separate IBM Technote #563065.

===========================================

Steps:

The following steps are based on Controller 10.3.0 and 10.3.1, installed on Windows 2012 R2.

  • The instructions may need to be altered slightly for different versions of Controller/Windows.
 

Controller application server (Part One):

1. Ensure that you have an existing working system (everything working OK without HTTPS)

  • In other words, the Controller system has already been tested and working (via HTTP)
 

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

(a) Commercial
For example purchase one from Verisign (or other third-party vendor).
  • This is the easiest method, since all the client devices will already trust the certificate
  • However, naturally there is a cost associated.

or (b) 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 #156485)
  • However, it is the cheapest (no cost).

3. 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
  • These instructions assume that the FQDN name = sbracs-cont1.hursley.ibm.com
 

4. Get/purchase/create the SSL certificate

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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Commercial SSL certificate

Contact your third-party supplier (for example 'Verisign') to obtain an SSL certificate that is compatible with IIS.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Self-signed SSL certificate

There are many different methods to create a self-signed SSL certificate that is compatible with IIS.

  • See appendix #1 (at the end of this Technote) for one easy method.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

5. Install/register the SSL certificate on the Controller application server (the one hosting the IIS website 'controllerserver' which powers the main 'classic' system).

- If using a commercial SSL certificate, then follow the advice from your third-party supplier

- If using a self-signed SSL certificate, then:

  • Typically this is done by double-clicking on the '.CER' file. [Alternatively, if you have a '.p7b' certificate, see Appendix #2 at the end of this Technote].
  • IMPORTANT: You must make sure that you choose to import into the correct store location (on the client device). Specifically, it should be: Local Computer\Trusted Root Certification Authorities:

    • [For more details, see Appendix #3 at the end of this Technote].

6. If using a self-signed SSL certificate, then install/register the SSL certificate on all client devices (for example end user's PCs, or the Citrix servers).

  • This is done in the same way as previous step #5.

7. Inside 'Internet Information Services (IIS) Manager':
  • Select 'Default Web Site'
  • Click 'Bindings'
  • Click 'Add'
  • Change type to: https
  • Click 'Select' and choose the certificate we chose earlier, for example:
  • Click OK, Close.

8. Test that the SSL/HTTPS communication is working OK
  • On the Controller application server itself, launch the HTTPS version of the Controller diagnostic website, for example:  https://myservername.mycompany.com/ibmcognos/controllerserver/ccrws.asmx
  • Then on the client device(s), perform the same test, for example:  https://myservername.mycompany.com/ibmcognos/controllerserver/ccrws.asmx
Make sure that there are no error messages.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Report Server (CA or BI):

Controller requires a report server (CA or BI) to power some of its functionality (for example standard reports and CAM authentication). For example:

  • Controller 10.3.0 comes bundled with Cognos BI 10.2.2
  • Controller 10.3.1 comes bundled with Cognos Analytics (CA) 11.0.7

If you want to encrypt CA/BI server <=> client traffic then you will need to perform the steps in this section.

9. On the Controller application server, launch "Controller Configuration"
10. Open section 'Report Server'
11. Check the current value for 'Report Server', for example:

  •  http://servername:9300/bi/v1/disp      ...    This is the default setting for CA, showing that it is NOT integrated with Microsoft IIS
  •  http://servername/ibmcognos/bi/v1/disp      ...    This shows that the CA/BI report server had been changed so that it is integrated with Microsoft IIS. Typically this is done to allow single sign on (SSO) with Microsoft Active Directory.

12. On the report server (CA/BI) modify it to use SSL

  • If your CA/BI report server is not integrated with IIS, then:
    • (a) Use the instructions provided with your software, to change CA/BI to using SSL. An example is given in the link at the end of the Technote.
    • (b) skip to the next step.
  • If your CA/BI report server is integrated with IIS, then perform the steps below:
    • (a) Logon to the Report server (the one hosting the Cognos Analytics or BI IIS website, which is mentioned in step 11)
    • (b) Create / install / register a SSL certificate on that IIS server (using similar instructions to what you did earlier for the Controller application server)
    • (c) Install the SSL certificate on both the Controller application server and the client device
    • (d) Test that both the Controller application server and client device can successfully connect to the CA/BI website (https://servername/ibmcognos) using HTTPS/SSL with no errors).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Controller application server (Part Two):
13. Configure 'Report Server', to use HTTPS (not HTTP)
  • For example: https://myserver.mycompany.com/ibmcognos/cgi-bin/cognos.cgi


14. If using the 'web client' via CDS (very rare), then open section 'Client Distribution Server' and configure the settings, for example:
  • CASURL: https://servername.domain.com/ibmcognos/controllerbin
  • WSSUrl: https://servername.domain.com/ibmcognos/controllerserver
  • HelpUrl: https://servername.domain.com/ibmcognos/ControllerHelp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Client PCs:
15. On each of the client PCs:
(a). Install/register the SSL certificate on the client.
  • This should already have been done - see steps 5 and 6 above)

(b) 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 #156485.

(c) When installing/configuring the 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/controllerserver
  • 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.  

===========================================

APPENDICES:

===========================================


Appendix #1 - Easy method to create a self-signed SSL certificate
1. Open Windows PowerShell with elevated permission (Run as Administrator)

2. Type the following command:
  • Replace the text, in bold, with the appropriate values for your environment. 
  • The below script creates a three (3) years certificate.  Change the -notafter switch to increase or decrease the age length of the certificate.

$selfSignedRootCA = New-SelfSignedCertificate -DnsName server_name.fyre.ibm.com -notafter (Get-Date).AddYears(3) -CertStoreLocation Cert:\LocalMachine\My\ -KeyExportPolicy Exportable -KeyUsage CertSign,CRLSign,DigitalSignature -KeySpec KeyExchange -KeyLength 2048 -KeyUsageProperty All -KeyAlgorithm 'RSA' -HashAlgorithm 'SHA256' -Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider'

$CertPassword = ConvertTo-SecureString -String "changeit" -Force -AsPlainText

$selfSignedRootCA | Export-PfxCertificate -FilePath path/filename.pfx -Password $CertPassword

image-20240408085650-1

Note:  You will find your .pfx in the path you have specified during the command.  But you will also notice that the certificate now exists in IIS under Server Certificates.image-20240408090237-2

image-20240408090309-3

3. Click on Start and type : mmc certmgr.msc



4. Browse to: Trusted Root Certificate Authorities -> Certificates
5. Right click on 'Certificates' and choose 'All Tasks - Import'
6. Click 'Next'
  • Browse to the file you created earlier (for example C:\Certificates\teenier1_fqdn.pfx)
  • Click 'Open', 'Next'
7. Type in the password, and click 'Next'

IMPORTANT: It is important to take care on the next step!
8. You must choose which store to use.
  • Click the 'Browse...' button
  • Tick "Show physical stores"
  • Browse to "Trusted Root Certificate Authorities - Local Computer"
  • Click 'OK'
  • Click 'Next'
  • Click 'Next', 'Finish'.
9. Click 'OK' to the popup message.
   image-20240408091712-5

Now we need to export the certificate (for use by the clients):

10. Logon to the Controller application server (where you have already performed the above steps)
11. From the Start button, type Internet Options
12. Open Internet Options - Control Panel
13. Select tab "Content"
14. Click "Certificates"
15. Select the tab "Trusted Root Certification Authorities"
16. Highlight the certificate you made earlier (HINT: Check its expiration date if you are unsure!), and click "Export..."
17. Click 'Next', 'Next' and then select "DER encoded binary X.509 (.CER)" then 'Next'
image-20240408092844-1
18. Type in a sensible filename (for example 'C:\Certificates\teenier1_fqdn.cer')'Save' , and click 'Next' then 'Finish'
19. Click 'OK' to the popup message
     image-20240408093251-3

===========================================


Appendix #2 - If you have a '.p7b' certificate (instead of .CER)
If you have a '.p7b' certificate, you can instead do the following:
  • From the Start button, type Internet Options
  • Open Internet Options - Control Panel
  • 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.

===========================================
Appendix #3 - Importing the certificate on a client device

There may be different methods for different operating systems. The following steps are known to work on most Windows Operating Systems:

1. Logon to the client device as a Windows administrator

2. Click Start button

3. Type the following: mmc

  image-20240408103507-1

4. Click "File - Add/Remove Snap-in..."
5. Click "Certificates" then 'Add'
6. VITAL: You must choose 'Computer account':


7. VITAL: Choose: Local computer


8. Click Finish and OK

9. Expand "Certificates (Local Computer)", "Trusted Root Certification Authorities" and right-click on 'Certificates' and choose "All Tasks - Import...":


10. Browse to your SSL certificate (.CER file)

11. VITAL: During the import process:

  • Choose "Place all certificates in the following store"
  • Click 'Browse'
  • Tick the box 'Show physical Stores'
  • Expand 'Trusted Root Certification Authorities'
  • Choose 'Local Computer':


12. Click OK, and complete the wizard.

===========================================

===========================================

[{"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"Component":"Controller","Platform":[{"code":"PF033","label":"Windows"}],"Version":"10.3.0, 10.3.1","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
08 April 2024

UID

swg22004920

Page Feedback