Minimal Configuration to Connect to a Single-Server ThingWorx Platform Using SSL/TLS
This topic presents the minimal configuration requirements for a ThingWorx eMessage Connector to connect to a single-server mode ThingWorx Platform. The first section below presents the properties that you must set for the Connector to connect to the platform. The second section presents optional configuration properties. Optional configuration includes settings for file transfers, remote sessions, metrics reporting, and more.
Required Configuration
These instructions create a configuration file for the eMessage Connector that has the minimum set of properties required to communicate securely with a single-server mode ThingWorx Platform and with your Edge devices.
1. Navigate to the <emessage_connector_install>/conf directory
2. Rename the emessage-sample.conf configuration file to emessage.conf . Then open the emessage.conf 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 eMessage Connector from starting.
3. Application key for the eMessage Connector to use when authenticating with ThingWorx Platform — Replace null with the application key you created for this Connector:
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 Connector 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 with the v.2.0.0 or later of the eMessage Connector and v.9.0.0 or later of the ThingWorx Platform. While you can still use the previous version of ThingWorx High Availability (Active-Passive) Clustering with v.8.5.x of ThingWorx Platform and v.1.2.0 of the eMessage Connector, it is strongly recommended that you upgrade to v.9.0.0 or later of the platform and v.2.0.0 or later of the eMessage Connector. These later releases contain security fixes and enhancements as well as new features, making them the best choice for securing your IoT network.
|
5. By default SSL/TLS is enabled for incoming HTTPS connections from Edge devices and the Global Access Server (GAS). The Connector 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.ssl.key-store group, with the PKCS #12 keystore's path and password, as follows:
cx-server {
protocol.ssl.key-store {
file = "/opt/secure/keystore.pfx"
password = "ai23#!f0j29QW"
}
}
 |
Pay particular attention to the exact spelling of the names of the keys in the configuration file. Making a simple mistake such as leaving the dash off of the key-store tag, for example, can result in obscure errors, depending on how the Connector handles HTTP/S calls from Axeda eMessage agents.
|
|
|
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 instructions. If you must use a Java keystore, refer to Optional Configuration Properties.
The Connector also needs a trust store that contains the certificates necessary to validate the certificate presented by the ThingWorx Platform. By default, the Connector uses the default trust store provided by the JRE ("cacerts"). If you need to use a different trust store, refer to Optional Configuration Properties.
For information on configuring SSL/TLS for the connection between an Axeda Global Access Server (GAS) and an eMessage Connector, refer to Configuring the Connector for Remote Access. For information on configuring the GAS itself to use SSL/TLS refer to the ThingWorx Global Access Server Reference, v.7.1.0, which is available on the Reference Documents page of the PTC Support site.
|
6. If you plan to transfer files between Axeda Agent devices and the ThingWorx Platform, you must configure the locations of the download and upload endpoints on the eMessage Connector where the transferred files can be accessed by the Axeda Agent devices and the ThingWorx Platform. The Agent will use these URLs when transferring files. The url properties are in the emessage.file-transfer.download and emessage.file-transfer.upload groups:
emessage {
file-transfer {
download {
url = "https://eMessageConnector:8443/download"
}
upload {
url = "https://eMessageConnector:8443/upload"
}
. . .
}
}
7. Save the configuration file. You have completed the minimum required configuration.
Next Steps
At this point, you may want to configure optional properties. 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. Follow the instructions in Setting Up an Encrypted Configuration File for an eMessage
Connector to encrypt the configuration file.
 |
If you are setting up an internal testing environment, this step is strongly recommended but not required. Do not skip this step when setting up a production environment. If you choose not to encrypt the configuration file, set the environment variable to point to your configuration files and to the SSL/TLS settings, as explained in and .
|
2. After encrypting the configuration file, follow the instructions in Setting Environment Variables for an eMessage Connector and Setting Environment Variables for an eMessage Connector.
3. After setting the environment variable, refer to Setting Up Permissions and Visibility for the eMessage Connector to set the required permissions and visibility before starting the Connector.
4. If you need to set options for the Token Authenticator used to authenticate Axeda Agents, refer to Configuring the TokenPropertyAuthenticator (eMessage Connector)
5. You are ready to start the Connector..