Authenticator Sample Extension Configuration

ThingWorx Model Definition in Composer > Security > Authenticators > Login Authenticators > Authenticator Sample Extension Configuration

Use the steps below to build, create an extension manifest, and implement your authentication strategy algorithm in the authenticator extension callback methods. For additional information on creating custom extensions in ThingWorx, refer to ThingWorx Extensibility.

Building

Build tools such as Ant or Gradle can be used. In your build script, you will need to compile your Java class that implements the authenticator method callbacks (discussed later). Make sure you compile against the Thingworx-Extension-SDK-x.x.x libraries (JAR files) that are compatible with the version of the Thingworx-Platform-x.x.x, that you are using at runtime. Remember to also include the metadata.xml file that is used to register your authenticator extension with ThingWorx when your extension ZIP is imported.

Creating a Manifest

1. Open configfiles/metadata.xml.

2. In the authenticators collection element (sample shown below), configure the following parameters as necessary:

a. Authenticator name— Displayed in Composer. Must be a unique name.

b. className— Class name of the implementation used by ThingWorx to instantiate the authenticator implementation instance.

c. description— Displayed in Composer.

d. aspect.isEditableExtensionObject— Set to true to allow enabled, priority settings to be saved in Composer. This is required.

3. Configure the FileResource type jar file name (see below):

<FileResource type="JAR" file="auth-sample-basicuser-extension.jar"
description="Authenticators Sample BasicUser JAR file." /> name of jar file

4. Save and close the file.

Implementation

To implement, follow the steps below for the appropriate authenticator JAR file:

1. Derive/extend from the CustomAuthenticator class.

The SupportsSession parameter allows for session support between requests, and is set to true by default. Set it to false if you do not want to support a session between requests.

2. Implement a default constructor.

3. Override authenticator type methods as necessary for your implementation:

Method	Description
public boolean matchesAuthRequest(HttpServletRequest httpRequest) throws AuthenticatorException,	Allows you to obtain information from the incoming authentication request that is provided as the httpRequest parameter. To specify that you can handle the request, return true, otherwise false. If the return value is true, the ThingWorx run time will call the authenticate method (see below).
//… make SSO call or other algorithm to determine userName public void authenticate(HttpServletRequest httpRequest, HttpServletResponse httpResponse) { // use validateThingworxUser to make sure the user is enabled and a Thingworx user AuthenticationUtilities.validateThingworxUser(userName); // Call setCredentials, so the Thingworx platform can provide the correct permissions and access to allowed content this.setCredentials(userName); } // … or if not using SSO, but providing username and password public void authenticate(HttpServletRequest httpRequest, HttpServletResponse httpResponse) { AuthenticationUtilities.validateCredentials(user, password); this.setCredentials(user, password); }	In the case of an authentication strategy that provides user name only (for example, SSO, where user authentication is done in a separate application), use the first set of "validate" and "setCredentials", as shown in the left column. In the case of an authentication strategy that provides a user name and password, use the second set of “validate” and “setCredentials”, as shown in the left column.
public void issueAuthenticationChallenge(HttpServletRequest httpRequest, HttpServletResponse httpResponse) throws AuthenticatorException	This method is not always necessary. However, if an exception is thrown from the Authenticate method or if you set the RequiresChallenge flag to true, then the issueAuthenticationchallenge method will be called.

Default Authenticator Prioritizations

The system authenticators have the following default prioritizations. This distributed range allows for injecting authenticator extensions into the processing chain in between if desired. These system object authenticators cannot be reordered, re prioritized, deleted, or changed in any way.

• ThingworxBasicAuthenticator — Priority 100. Authenticates the provided username and password.

• ThingworxMobileTokenAuthenticator— Priority 150. Mobile App Builder Authenticator that validates against ThingWorx mobile tokens.

This authenticator is intended for a future release, and is currently disabled.

• ThingworxApplicationKeyAuthenticator — Priority 200. Authenticates the provided application key.

• ThingworxFormAuthenticator — Priority 300. Authenticates via form login.

• ThingworxMobileAuthorizationAuthenticator — Priority 350. Mobile App Builder authenticator that validates against ThingWorx user/passwords.

This authenticator is intended for a future release, and is currently disabled.

• ThingworxHttpBasicAuthenticator — Priority 400. Basic HTTP authentication.

Deploying a Custom Authenticator in Composer

1. In Composer, click Import/Export>Import.

2. Locate the <YourAuthenticatorExtensionZipName>.zip.

3. Install the extension.

4. In the Explorer, click Authenticators.

5. Open the appropriate authenticator.

6. In General Information, click Enabled.

All authenticators are disabled by default.

7. Click Save.

Authenticators at Run time

The authenticator extension can be accessed at run time. Generally, the lowest value is processed first. If there are two authenticators with the same priority value and both respond true to the matchAuthenticationRequest callback, then a non-deterministic order effect will cause a non-deterministic authenticator request handling at run time. For this reason, it is suggested that no two custom authenticators have the same priority values to guarantee a known request handling order. If an authenticator fails to handle a request, then the next authenticator in the chain will be given a chance to handle the request and so on until a valid authentication occurs. If no custom authenticators can handle the request, the ThingWorx system authenticators will process the request and likely display a form login for the user name and password.

Accessing Authenticators at Run time

To access authenticators at run time, make a request to the following URL, and provide the query, header parameters, or message body that the custom authenticator can retrieve and process from the forwarded httpRequest object during the three custom authenticator callback methods discussed earlier.

• Server:Port/Thingworx/Home

• <host:port>/Thingworx/Home?YourParameter=something