Enabling LDAP Authentication in ThingWorx

[#1]

• Guide Concept
• Step 1: Completed Example
• Step 2: Understanding Directory Services
• Step 3: Configure ThingWorx and ApacheDS
• Step 4: Import Users Into ThingWorx
• Step 5: Next Steps

Create users, security groups, and provide a method to authenticate with LDAP.

Guide Concept

LDAP allows for a layer of security within your company or organization to be utilized for authentication or user management.

These concepts and steps will allow you to focus on development of your application while still allowing the ability to utilize the power of ThingWorx!

We will teach you how to enable LDAP authentication in ThingWorx and configuring ThingWorx to connect to a LDAP server.

You'll learn how to

• How to enable LDAP Authentication on ThingWorx
• Configuring ThingWorx to connect to an LDAP server
• Importing users from LDAP

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

Step 1: Completed Example

Download the completed files for this tutorial: ApacheDSExample.xml. This guide will cover authentication with an ApacheDS LDAP server.

In this tutorial, we walk 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.

Step 2: Understanding Directory Services

ThingWorx provides built-in LDAP Directory Support for clear-text connections (port 389). In order to enable LDAP Authentication, a Directory Service Entity must be imported and configured. The sample download provided is setup for Apache DS. An Active Directory example and a OpenLDAP example are attached, but will not be covered here. Other LDAP providers will need a similar file.

Users can exist in any Directory Services location as all Directory Services will be tried in order of priority when a user logs in. For the default setting, LDAP Directory Service will have priority over the ThingWorx one once enabled. To modify this configuration on the provided example, follow the below steps (if you have not done so already, import the XML file that was provided into The ThingWorx Composer):

1. From the ThingWorx Composer, go to the SECURITY section and click Directory Service.
2. Open the Directory Service Entity you imported, ApacheDS.
3. Enable LDAP in the General Properties section by checkicking the Enabled checkbox.
   
   

4. (Optional) Set the priority for the authentication if you have multiple Directory Service entities configured:

• Use the Priority property to assign an order of authentication to log in.
• The lower the number the higher the priority (1 is the highest priority).

5. Click Save to save ApacheDS and enable LDAP authentication.

ThingWorx will contact the LDAP server to check for the given username when a user then tries to authenticate. If the user is not found or if the authentication on the LDAP server fails then the ThingWorx Directory Service will be tried.

Step 3: Configure ThingWorx and ApacheDS

This section will create an LDAP server, create the connection, and configure LDAP utilizing ApacheDS and Apache Directory Studio. In order to fully run this example, you will need to initially create this server OR deploy this server to a ThingWorx accessible location.

If you do not have an LDAP server already setup, utilize the below instructions to get started. If you already have a LDAP server setup, skip to the Configure ThingWorx For LDAP Connection section to configure the connection in ThingWorx.

Create New LDAP Server and Connection:

1. Open Apache Directory Studio.

2. Right-click in the LDAP Servers section and select New -> New Server.
   
   

   

3. Select your version of ApacheDS in the menu and click Finish.
   
   

   

4. Right-click the newly created LDAP server and select Open Configuration.
   
   

   

5. Update the Port for the LDAP server to 389 and uncheck the LDAPS server.
   
   

   

6. Click Partitions at the bottom of the configuration and click Add.
   
   

   

7. Set the new Partition ID to ThingWorx.

8. Set the Suffix value of the Partition to ou=people, dc=thingworx.
   
   

   

9. Save and close the configurations.

10. Right-click the LDAP server and select Run.

11. Once the State of the LDAP server has changed to Started, right-click the LDAP server and select Create Connection.
    
    

    

Utilize the ApacheDS adding entries guide to create users for your new LDAP server then follow the below instruction to create the ThingWorx connection.

Configure ThingWorx For LDAP Connection: The sample XML files provided are configured with the most common attribute for the platform.

1. From the ThingWorx Composer, go to the SECURITY section and click Directory Service.
2. Open the Directory Service Entity you imported, ApacheDS. Generally, only one Entity listed unless multiple authentication realms have been configured.
3. Click Congifurations to bring up Directory Service configuration details.
4. Update the configuration parameters for the LDAP server:
   
   
   • server: The hostname of the LDAP server
   • userIdAttribute: LDAP attribute that is used to uniquely identify the user logging in. This property should be set to the name of the attribute containing the user's username.
   • port: Connection port for the LDAP server. LDAP standard port is 389. If the LDAP server's connection port is 636, it is very likely that the server is expecting LDAPS, which ThingWorx does not currently support.
   • adminBindDN: The full distinguished name for the user that the ThingWorx server will use for browsing the LDAP directory tree. The user that is defined here must have Read permissions on the directory tree. Generic Format: uid=admin, ou=Users, dc=company, dc=com
   • userBaseDN: Distinguished name for the parent organizational unit (OU) containing any user that will need to log in. *Generic Format*: ou=ThingWorxUsers, ou=Users, dc=company, dc=com
   • adminPassword: The password for the user configured in adminBindDN above
     
     
     
5. Click Save to update the ApacheDS Directory Service.

Step 4: Import Users Into ThingWorx

Handling Password Configurations: User must have a corresponding ThingWorx user created on the server before a user can log into ThingWorx via LDAP. These users must be created manually before they can log into the ThingWorx server

All User entities created on ThingWorx matching LDAP users must have a password set, otherwise LDAP will not be able to log in.

• This password should NOT be the user's LDAP password
• The password used within ThingWorx should be secure/randomly generated. If LDAP authentication fails, ThingWorx will fall back on the password set for this user.
• The code provided below generates a random password for the users it creates
  
  

Custom Service for User and Password Generation: A custom service can be created on a Service-Providing Thing instance that creates a specific user and assign it a home mashup:

A Service-Providing Thing is an entity that uses the *GenericThing** ThingTemplate. It does not store properties. Instead, it provides useful Services that retrieve and compile data from many Thing instances for use in Mashups and/or other services.

To create a Service-Providing Thing:

1. Create a new Thing, and name it LDAPServiceHelper.
2. Set the Thing Template to GenericThing.
3. Click Services and create a new Service called CreateLDAPUser.
4. Set the Inputs to be the following:
   • Username (STRING, required)
   • HomeMashup (MASHUPNAME, optional)
5. Use the following for the source code:

// ThingWorx will fall back on ThingWorx Directory Service (Local authentication) 
// if LDAP authentication fails, which means the password that we have to set for 
// the new user could also be used to log the user in. 
// Using a random string will make it highly unlikely that a user / attacker can 
// use the ThingWorx password to log in.
var randompass = Math.random().toString(36).slice(-10);

var params1 = {
    name: Username, 
    password: randompass,
    description: "Generated LDAP User"
};

Resources["EntityServices"].CreateUser(params1);

// By default non-admin users will be directed to SQUEAL.  
// If there is a specific mashup that the user should see instead, 
// the following code will configure it based on the HomeMashup optional parameter.
// The mashup passed to this service must exist.

if (HomeMashup !== null) {
    var params2 = { 
        name: HomeMashup 
    };

    Users[Username].SetHomeMashup(params2); 
}

6. Click Done.

7. Click Save.

Execute the newly created Service for each user in the LDAP system. Once all users have been imported (or at least the ones who need immediate access) the Directory Service must be enabled for ThingWorx to begin authenticating users via LDAP.

Step 5: Next Steps

Congratulations! You've successfully completed the Enabling LDAP Authentication in ThingWorx tutorial, and learned how to:

• How to enable LDAP Authentication on ThingWorx
• Configuring ThingWorx to connect to an LDAP server
• Importing users from LDAP
• Auto assigning to user groups based on LDAP membership

Learn More

We recommend the following resources to continue your learning experience:

 Capability   Guide

Secure	Create An Authentication Extension
Secure	Configure Permissions

 

Additional Resources

If you have questions, issues, or need additional information, refer to:

 Resource         Link

Community	Developer Community Forum
Support	Extension Development Guide