Securely Connecting an Application to ThingWorx Platform
All connections follow the lifecycle illustrated in the diagram below:
Connection Process
When the device starts, it establishes a connection over HTTP or HTTPS and a WebSocket upgrade occurs. The device must authenticate using an application key. Starting with v.7.0.0 of the ThingWorx Edge Java SDK, you must implement the IPasswordCallback interface to handle secure retrieval of the application key.
 | The application key is created by the ThingWorx platform. |
 | The example provided with the SDK is NOT suitable for production environments. |
Once authenticated, a device can call invokeService().
The Java SDK follows this process when connecting to the ThingWorx Platform. The three steps below describe the first three parts of the process, Connect, Authenticate, and Bind. Later sections will address the Synchronization Framework , Creating and Pushing Property Changes, and disconnecting.
In the following steps, “client” refers to the application and the SDK running on or near the device and “server” refers to the ThingWorx Platform:
1. Connect: The client opens a WebSocket to the server, using the host and port that it has been configured to use. For secure connections, always use TLS, which is negotiated at this time. While the connection is established, the duty cycle thread of the Edge Java SDK re-validates the certificate presented by the ThingWorx Platform to ensure that it has not expired.
2. Authenticate: The client sends an authentication message to the server, which contains an application key to authenticate with the server. This message is part of the ThingWorx AlwaysOn protocol. If the client attempts to send any other message before the authentication message, the server disconnects it. The platform also disconnects the client if it does not receive an authentication message within 15 seconds. You can configure this timeout in ThingWorx Composer (the WebSocket Communication Subsystem configuration). The setting is named Amount of time to wait for authentication message (secs). A ThingWorx Platform Administrator should refer to the topic, WebSocket Communications Subsystem in the ThingWorx Platform 9 Help Center for more information.
Establishing a connection and authenticating are both performed whenever a new SDK client is created and its start() method is called. Once authenticated, the client can interact with the server according to the permissions granted to the user account that is associated with its application key. At this point, the client can make requests to the server and interact with it. Note, however, that the server cannot yet direct requests to the client.
3. Bind: Binding is an optional step in the client connection process. The SDK client allows one or more Virtual Things to be associated with a WebSocket, using their names or identifiers. After associating a Virtual Thing with a WebSocket, the client sends a BIND request to the server. The server then links the associated Thing, which was created using the RemoteThing Thing Template, on the server with the WebSocket from which it received the bind request. Binding enables the server to send request messages to a client application over the associated WebSocket. The server also updates the isConnected property to true and the time value of the lastConnected property for the newly bound Thing to show the time that the binding was established.
In addition to connecting the device (client) to the Thing (isConnected property), binding maps the properties and services of the Thing to values and functions on your device. Binding also registers a Thing to participate in property change subscriptions.
A client can also send an UNBIND request. This message tells the platform to remove the association between the Thing on the platform and the WebSocket. The isConnected property of the Thing is then updated to false.
Example 1. Connecting Securely to the ThingWorx Platform
To enable your application to connect to the ThingWorx Platform, you need to create a ClientConfigurator and use it as the source of configuration for the ConnectedThingClient. The ConnectedThingClient establishes the connection to the platform. Here is a snippet from the SteamSensorClient.java example application that shows how the example creates the ConnectedThingClient and configures it in the ClientConfigurator based on the input from the command line:
public class SteamSensorClient extends ConnectedThingClient {
private static final Logger LOG = LoggerFactory.getLogger(SteamSensorClient.class);
static String hostName = "";
static int port = 8443;
static int logLevel = 2;
static String thingworxUri = "";
. . .
// After building the Uri for the ThingWorx Platform, set it for the application
ClientConfigurator config = new ClientConfigurator();
config.setUri(thingworxUri);
config.setReconnectInterval(15);
if(cmd.hasOption("n")) {
config.tunnelsEnabled(true);
}
if(cmd.hasOption("j")) {
config.setProxyHost(cmd.getOptionValue("j"));
config.setProxyPort(Integer.parseInt(cmd.getOptionValue("r")));
config.setProxyUser(cmd.getOptionValue("u"));
if(cmd.hasOption("q")) {
config.setProxyPassCallback( new SamplePasswordCallback(cmd.getOptionValue("q")) );
}
}
. . . <logging setup>
// Using the password callback for the application key
config.setSecurityClaims( new SamplePasswordCallback( cmd.getOptionValue("k") ) );
. . .
// Do not use self-signed certificates in production systems.
if(cmd.hasOption("d")) {
config.ignoreSSLErrors(true); // Allow self signed certs
int scanRate = 3000; // the processScanRequest of the VitualThing scans every 3 seconds
if(cmd.hasOption("g")) {
config.setName(cmd.getOptionValue("g"));
config.setAsSDKType();
} else {
config.setName(null);
}
. . .
SteamSensorClient client = new SteamSensorClient(config);
Following this example, a fast, continuously-connected, bidirectional data channel is established between the ThingWorx Platform and as many remote processes as you want, enabled by the ThingWorx AlwaysOn protocol.
 | It is strongly recommended that you use TLS (JSSE) with a valid server certificate for connections between your devices and the ThingWorx Platform. Use of self-signed certificates and the ignoreSSLErrors method are purely for development purposes. |