Minimal Configuration for Connecting to a Single-Server ThingWorx Platform Installation Using SSL/TLS
To help you get the Connection Server up and running quickly, this topic provides instructions for creating a configuration file for the Connection Server that has the minimum set of properties required to communicate securely with a ThingWorx Platform and your Edge devices. For v.9.0.0, the sample configuration file, cxserver-sample.conf, has been reorganized, with the required properties first, followed by the optional properties. The procedures below follow the organization of this file.
Make sure that you have the following information:
• The application key that this Connection Server will use to authenticate with the ThingWorx Platform.
• The URI and port number of the ThingWorx Platform with which this Connection Server will communicate.
• The path to and name of the keystore file that contains the certificate chain and private key used for establishing the SSL/TLS connections with Edge devices.
• The password for the keystore file.
Required Configuration for the Connection Server
 |
The application key that this Connection Server will use to authenticate with the ThingWorx Platform. PTC recommends using an Application Key with minimal permissions for security reasons. Additionally, for the purposes of this Application Key, no visibility or permissions are required.
|
The instructions below assume that you are using the v.9.0.0 sample configuration file, cxserver-sample.conf, as your starting point.
To configure the Connection Server:
1. Navigate to the conf subdirectory of the Connection Server installation.
2. Copy the cxserver-sample.conf configuration file, rename it to cxserver.conf, and open the new file in a text editor.
The rest of this procedure takes you through the REQUIRED properties. You must set these properties for the configuration file to be valid. An invalid configuration file will prevent the Connection Server from starting.
3. Application key for the Connection Server to use when authenticating with ThingWorx Platform — Replace null with the application key you created for this Connection Server:
cx-server {
transport.websockets {
app-key = null
For example: app-key = "88888888-4444-4444-aaaa-cccccccccccc"
4. The URI of the ThingWorx Platform to which the Connection Server will connect — Replace null with the URL for the ThingWorx Platform:
cx-server {
transport.websockets {
app-key = <your_application-key>
platforms = null
The URI scheme must be wss for a secure (SSL/TLS) connection and ws for an insecure connection. The URI path must be /Thingworx/WS for either secure or insecure connections. For example:
◦ Secure: platforms = "wss://twxplatform:8443/Thingworx/WS"
◦ Insecure: platforms = "ws://twxplatform:8080/Thingworx/WS"
 |
Although it is still possible to specify more than one URI for the platforms property, only the first URI is used. Any subsequent URI is ignored. If you require failover to another instance of ThingWorx Platform, use ThingWorx High Availability Clustering with the v.9.0.0 of the Connection Server and v.9.0.0 of the ThingWorx Platform.
|
5. By default SSL/TLS is enabled for incoming WebSocket connections from edge devices. The Connection Server needs a keystore containing the certificate chain and private key used for establishing the SSL/TLS connections with edge devices.
The keystore must be in a PKCS#12 format and should be created with a password. Specify the file and password properties in the cx-server.protocol.http-server.ssl.key-store group, with the PKCS #12 keystore's path and password, as follows:
cx-server {
protocol.http-server.ssl.key-store {
file = "/opt/secure/keystore.pfx"
password = "ai23#!f0j29QW"
}
}
|
|
If you are currently using a JKS keystore, you will need to convert it to a PKCS #12 keystore. Refer to Converting JKS Keystores to PKCS Keystores for help converting to the supported format. If you must use a Java keystore, refer to Optional Configuration Properties Shown in the Minimal and
HA Sample Configuration Files.
The Connection Server also needs a trust store that contains the certificates necessary to validate the certificate presented by the ThingWorx Platform. By default, the Connection Server uses the default trust store provided by the JRE ("cacerts"). If you need to use a different trust store, refer to Optional Configuration Properties Shown in the Minimal and
HA Sample Configuration Files.
|
6. Save the configuration file. You have completed the minimum required configuration.
Next Steps
At this point, you may want to configure optional properties and/or metrics reporting. If so, leave your configuration file open and follow the steps in the appropriate topic:
When you have completed the configuration, follow these steps:
1. As a best practice, encrypt the configuration for optimal security. Do this before setting the environment variable. For instructions, refer to Setting Up an Encrypted Configuration File.