I've been working with the 7.x and 8.x versions of Thingworx over the last several months doing integrations. So I have a few development instances I've been working with. I'd like to go over some of the issues I've encountered and provide some potential best practices around how you work with Thingworx in development mode and transition to production.

 

Typically, I'll create an instance and develop the integration using the Administrator user which is the only user created as you start up Thingworx instances. Lately, I've been having trouble with a lot of authentication failures as I build.

 

Problem number 1: The new User Lockout feature.

Around 7.2 a new User Lockout feature was added to Thingworx to help prevent brute-force cracking of passwords. You now are allowed only so many authentication failures in a given period of time before the user is automatically put in lock mode for a number of minutes. Unfortunately, (but realistically in a more secure manner), a lockout appears as more authentication failures. In reality, it is because the user you have just successfully authenticated to has been automatically locked. I came very close to wiping out an entire instance because I just couldn't get signed in. Then I remembered the lockout, so I worked on something else for a while and then tried to get back into the server and I was successful because the lock timeout had expired. To see the settings in your system, look at the User Management Subsystem configuration page. The Account Lockout Settings default to 5 failures in a 5 minute period that will result in a 15 minute lockout. One note is that setting the lockout to 0 doesn't disable it, it permanently locks out the account. It will have to be reset by a member of the administrators group. The screenshot below shows

 

UserManagementLockoutSettings.jpg

 

Problem number 2: AppKeys

There is a new setting in the PlatformSubsystem that by default prevents the use of AppKeys in a URL. This setting is present because it is more secure. If you use an appKey as a query parameter in a URL, the appKey will be logged as clear text in your web browser's access log. This is a security risk - an AppKey, especially one not using a whitelist setting might make it possible for someone to gain access to your system by managing to see the access log for your system (maybe via some log analysis tool you feed your logs to). You can disable this setting, but it is not recommended for production - you may have to for a while because you may have code that uses this technique that must be updated before you can enforce the policy. You should deal with this in your production systems as soon as practical. See the graphic below on where this setting shows up.

 

Problem number 3: REST API testing

As a Thingworx developer, you're probably aware of tools like Curl, Postman and even the Web Browser that can let you exercise a REST API as you develop your code so you can validate your functionality. The REST guidelines specify that you should use the GET method to retrieve data, PUT to create data, POST to update data, etc. The issue is that it is easiest to test an API call if you can execute it from a web browser. However, the web browser always uses the GET method to make a request. This means that PUT and POST (along with other methods) will not work from your browser. Thingworx originally interpreted the incoming request and would internally reroute incoming requests to the POST or PUT functionality. This is also insecure because it makes it too easy to execute services from a browser. A setting was added to the PlatformSubsystem allow for a gradual transition to the more secure configuration. Turn this on in developer mode to simplify your testing of REST calls, but you should not leave it on in production mode as it provides a potential attack vector for your server.

 

PlatformSubsystemInsecureSettings.jpg

 

So I have some recommendations:

 

1) Set up an additional Administrative user upon installation

If you only have one user defined and it gets locked out, you're stuck until the lockout times out. Worse, if for some reason you set the timeout value to 0, you're locked out forever by Thingworx. You're only choice will be to hack the database to unlock the user or to wipe out the instance and start over. I just went through a situation where I did create the second user and forgot to add it to the Administrators group. So I did something else for 20 minutes to make sure the lockout had cleared. Then I added the user to the Administrators group but got distracted and never pressed the Save button so it locked up again. Make sure you have the user created and functional immediately upon installing the instance - don't wait until you're getting locked out by some loop that's not authenticating properly. Even if you were logged in as your Administrator user, the lockout will cause a failure the next time you try to do something in Composer, like turn off the lockout checkbox!

 

2) Test your REST Calls with Curl or Postman - not the web browser

Don't test your code in a loop until you've tested it in isolation to be sure it's not going to fail authentication for some reason (which may include violating the PlatformSubsystem settings above). Don't use the browser to do the testing - it will require disabling the secure settings. Use Curl or even better, Postman or a similar tool to test your REST calls - it will give you better formatted output than Curl. And you can easily put appKey in as a header (where it should be) instead of a parameter on the URL or in the body.

 

3) Tighten up your appKeys where possible.

Since an appKey is effectively a user/password replacement, you should protect them in the same manner - keep them out of log files by not allowing them as URL parameters, and use the whitelist to keep them from being used for other purposes. If you have a server to server connection, whitelist the server who will be making the calls to you. What I'm not sure of is just whether this is really IP addresses only or if you can use a DNS name and it will look up the IP address and insure it is in fact coming from the expected source. Someone else might be able to comment on this.

 

4) Test with the PlatformSubsystem settings off

Make sure you can run your server without the method redirect or appKey as parameter settings in the PlatformSubsystem. Those settings are potential security vulnerabilities. You may find some Thingworx code that requires one or the other of those settings. Please be sure to report this through PTC Tech Support so it can be fixed.