Setting up ThingWorx and ThingWorx Flow for Windchill Two-Way SSL Connection (9.0 Only)
 |
This topic is not valid if you are on ThingWorx Flow 9.0.2 and later.
|
PTC recommends using the Secure Sockets Layer (SSL) protocol for a production environment. ThingWorx uses SSL to mutually authenticate the servers and protect the communication between the servers.
Configurations for HTTPS require the use of a certificate of authority. ThingWorx requires that the certificate be trusted by Java. If you are using a certificate that is not trusted by Java, then you must configure Java to trust this certificate. Certificates provided by third-party vendors, such as Verisign and Thawte are Java-trusted certificates of authority.
|
|
This document provides steps that require a minimum of effort to implement HTTPS for your installation. It is not an exhaustive list of all the options available in an SSL configuration.
|
Prerequisites
Before you set up ThingWorx and ThingWorx Flow for Windchill two-way SSL connection, ensure that you meet the following prerequisites:
• Windchill is configured with the following certificates (required only if the Windchill Certificate is a self-signed certificate):
◦ Windchill Certificate
This document assumes that the Windchill Certificate is stored in the server.crt file.
◦ CA Certificate using which the Windchill Certificate is created.
This document assumes that CA Certificate is stored in the rootCA.crt file.
• Make sure that you add the JAVA_HOME/bin to your PATH environment variable.
Steps
Here are the main steps of the process:
|
|
Skip this step if you have already set up SSL for the same instance of ThingWorx for ThingWorx Navigate.
|
Step 1: Configure ThingWorx for Windchill Two-Way SSL Connection
To configure ThingWorx for Windchill Two–Way SSL connection, you must generate a KeyStore file to accept SSL connections using a self-signed certificate. To do that, complete the following steps:
1. Start Command Prompt as Administrator, and browse to the location where you want to save the KeyStore file.
2. Create a Java KeyStore (JKS) file, thingworx.jks and generate an initial public and private key pair with the alias, thingworx:
keytool -genkey -alias thingworx -keyalg rsa -dname "CN=<Fully Qualified Domain Name of the ThingWorx Server>" -keystore thingworx.jks -storetype JKS
When prompted, enter the same password for the KeyStore file and the private key.
Ensure that the password includes letters and numbers only. Special characters are not supported. PTC does not take responsibility for the security of the certificates and the KeyStore and TrustStore files that you generate.
|
|
If you do not start Command Prompt as Administrator, you might receive the following error:
keytool error: java.io.FileNotFoundException: thingworx.jks (Access is denied)
|
3. Generate a self-signed certificate for the key:
keytool -selfcert -alias thingworx -validity 1825 -keystore thingworx.jks -storetype JKS
When prompted for the KeyStore password, enter the same password that you entered for the preceding command.
4. Export the public key for your new self-signed certificate:
keytool -export -alias thingworx -file thingworx.cer -rfc -keystore thingworx.jks -storetype JKS
Step 2: Configure ThingWorx Flow for Windchill Two-Way SSL connection
Part A—Obtain the certificate and private key that is associated with the thingworx.jks KeyStore
1. Download and install KeyStore Explorer.
2. In KeyStore Explorer, open thingworx.jks, the ThingWorx KeyStore that you created in Step 1.
When prompted, enter the correct password of the KeyStore.
3. Right-click thingworx, and click > to export the certificate that is associated with the thingworx.jks KeyStore:
4. In the Export Certificate Chain from entry ‘thingworx’ window, do the following:
a. For Export Length, select Head Only.
b. For Export Format, select X.509.
c. Select the PEM check box.
d. In the Export File field, click Browse to browse to the location where you want to save the exported certificate. For example: thingworx.crt.
e. Click Export.
5. Right-click thingworx, and click > to export the private key that is associated with the thingworx.jks KeyStore.
6. In the Export Private Key Type window, select PKCS#8, and click OK.
7. In the Export Private Key as PKCS#8 from KeyStore Entry ‘thingworx’ window, do the following:
a. Clear the Encrypt check box.
b. Select the PEM check box.
c. In the Export File field, click Browse to browse to the location where you want to save the exported private key. For example: thingworx.key.
d. Click Export.
Part B—Add the ThingWorx and Windchill Certificates to the ThingWorx Flow TrustStore
1. The value of the secret parameter is used to decrypt the TrustStore. To obtain the value of the secret parameter, start Command Prompt as Administrator on the machine where you installed ThingWorx Flow, and run the following commands:
a. pm2 ls
Make note of the value of the ID of any ThingWorx Flow service.
b. pm2 env <ID>
, where <ID> is the ID of any ThingWorx Flow service. For example: the ID of the flow-api service.
c. Copy the value of the CONFIG_IMAGE variable. This is the value of the secret parameter.
2. Run the following command:
<ThingWorx Flow Installation Directory>\cryptography\tw-security-common-nodejs npm link
3. Run the following command to add the thingworx.crt certificate file to the TrustStore:
PtcOrchKeyFileTool set --keyName thingworx-crt --keyPath <Path to thingworx.crt> --configPath <Absolute path to the config.json file of any Flow Service> --secret <Secret to decrypt the TrustStore>
Do not change the value of the keyName parameter. It must be set to thingworx-crt.
4. Run the following command to add the thingworx.key private key file to the TrustStore:
PtcOrchKeyFileTool set --keyName thingworx-key --keyPath <Path to thingworx.key> --configPath <Absolute path to the config.json file of any Flow Service> --secret <Secret to decrypt the TrustStore>
Do not change the value of the keyName parameter. It must be set to thingworx-key.
5. If your Windchill certificate is a self-signed certificate, then do the following:
a. Create a new file, ca.crt.
b. Paste the contents of the rootCA.crt and server.crt file in the ca.crt file.
c. Run the following command to add the Windchill certificate to the TrustStore:
PtcOrchKeyFileTool set --keyName <Windchill-crt>--keyPath <Path to ca.crt file> --configPath <Absolute path to the config.json file of any Flow Service> --secret <Secret to decrypt the TrustStore>
For this command, you can change the value of the keyName parameter. For multiple Windchill servers, ensure that you set different values for the keyName parameter.
6. Restart the ThingWorx and ThingWorx Flow server.
You have successfully set up ThingWorx and ThingWorx Flow for Windchill two-way SSL connection.
You can now add a Windchill two-way SSL connection for any Windchill action. For more information, see Adding a Windchill two-way SSL connection.