Create An Authentication Extension Part 1

[#1]

• GUIDE CONCEPT
• Step 1: Completed Example
• Step 2: Understanding Authenticators
• Step 3: Download Plugin and SDK

Build authentications extensions quickly and add to the security of your application.

GUIDE CONCEPT

Extensions enable you to quickly and easily add new functionality to an IoT solution. Extensions can be service (function/method) libraries, connector templates, functional widgets, and more.

These pointers and steps will enable you to maintain focus on development of your own application and still utilize the power of ThingWorx for other purposes at the same time.

When to Utilize:

• You have your own login from outside of ThingWorx but you want to leverage ThingWorx user management
• You are using an identity provider other than ThingWorx
• You need to support passing of credentials in headers/query string parameters which ThingWorx doesn’t support out-of-the-box

Concept

Whether you would like ThingWorx to handle the security for your application, have an application you want ThingWorx to pump data into, or would just like to utilize ThingWorx features in your own application, external authentication can be a great way to integrate your application with ThingWorx. This guide will focus in on how to create an authentication middle man between a system you have already developed (or are in the middle of creating) and connect it to the ThingWorx Platform. In a provided demo website, you will login (with the provided credentials) and validate your user profile and password with ThingWorx. This setup shows the simple integration between ThingWorx and an application you would like to connect to the ThingWorx Platform.

YOU'LL LEARN HOW TO

• Install the Eclipse plugin and extension SDK
• Create authentication application
• Build and import an extension

NOTE: This guide's content aligns with ThingWorx 9.3. The estimated time to complete ALL parts of this guide is 60 minutes. 

Step 1: Completed Example

Download the completed files for this tutorial: AuthenticationExtension.zip

This tutorial will guide you through security concepts within ThingWorx. Utilize this file to see a finished example and return to it as a reference if you become stuck creating your own fully flushed out application.

Keep in mind, this download uses the exact names for entities used in this tutorial. If you would like to import this example and also create entities on your own, change the names of the entities you create.

The download contains three directories (Source, CompletedExtension, and Demo). See below for the information about each directory.

Directory	Description
Source	The completed project and source code to be utilized as a comparison or ready to go pre-built extension.
CompletedExtension	A completed and built extension that is based on the steps utilized in the latter steps. The zip file in this directory can be imported directly.
Demo	A demo web page that shows easy integration of an external application and ThingWorx authentication.

Step 2: Understanding Authenticators

Authentication between ThingWorx and custom outside applications begins with Authenticators.  Authenticators are the component integration point that allows for custom authentication schemes to be added into the ThingWorx platform. Authenticators can be used to retrieve content, parameters, headers, etc from HTTP requests.

The retrieved data can be verified by the authenticator using its implemented/configured verification  algorithm(s). If that data is of a username/password credential type the authenticator can choose to pass validation of that data to the configured list of Directory Services. For example, the internal ThingWorx username/password store, or delegate to an external Active Directory set of username/passwords.

ThingWorx tries to authenticate in increasing order of priority. In example, starting with  ThingworxBasicAuthenticator, unless a custom authenticator is given higher priority than that, ThingWorx will continue trying enabled authenticators by priority until one succeeds.

If an authenticator has priority 1, it will be consulted first in the chain of authenticators. If the authenticator has a priority of 101, it will be consulted after the ThingworxBasicAuthenticator (with priority of 100) fails to authenticate the HTTP request. There are several built-in authenticators

Authenticator	Priority	Editable
ThingworxBasicAuthenticator	100	No
ThingworxMobileTokenAuthenticator	150	Yes
ThingworxApplicationKeyAuthenticator	200	No
ThingworxSSOAuthenticator	250	Yes
ThingworxFormAuthenticator	300	No
ThingworxMobileAuthorizationAuthenticator	350	Yes
ThingworxHttpBasicAuthenticator	400	No

When all configured and enabled authenticators fail to validate the data provided by an HTTP request, an authentication failure response is sent back to the requesting client. Custom Authenticators can be given priority such that they fit into any part of this process.

For setting the priority follow the instructions below:

1. Navigate to and select Security > Authenticators.

   
   
   

2. Select the Authenticator you would like to edit (ie, ThingworxSSOAuthenticator). If you do not see a specific Authenticator you would like to VIEW ONLY, check the Show System Objects checkbox in your search filter.

   

3. Update the Priority field with a new value.

4. Click Save.

   

 

Step 3: Download Plugin and SDK

The ThingWorx Extension SDK provides supported classes and APIs to build Java-based extensions. The APIs included in this SDK allow manipulation of ThingWorx platform objects to create Java based extensions that can extend the capability of the existing ThingWorx platform.

The Eclipse Plugin assists in working with the Extension SDK to create projects, entities, and samples.

1. Download the Eclipse Plugin.

2. Download Extensions SDK.

3. Make a note of the directory where the plugin and the extension SDK are stored. The path of the directory will be required in upcoming steps. Do not extract the zip files.

Click here to view Part 2 of this guide.