Managing Users in Active Directory

ThingWorx Model Definition in Composer > Security > Directory Services > Managing Users in Active Directory

You can manage users and user groups in ThingWorx if the users already exist in Microsoft Active Directory (AD) directory service. ThingWorx allows Active Directory user groups to be mapped to ThingWorx user groups. User provisioning options allow users to be created, modified, or deleted. Permissions are managed in ThingWorx for each user group.

Active Directory functionality is not enabled by default in ThingWorx. A ThingWorx administrator user must enable Active Directory before it can be used to authenticate in ThingWorx.

To help you get started, configure ThingWorx to use Active Directory, set up the connection, and test the connectivity, refer to the following sections in this topic:

1. Getting Started

2. Configuration for Directory Services

3. Connection Settings

4. Testing Active Directory Connectivity

Getting Started

To get started, create a directory service in ThingWorx by importing an XML file with entities into ThingWorx. After the file is imported, you can configure the directory service in ThingWorx. Follow these rules when working with the XML file:

• The XML file must contain one or more directory services that use the com.thingworx.security.directoryservices.ActiveDirectoryDirectoryService Java class as the className attribute of a DirectoryService element.

• For each DirectoryService element, a unique value for the name must be provided.

• The name value must also be unique among all directory services that exist within ThingWorx run time.

• The priority attribute should have a unique priority order number for authentication. Additionally, a unique priority order should be added to each directory service in the file as well as in the ThingWorx run time. This priority order corresponds to the order in which ThingWorx should consult the directory service when validating credentials.

Directory services work in a linked priority order for authentication. If a directory service with the lowest priority setting of 1 fails to validate a user authentication, the chain attempts to validate the user against the directory service in the chain with the next highest priority.

For usage of these rules, refer to the following examples:

• XML Example: Single Directory Service

• XML Example: Two Directory Services

When ready, import the XML file for your Active Directory server into ThingWorx. For issues with the import, refer to one of the following troubleshooting sections:

• Entity Import Failed with Unable to Convert Error if the import of an entity fails with an Unable to convert message written to the Application Log

• Import Validation Fails But Import Succeeds if the import validation fails due to a missing required field or invalid configuration, but the entity is imported and disabled

Configuration for Directory Services

After you have imported an XML file for an Active Directory directory service, you must configure it. To access the configuration page in ThingWorx Composer:

1. In the Browse navigation panel, expand Security, and select Directory Services.

2. On the directory services page, click the name of the Active Directory directory service. The General Information page for the directory service appears.

3. Select the Enabled check box to enable this directory service, and click Save.

4. Select Configuration to display the configuration page. You are ready to configure the directory service.

The configuration options described in this section and the sections that follow are all displayed on the configuration page for the directory service entity. For assistance with configuration error messages, refer to Configuration Error Messages.

Validation of credentials for user inputs during a login to ThingWorx is performed by looking up the user object and password on that object in the User Base Distinguished Name configuration table setting. There are two places to specify a domain on an Active Directory entity, and they can be completely independent of each other. The Domain Distinguished Name is used during a group lookup, so if you are using the group mapping functionality, verify that all of the groups in which users reside fall under the Domain Distinguished Name value specified. The User Base Distinguished Name is the location used during a lookup of a user object in Active Directory, with the user name and the password given during a login to ThingWorx.

When configuring multiple directory services objects, do not overlap user search bases within your Active Directory structure.

Connection Settings

The connection settings of the Active Directory configuration include the option, Dynamic User Login. Here is the page:

The following table describes the Connection Settings for a directory service. All connection settings fields are required.

Name	Description	XML Attribute Name	Default Value	Example of Value
URI Scheme	A string that specifies the associated protocol used in communications to the Active Directory server.	protocol	LDAP	LDAP
Server FQDN or IP Address	Server name/address being targeted for directory queries.	server	localhost	localhost, domainserver.acme.com, 127.0.0.1
Server Network Port	The port of the server being targeted for directory queries.	port	389	389, 369, 10389
Domain Distinguished Name	The distinguished name of the top-level directory used during a user group lookup.	domain	n/a	DC=test, DC=acme, DC=com
Dynamic User Login	Determines whether the Dynamic User Login is enabled. See the next section for details.	dynamicUserLogin	The check box is empty (disabled).	The check box is selected.
Administrative Principal Name	The name of the user that has administrative read access to the domain object specified. The value of this name depends on the User Id Attribute specified in the Schema Mappings configuration table.	adminPrincipal	n/a	AcmeAdmin
Administrative Password	The password for the administrative principal name specified in the connection settings configuration table.	adminPassword	n/a	AcmePassword

Testing Active Directory Connectivity

In the Connection Settings section of the directory service configuration page, the Verify button under Test Connection allows you to test the connection to the Active Directory server, based on the current configuration. The following fields from the Connection Settings section of the configuration are used to test the Active Directory connection:

• URI Scheme

• Server FQDN or IP Address

• Server Network Port

• Administrative Principal Name

• Administrative Password

The Verify button starts the TestConnection service, which takes the following parameters:

Parameters for the TestConnection Service
Parameter	Base Type	Description
userName	STRING	The name of the user in Active Directory.
password	STRING	The encrypted password of the Active Directory user.
protocol	STRING	The schema used (either LDAP or LDAPS).
server	STRING	The host or IP address of the Active Directory instance.
port	INTEGER	The port of the Active Directory instance.

The results of the connection test are returned in result, which is an INFOTABLE, with the following information:

• status: (Boolean) Indicates if there is a successful connection to Active Directory.

• message: (String) Message that provides any useful information as to why the test failed.

If Dynamic User Login is enabled, then the "Administrative Principal Name" and "Administrative Password" are not used and the Verify button is hidden.