Security > Authenticators > Login Authenticators > Authenticator Sample Extension Configuration
  
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’ll 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:
<Entities>
<ExtensionPackages>
<ExtensionPackage name="Authenticators_Sample_BasicUser_ExtensionPackage"
description="Authenticators Sample BasicUser Extension Package"
vendor="ThingWorx"
packageVersion="1.0"
minimumThingWorxVersion="5.1.1">
<JarResources>
<FileResource type="JAR" file="auth-sample-basicuser-extension.jar" description="Authenticators Sample BasicUser JAR file." />
</JarResources>
</ExtensionPackage>
</ExtensionPackages>
<Authenticators>
<Authenticator name="SampleBasicUserAuthenticator"
className="com.thingworx.security.authentication.samples.SampleBasicUserAuthenticator"
description="Sample Authenticator that validates against the Thingworx User"
aspect.isEditableExtensionObject="true">
</Authenticator>
</Authenticators>
</Entities>
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 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 runtime will call the authenticate method (see below).
public void authenticate(HttpServletRequest httpRequest, HttpServletResponse httpResponse)

{

//… make SSO call or other algorithm to determine userName



// use validateEnabledThingworxUser to make sure the user is enabled and a Thingworx user

AuthenticationUtilities.validateEnabledThingworxUser(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



AuthenticationUtilities.validateCredentials(user, password);

this.setCredentials(user, password);
In the case of SSO, you need to forward the authentication request information to your SSO authentication server (handles the login). This server must provide ThingWorx with the user name that the Authenticator extension will validate and set user name credential into ThingWorx.
In the case of an authentication strategy other than SSO that provides both a username and password, use the second set of “validate” and “setCredentials” as shown to the left.
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 re-ordered, 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 Runtime
The Authenticator extension can be accessed at runtime. 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 non-deterministic authenticator request handling at runtime. 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 username and password.
Accessing Authenticators at Runtime
To access at runtime, make a request to the following URL, and provide the query or 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
Related Links
Authenticators
Mobile Authenticators