TLS Support for ThingWorx
Overview
TLS protection for communication between ThingWorx Analytics and the ThingWorx server has been available since integration with ThingWorx became possible. The option to use TLS for the connection to ThingWorx is available for both Analytics Server and Platform Analytics installations.
In order to connect to a ThingWorx server running on TLS, the following tasks must be completed as part of your ThingWorx installation and setup:
• You have generated a Keystore that contains a signed ThingWorx TLS certificate. The certificate can be from a trusted Certificate Authority or a self-signed certificate.
• You have configured Apache Tomcat for TLS use.
How is the ThingWorx TLS Certificate Imported to the Appropriate Truststore?
The ThingWorx TLS certificate can be imported automatically during Analytics Server or Platform Analytics installation or it can be imported manually. The truststore the certificate is imported to, and the import method itself, depend on which release of each component you are installing, and whether you are doing a new installation or an upgrade. The following chart indicates which import method is appropriate. The detailed procedures are described in the sections below the chart.
|
Release
|
Analytics Server
|
Platform Analytics
|
|---|---|---|
|
9.2 and later
|
New or upgrade installation – Automatic import
Modify, repair – Automatic or Manual import
|
New or upgrade installation – Automatic import
Modify, repair – Automatic or Manual import
|
|
9.0 and 9.1
|
New installation – Automatic or Manual import
Upgrade, modify, repair – Automatic or Manual import
|
New installation – Manual import
Upgrade, modify, repair – Manual import
|
Import the TLS Certificate Automatically During Installation
The simplest way to ensure that your ThingWorx TLS certificate is properly imported is to allow the Analytics Server installer or the Platform Analytics installer to do it automatically.
For 9.2 and later
For both Analytics Server and Platform Analytics, the ThingWorx TLS certificate is imported automatically to a ThingWorx truststore that is generated during the installation procedure. To enable this automatic certificate upload during installation, do the following when prompted for ThingWorx connection information:
• For Use TLS?, select the check box or enter y for Yes. In silent mode, include the appropriate parameter in the launch command and set it to true.
• For Upload ThingWorx Certificate File?, select the check box or enter y for Yes. In silent mode, include the appropriate parameter in the launch command and set it to true.
• Select or enter the path to your ThingWorx TLS certificate.
• Enter a password that will be assigned to the ThingWorx truststore when it is generated during the installation.
When the installation runs, the ThingWorx TLS certificate is imported automatically into the ThingWorx truststore.
For 9.0 and 9.1
For these releases, the ThingWorx TLS certificate needs to be imported to the Java truststore (cacerts). Analytics Server can automatically import a self-signed certificate during installation. But if you are using a TLS certificate from a trusted Certificate Authority, the necessary certificate is already located in the Java truststore when Java is installed.
 | For Platform Analytics, only the manual import method is available in these releases. |
To automatically import the TLS certificate during Analytics Server installation, do the following when prompted for ThingWorx connection information:
• For Use TLS?, select the check box or enter y for Yes. In silent mode, include the appropriate parameter in the launch command and set it to true.
• For Upload a Self-signed ThingWorx TLS Certificate, select the check box or enter y for Yes. In silent mode, include the appropriate parameter in the launch command and set it to true.
• Select or enter the path to your ThingWorx TLS certificate.
• Enter the unique alias name that is assigned to the ThingWorx TLS certificate.
• Enter the password for the Java truststore.
When the installation runs, the ThingWorx TLS certificate is imported automatically into the Java truststore.
Import the TLS Certificate Manually
If you need to import the ThingWorx TLS certificate manually, follow the steps below. This process must be completed before installing the Analytics Server.
For 9.2 and later
Use this manual import procedure when your ThingWorx TLS certificate has expired and you do not want to rerun the Analytics Server or Platform Analytics installer to generate a new certificate and truststore.
For both Analytics Server and Platform Analytics, the ThingWorx TLS certificate must be imported to a ThingWorx truststore as follows:
1. Use the following command to extract the certificate from the ThingWorx Keystore into a separate certificate file. The extraction will not change the Keystore but will make the certificate available for import in a separate file:
keytool -keystore <path to the ThingWorx keystore>.jks -alias <alias name> -export -file <path to the certificate file>.csr
 | Sample command: keytool -keystore ~/apache-tomcat-8.5.33/conf/keystore.jks -alias thingworx -export -file ~/apache-tomcat-8.5.33/conf/thingworx.csr |
2. Use the command below to import the certificate into the ThingWorx truststore that was created during Analytics Server or Platform Analytics installation. When prompted, enter the truststore password.
keytool -alias <must be "thingworx"> -storetype pkcs12 -importcert -file <path to ThingWorx certificate -keystore <path to your installation directory>/certificates/thingworx-truststore.pkcs12
| | Analytics Server sample command: keytool -alias thingworx -storetype pkcs12 -importcert -file ~/apache-tomcat-8.5.33/conf/thingworx.csr -keystore /opt/ThingWorxAnalytics/ThingWorxAnalyticsServer/certificates/thingworx-truststore.pkcs12 Platform Analytics sample command: keytool -alias thingworx -storetype pkcs12 -importcert -file ~/apache-tomcat-8.5.33/conf/thingworx.csr -keystore /opt/ThingWorxAnalytics/PlatformAnalytics/certificates/thingworx-truststore.pkcs12 |
For 9.0 and 9.1
Use this manual import procedure in the following scenarios:
• To import any type of ThingWorx TLS certificate for new, upgrade, modify, or repair Platform Analytics installations. The manual import is the only method available for Platform Analytics in these releases.
• For Analytics Server, use the manual import procedure if your ThingWorx TLS has expired and you do not want to rerun the installer to import the new certificate to the Java truststore.
For these releases, the ThingWorx TLS certificate needs to be imported to the Java truststore (cacerts). But if you are using a TLS certificate from a trusted Certificate Authority, the necessary certificate is already located in the Java truststore when Java is installed.
1. Use the following commands to extract the certificate from the ThingWorx Keystore into a separate certificate file. The extraction will not change the Keystore but will make the certificate available for import in a separate file:
keytool -keystore <path to the ThingWorx keystore>.jks -alias <alias name> -export -file <path to the certificate file>.csr
| | Sample command: keytool -keystore ~/apache-tomcat-8.5.33/conf/keystore.jks -alias thingworx -export -file ~/apache-tomcat-8.5.33/conf/thingworx.csr |
2. Use the command below to import the certificate into the Java truststore. If you have multiple Java installations running, ensure that you provide the truststore for the Java that is running your Analytics Server. When prompted, enter the Truststore password.
keytool -keystore <path to Java truststore> -alias <alias name> -import -trustcacerts -file <Path to the certificate file>.csr
| | Sample command: keytool -keystore/etc/ssl/certs/java/cacerts -alias thingworx -import -trustcacerts -file ~/apache-tomcat-8.5.33/conf/thingworx.csr Note: If you have post-installation trouble connecting to ThingWorx using TLS, check the twas-twx-adapter.log file. If you find an error that the Truststore path is not valid, you might have selected the wrong Java truststore. To import the certificate to a different truststore, follow the procedure in the second half of article CS279983, entitled ThingWorx Analytics. |