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:
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:
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:
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. |