Configure SSL for Planning Analytics TM1 Web/Spreadsheet Services with an existing keystore

These procedures let you secure TM1® Web/IBM® Planning Analytics Spreadsheet Services using a custom keystore.

About this task

The following conditions must be met before you can configure SSL for TM1 Web/IBM Planning Analytics Spreadsheet Services:

Your keystore/certificate file must already be in PKCS12/PFX format and contain the complete certificate chain.
The file must be placed in a location outside the IBM Planning Analytics Spreadsheet Service installation directory. A directory "next to" (at the same level as) the installation directory is recommended. For example if your installation directory is C:\Program Files\ibm\cognos\tm1web, the file could be placed in C:\Program Files\ibm\cognos\certificates.
In this document, we use the path C:\Program Files\ibm\cognos\certificates to refer to the location of your keystore file, and C:\Program Files\ibm\cognos\certificates\customKeystore.pfx as the file path for your keystore file. Your actual file path will differ.
The file must be placed in the <install_dir>\tm1web\bin64\ssl\ directory.
The IBM Planning Analytics Spreadsheet Service must be stopped before you can proceed with configuration.

You must also know the location of the following items before executing the keytool command:

keytool.exe - located in <install_dir>\tm1web\jre\bin\
ibmtm1.arm - located in <install_dir>\tm1_64\bin64\ssl

Procedure

Configure the Planning Analytics Spreadsheet Services service with a custom keystore.
1. Open Windows Services and check the status of your IBM Planning Analytics Spreadsheet Services. If the service is running, stop it before you proceed to the next step.
2. Open <install_dir>\tm1web\wlp\usr\servers\tm1web\server.xml in a text editor.
3. Update the httpPort and httpsPort parameters to reflect the ports you would like to use. To disable HTTP altogether, set httpPort="-1". For example,
```
<httpEndpoint id="defaultHttpEndpoint" httpPort="-1" httpsPort="9510" host="*" removeServerHeader="true">
</httpEndpoint>
```
4. In server.xml, replace the existing keyStore entry with:
```
<keyStore id="defaultKeyStore" location="C:\Program Files\ibm\cognos\certificates\customKeystore.pfx" password="your_password" />
```
  If server.xml does not have a keyStore entry, add the following line immediately following the last <application> tag in server.xml:
```
<keyStore id="defaultKeyStore" location="C:\Program Files\ibm\cognos\certificates\customKeystore.pfx" password="your_password" />
```
5. Save and close the server.xml file.
6. Open a Command Prompt as an administrator, then go to <install_dir>\tm1web\jre\bin\.
7. Because TM1 Web is using a new keystore, you must include the TM1 Server certificates in the keystore file. If the TM1 Server certificates are not present, you can't see your TM1 Servers in TM1 Web. Execute the following command:
```
keytool -importcert -keystore "C:\Program Files\ibm\cognos\certificates\customKeystore.pfx" -storepass your_password -storetype pkcs12 -noprompt -alias ibmtm1 -file ..\..\bin64\ssl\ibmtm1.arm
```
8. If you communicate with any other TM1 Servers or applications that use different certificates, you must repeat the previous step, importing any additional certificates you require.
9. Restart IBM Planning Analytics Spreadsheet Services in Windows Services.
Validate your SSL configuration.
The following validation steps apply to the Chrome web browser. If you are using another browser, you'll need to adjust the steps as necessary.
1. After the IBM Planning Analytics Spreadsheet Services service starts, access your TM1 Web URL using Chrome, for example: https://machine_name:9510/tm1web.
  
  You may encounter a warning. If you do, it is likely because you haven't told your computer to trust the Root Certificate Authority and Intermediate Certificate Authority that are used to sign the Planning Analytics certificate. To resolve the untrusted certificate warning, see the following technote: http://www.ibm.com/support/docview.wss?uid=ibm10879929.
2. If your certificates are valid and trusted, you should see something similar to this on the Security tab of the Chrome developer tools:
3. If you don't see a particular TM1 Server in your list of servers in TM1 Web, you may not have imported the TM1 Server certificate in to your keystore. Please see step 1h for details on importing TM1 Server certificates to your keystore.