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.
|
This topic provides the following information:
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 fails (1 in the example below) to validate a user authentication, then the chain attempts to validate the user against the directory service in the chain with the next highest priority. See the examples below.
|
XML Example: Single Directory Service
In the example below, the minimal configuration xml file required to import a new directory service within ThingWorx is included.
|
|
The examples below are for an administrator user.
|
<Entities>
<DirectoryServices>
<DirectoryService
className="com.thingworx.security.directoryservices.ActiveDirectoryDirectoryService"
description="Active Directory Directory Services"
documentationContent="" enabled="false" homeMashup=""
lastModifiedDate="" name="ADDS1" priority="1" projectName=""
tags="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables/>
<ConfigurationChanges />
</DirectoryService>
</DirectoryServices>
</Entities>
XML Example: Two Directory Services
In the example below, there are two directory services. The priority attribute is defined in each DirectoryService.
<Entities>
<DirectoryServices>
<DirectoryService
className="com.thingworx.security.directoryservices.ActiveDirectoryDirectoryService"
description="Active Directory Directory Services"
documentationContent="" enabled="false" homeMashup=""
lastModifiedDate="" name="ADDS1" priority="1" projectName=""
tags="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables/>
<ConfigurationChanges />
</DirectoryService>
<DirectoryService
className="com.thingworx.security.directoryservices.ActiveDirectoryDirectoryService"
description="Active Directory Directory Services"
documentationContent="" enabled="false" homeMashup=""
lastModifiedDate="" name="ADDS2" priority="2" projectName=""
tags="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables/>
<ConfigurationChanges />
</DirectoryService>
</DirectoryServices>
</Entities>
<DirectoryServices>
<DirectoryService
className="com.thingworx.security.directoryservices.ActiveDirectoryDirectoryService"
description="Active Directory Directory Services"
documentationContent="" enabled="false" homeMashup=""
lastModifiedDate="" name="ADDS1" priority="1" projectName=""
tags="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables/>
<ConfigurationChanges />
</DirectoryService>
<DirectoryService
className="com.thingworx.security.directoryservices.ActiveDirectoryDirectoryService"
description="Active Directory Directory Services"
documentationContent="" enabled="false" homeMashup=""
lastModifiedDate="" name="ADDS2" priority="2" projectName=""
tags="">
<Owner name="Administrator" type="User" />
<avatar />
<DesignTimePermissions>
<Create />
<Read />
<Update />
<Delete />
<Metadata />
</DesignTimePermissions>
<RunTimePermissions />
<VisibilityPermissions>
<Visibility />
</VisibilityPermissions>
<ConfigurationTables/>
<ConfigurationChanges />
</DirectoryService>
</DirectoryServices>
</Entities>
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, see 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 username 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
As of v.8.3.5, The connection settings section of the Active Directory configuration includes the option, Dynamic User Login. Here is the revised 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 |
Dynamic User Login
| | It is recommended that users authenticate with the ThingWorx Platform using the same username when Dynamic User Login is enabled. Otherwise, due to a current limitation of the ThingWorx platform, multiple ThingWorx Platform accounts are created for the same user. For example, suppose a user logs in using their displayName, testuser. A user account is created on the platform named testuser. However, if the same user logs in using their Universal Principal Name (UPN), in this example, testuser@domain.com, then the user testuser@domain.com is also created on the platform. |
If Dynamic User Login is enabled, then the Connection Settings for Administrative Principal Name and Administrative Principal Password are ignored. The user who is logging into the ThingWorx Platform directory is authenticated in Active Directory using their user name and password. The currently supported method of authentication in Active Directory is to use the displayName, UPN, and domain\samAccountName.
If Dynamic User Login is disabled, the workflow for user login remains the same as it is in ThingWorx Platform 8.3.0 through 8.3.4.
Group Mappings
Make sure that you understand ThingWorx visibility, permission, and organization rules for users and groups to configure mappings as intended. If permissions are not assigned correctly, users may access the content that they should not be able to access.
While group mappings are not required, having no group mappings results in limited permissions (only the default permissions the user has) if a user is provisioned or updated.
The Group Mappings configuration is located about mid-way down the configuration page for an Active Directory directory service. To set up group mappings:
1. In ThingWorx Composer navigate to the Active Directory directory service in Composer ( > > .
2. Open the configuration page, scroll down to the Group Mappings section, and click Add, as indicated in the following figure:
3. In the Active Directory Group Name field of the Group Mappings window, type the name of an Active Directory Group that you want to map to a ThingWorx Group.
4. In the ThingWorx Group Name field, click the + sign to display the drop-down list of ThingWorx Groups, shown below. Note that it provides an Advanced Search, where you can filter by specific entities and more. This drop-down list is available as of v.8.3.5 of ThingWorx.
| | The following GroupMappings form is displayed when Dynamic User Login is disabled.  |
5. In the following version of the GroupMappings form, note that the message, "Credentials Required", is displayed when Dynamic Group Login is enabled. To enter an Active Directory Group Name, click the green lock icon.
6. When the Provide Credentials dialog appears, set the AdministrativePrincipalName and AdministrativePassword, and click Set.
The following table describes the settings for group mappings:
Name | Description | Valid Values |
|---|---|---|
Active Directory Group Name | The name of the Active Directory group associated/mapped to the ThingWorx group for permissions/authorization verification at run time. | A non-empty, non-blank string that contains a group name that corresponds to a groupObjectClass object in the Active Directory under the configured domain. |
ThingWorx Group Name | The name of the ThingWorx group that will contain the ThingWorx permissions/authorization configurations used at run time. Users provisioned by the Active Directory will be added to this ThingWorx group. This is based on the Active Directory group the user belongs to that is mapped to this ThingWorx group. | A non-empty, non-blank string that contains a Group Name that corresponds to a Group Entity in the ThingWorx. |
Group Mapping with Dynamic User Login
With the addition of Dynamic User Login in v.8.3.5, the GetDomainGroups and IsValidGroup services take arguments that allow Active Directory administrative user credentials to be passed in, such as from the UI, when the Dynamic User Login feature is enabled. When Dynamic User Login is disabled (as by default), the administrative user credentials are optional for the IsValidGroup and GetDomainGroups services. The TestConnection service works with all the required credentials. Any time that the parameters are empty, the services use the administrator credentials.
Group Validation for Group Mapping
As of v.8.3.5, ThingWorx Composer provides a text box on the Group Mappings page in which you can enter the name of an Active Directory group. The option to select an Active Directory group from a drop-down list is still available. The text box supports entering a group either by name or by full distinguished name. For example, the name TestGroup is a simple name, while CN=TestGroup, CN=Users, DC=domain, DC=com is a full distinguished name.
The IsValidGroup service is also provided as of v.8.3.5, to allow you to search for the name of a valid group in Active Directory. This service takes the a single, STRING parameter, groupName, which specifies the name of the group you want to find. The service returns a BOOLEAN result that indicates if the group exists in Active Directory.
| | The wild-card character ("*") is NOT allowed as part of the input for groupName. |
Nested Group Membership
As of v.8.3.5, the Add users to mapped ancestor groups configuration option is available in the Schema Mapping section of the Active Directory configuration. This BOOLEAN setting enables or disables nested group membership.
If nested group membership is enabled, then the following occurs:
• Active Directory is queried using an Extensible Match rule to retrieve both the groups that the user belongs to, and also the groups that those groups belong to, to any depth of nesting.
• These groups are compared against the Group Mapping table to assign the resulting ThingWorx user to user groups.
• This option may cause a performance impact, as it increases the load on Active Directory and may result in a large set of results.
If nested group membership is disabled, then the workflow remains the same as it exists in ThingWorx Platform v.8.3.0 through 8.3.4.
Schema Mappings
For authentication and group retrieval/mapping to work, the following fields in this section are required: User ID Attribute Name, Group Object Class Name, Group Membership Attribute Name, Group Attribute Name, User Flags Attribute Name, User Control Attribute's Disabled Bit, and User Control Attribute's Lockout Bit.
Name | Description | XML Attribute Name | Default Value | Example of Value | ||
|---|---|---|---|---|---|---|
User ID Attribute Name | The name of the attribute that contains the user name value that is used to match against the specified username when logging into ThingWorx. | attributeUserIdName | cn | cn, userPrincipleName | ||
User Base Distinguished Name | The distinguished name of the top level directory used during user credential validation. | userBaseDN | ou=people | DC=test, DC=acme, DC=com | ||
Group Object Class Name | The value of the objectClass attribute that denotes that the object is a group. The group objects will be queried for and presented for Active Directory / ThingWorx Group mapping in the Group Mappings configuration table. | groupObjectClass | group | group | ||
Group LDAP Filter to Filter Domain Groups | Allows for filtering a large number of domain groups.
| groupLdapFilter | n/a | (cn=a_testgroup111*)(cn=b_testgroup222*) | ||
Group Membership Attribute Name | The name of the attribute that denotes that a user or group is a "Member Of" another group. For each memberOf entry within a user in Active Directory, that user is added as a member to the ThingWorx group that is mapped to the Active Directory group named in the memberOf entry. | memberOfAttribute | memberOf | memberOf | ||
Group Attribute Name | The name of the attribute that should be used to retrieve the group display name in ThingWorx UI, specifically in the Group Mappings configuration table selections.
| groupAttribute | cn | cn | ||
User Flags Attribute Name | For more information, reference https://msdn.microsoft.com/en-us/library/cc223145.aspx | userControlAttribute | userAccountControl | userAccountControl | ||
User Control Attribute's Disabled Bit | The integer/decimal value of the disabled bit flag within the specified user flags attribute name (i.e. default userControlAttribute). For more information, go to https://msdn.microsoft.com/en-us/library/cc223145.aspx | userDisableBit | 2 | 2 | ||
User Control Attribute's Lockout Bit | The integer/decimal value of the lockout bit flag within the specified user flags attribute name (i.e. default userControlAttribute). For more information, go to https://msdn.microsoft.com/en-us/library/cc223145.aspx | userLockoutBit | 16 | 16 | ||
Forest Name Identifier | Identifies a collection/forest of domain controllers. Each directory service object configured with the same string will be able to map groups from each others domains within their Group Mapping configuration. See the next sections for the examples of using this option. | forestNameIdentifier | n/a |
User Provisioning
User provisioning provides options to automatically create, modify, and delete users in ThingWorx.
Name | Description | XML Attribute Name | Default Value | Notes |
|---|---|---|---|---|
User Creation Enabled | Controls the auto creation/provisioning of ThingWorx users if the user credentials are correct in the Active Directory server that facilitates the login request. If the field is checked, users are created with the login username specified, as well as with any default values specified in the User Default Settings configuration table. If the field is unchecked/false (default), users must exist in ThingWorx before a user tries to login. Users must exist in ThingWorx for logins to succeed. If the user belongs to the User Provisioning Exclusion List configuration table, this field has no effect on the automatic creation of the user. | userCreationEnabled | false | Set to true if you want the directory service in ThingWorx to have the ability to auto create users. |
User Modification Enabled | Controls the auto update/provisioning of ThingWorx users if the user credentials are correct in the Active Directory server that facilitates the login request. If the field is checked/true, users are updated upon each login attempt. They are updated with any default values specified in the User Default Settings configuration table. If the field is unchecked/false (default), users are not updated upon each login attempt after the initial attempt when the user was auto-created/provisioned. Users must exist in ThingWorx for logins to succeed. If the user belongs to the User Provisioning Exclusion List configuration table, this field has no effect on auto updating the user. | userModificationEnabled | false | Set to true to allow the directory service in ThingWorx to update users. |
User Deletion Enabled | Controls the auto deletion/un-provisioning of ThingWorx users if the user does not exist in the Active Directory server that facilitates the login request. If the field is checked/true, users are deleted upon a login attempt. If the field is unchecked/false, users are not deleted upon a login attempted. Users must exist in ThingWorx for logins to succeed and for deletion to be successful. If the user belongs to the User Provisioning Exclusion List configuration table, this field has no effect on the automatic deletion of the user. | userDeletionEnabled | false | Set to true to allow the directory service in ThingWorx to delete users. |
User Default Settings
The following table describes the available default settings for users. These fields are optional.
Name | Description | XML Attribute Name | Valid Values | Notes | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
Provisioned User's Default Domain Prefix | A string value that is assumed to be the prefix for user names to differentiate user X from domain server Y vs. user X from domain server Z. This allows the configured Active Directory directory services to explicitly know if the user to be validated is targeted to manage. If configured with a value, the Active Directory directory service does not attempt to validate or provision the user, instead it logs security messages and passes the user login attempt to the next ThingWorx directory service in the chain.
| userDefaultDomainPrefix | Empty string or any string that contains valid entity name characters | If there is more than one configured domain server, this configuration should be used. For example, NA or EUR could be used as a domain prefix.
| ||||||
Provisioned User's Default Description | A description string value that is set as the description for all provisioned users. This is a helpful setting that allows adding contextual information to a user, such as "Auto Provisioned by Domain Server Y". | userDefaultDescription | Empty string or any description string | This option should be used if a default description for all provisioned users (i.e. auto-created/updated users) is preferred. | ||||||
Provisioned User's Default Home Mashup | A home mashup name value that is set as the default mashup for all provisioned users. This setting allows all provisioned users to start at a common home mashup when they login to ThingWorx. Some examples of these mashups include a guest home mashup, self-service home mashup, or operators' home mashup, etc. | userDefaultHomeMashupName | Empty string to unset, or a valid existing mashup name | This option should be used if a default home mashup for all provisioned users (i.e. auto-created/updated users) is preferred. For example, this would be useful if the same GuestMashup, SelfServiceMashup, or LandingPageMashup is preferred for all users to start with when they enter the ThingWorx application. | ||||||
Provisioned User's Default Mobile Mashup | A mobile mashup name value that is set for all provisioned users to be used on mobile devices. This setting allows all provisioned users to start at a common mobile mashup when they login to ThingWorx. Some examples of these mashups include a guest mobile mashup, Self Service mobile mashup, or operators' mobile mashup, etc. | userDefaultMobileMashupName | Empty string to unset, or a valid existing mashup name | Use this option if a default mobile mashup for all provisioned users (i.e. auto-created/updated users) is preferred. For example, this would be useful if the same GuestMashup, SelfServiceMashup, or LandingPageMashup is preferred for all users to start with when they enter the ThingWorx application. | ||||||
Provisioned User's Default Tags | A set of model tags that are set on all provisioned users. This setting allows all provisioned users to have common tags that can be used for searching or contextual identification. Some examples of these tags include Operator tag, ProvisionedByDomainServerY, ProvisionedByDomainServerZ, etc. | userDefaultTags | Empty string to unset, or a valid existing tag names | This option should be used if a default set of model tags for all provisioned users (that is, auto-created/updated users) is preferred. |
User Provisioning Exclusion List
This is a configuration table that allows the administrator of the Active Directory directory service to exclude specific ThingWorx users from participating in the user provisioning features of the Active Directory directory service.
The user provisioning features include user creation, modification, and deletion. When configuring ThingWorx with an Active Directory directory service, existing users may not wish their configuration and existence to be managed by Active Directory; and only use it for the credential validation. These types of users should be added to the User Provisioning Exclusion list configuration.
| | The administrator user is automatically added to this list, and should not be removed. |
The administrator user is a ThingWorx default user that cannot be created or destroyed. The administrator user should not be automatically modified. Doing so could cause undesired configuration changes at login.
User Login Scenarios
The following table provides the pre and post user states during login attempts to ThingWorx per the configuration options set in the Active Directory directory service within ThingWorx.
| | The scenarios below do not change the user state/configuration within the Active Directory server. The items in bold are the main decision maker in the post-state of the user in ThingWorx. |
User State in AD Server | User Pre-State in ThingWorx | Configuration Option(s) | User Post-State in ThingWorx |
|---|---|---|---|
Does not exist | Does not exist | Any configuration | • Does not exist • Cannot be used to log in |
Does not exist | • Exists (manually created by ThingWorx administrator) • Password was set/resides in ThingWorx | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Listed in User Provisioning Exclusion List | • Exists • Is not modified or deleted • Can be used to log in |
Does not exist | • Exists (manually created by ThingWorx administrator) • Password was not set or does not reside in ThingWorx | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Listed in User Provisioning Exclusion List | • Exists • Is not modified or deleted • Cannot be used to log in |
Does not exist | Exists (manually created by ThingWorx administrator) | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Not listed in User Provisioning Exclusion List | • Does not exist • Cannot be used to log in |
Does not exist | • Exists (manually created by ThingWorx administrator) | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Disabled • Not listed in User Provisioning Exclusion List | • Does not exist • Cannot be used to log in |
Exists | Does not exist | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Listed in User Provisioning Exclusion List | • Does not exist • Cannot be used to log in |
• Exists • Disabled | Does not exist | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Not listed in User Provisioning Exclusion List | • Does not exist • Cannot be used to log in |
• Exists • Locked | Does not exist | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Not listed in User Provisioning Exclusion List | • Does not exist • Cannot be used to log in |
Exists | Does not exist | • User Provisioning Creation Disabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Not listed in User Provisioning Exclusion List | • Does not exist • Cannot be used to log in |
Exists | Does not exist | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Not listed in User Provisioning Exclusion List | • Exists (created) • Added as a member to mapped groups • Default user settings added • Can be used to log in |
Exists | Exists | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Not listed in User Provisioning Exclusion List • User default settings configured | • User is modified • Added/removed as a member to mapped groups • Default users settings added • Can be used to log in |
Exists | Exists | • User Provisioning Creation Enabled • User Provisioning Modification Enabled • User Provisioning Deletion Enabled • Listed in User Provisioning Exclusion List • User default settings configured | • User is not modified • Can be used to log in |
• Exists • Locked | Exists | Any configuration | • User is locked • Cannot be used to log in |
• Exists • Disabled | Exists | Any configuration | • User is disabled • Cannot be used to log in |
User Lockout Scenarios
Account lockout settings are configured in ThingWorx in the User Management Subsystem.
The Lockout Manager is defined as the system (ThingWorx or Active Directory) that determines the lockout based on the lock evaluation.
The key for the table below is:
• ThingWorx Lockout Attempts configuration: TLA
• Active Directory Lockout Attempts configuration: ADL
Lock Evaluation | Lockout Manager | Lockout Manager Max Attempts Configuration Example | Action | Result | ||
|---|---|---|---|---|---|---|
TLA > ADL | ADL | 2 attempts | ThingWorx finds a user locked in Active Directory | ThingWorx user is locked immediately | ||
TLA > ADL | ADL | 2 attempts | User logs in incorrectly two times | ThingWorx user is locked after two attempts | ||
TLA = ADL
| ADL | 2 attempts | User logs in incorrectly two times | ThingWorx user is locked after two attempts | ||
TLA < ADL | ADL | 2 attempts | User logs in incorrectly two times | ThingWorx user is locked after two attempts |
Active Directory or ThingWorx Directory Service Changes
If a user is deleted or updated in the domain server, a group mapping is updated in the associated ThingWorx Active Directory directory service. If the user default settings change, then it is recommended to use the TerminateUserSessions service in the CurrentSessionInfo resource for that user in ThingWorx.
| | If either of the configuration changes listed below are made, and there is a user who was created from the previous configuration, the Active Directory directory service cannot migrate the past user to the new user. Instead, a new user is created and managed, based on the new or different values set with the attribute specified in the User ID Attribute Name and/or domain. • The value of the User ID Attribute Name in the Schema Mappings configuration is a user name. • The Domain prefix is changed. |
Mapping User Attributes from Active Directory to the ThingWorx UserExtension Property
When a new Active Directory user logs in, that user is created in ThingWorx and that user may be auto-provisioned, depending on the settings in Active Directory for Create User. The options described in the table below allow for mapped attributes to be automatically mapped from the Active Directory server to the UserExtension property table for that user in ThingWorx. When an existing Active Directory user logs in, any modified values are pulled into the user's UserExtension mapping. If a new UserExtension configuration table row mapping is added, it pulls the new data in to the user's UserExtension property.
To set up mappings in ThingWorx Composer:
1. Navigate to the Active Directory directory service in Composer ( > > .
2. Display the Configuration page and scroll down to the section, User Extension Property Mapping Configuration Table, and click Add, as indicated here:
3. In the Active Directory Attribute Name field of the User Extension Property Mapping window, type the name of the Active Directory attribute that you want map automatically to a ThingWorx property. The following screen shot shows the drop-down menu for selecting the ThingWorx property. This drop-down menu is available starting with v.8.3.5 of ThingWorx. Select one of the values in this list.
4. Once you make a selection and click Add; the new row appears in the configuration table:
The options in the following configuration table are available only in ThingWorx 8.2.1 and later.
Attribute | Description | ||
|---|---|---|---|
activeDirectoryAttributeName | The name of an attribute in the Active Directory user's attributes that can be mapped. This field can be left blank to specify a default value for all users synchronized from Active Directory.
| ||
userExtensionPropertyName | The name of the user extension property in the ThingWorx user's UserExtension table that needs to be mapped to the Active Directory attribute.
| ||
userExtensionDefaultValue | The default value for the UserExtension property if the attribute was not found on the AD server, or was invalid or empty. |
Mapping Users and Groups that Exist in Multiple Domains
Users that are members of a group in a separate Active Directory domain can be mapped to their respective groups in ThingWorx by using the Forest Name Identifier option. When this field is populated with any string, a collection/forest of domain controllers is identified. Each directory service object configured with the same string will be able to map groups from each other's domain within their Group Mapping configuration.
Forest Name Identifier Value | Result |
|---|---|
<blank> or empty string | Groups are only visible from the specific directory service object from which they are requested from. |
string that does not match any other directory service configuration | Groups are only visible from the specific directory service object from which they are requested. |
string that matches one or more directory service configurations | Groups are only visible from the specific directory service object from which they are requested as well as from the other directory service objects that have the matching Forest Name Identifier. |
Domain Name | Configured Groups | Forest Name Identifier Value | Visible Groups for Mapping |
|---|---|---|---|
Domain1 | Group1, Group2 | <blank> | Group1, Group2 |
Domain2 | Group3, Group4 | <blank> | Group3, Group4 |
Domain3 | Group5, Group6 | <blank> | Group5, Group6 |
Domain Name | Configured Groups | Forest Name Identifier Value | Visible Groups for Mapping |
|---|---|---|---|
Domain1 | Group1, Group2 | "domainForest1" | Group1, Group2 |
Domain2 | Group3, Group4 | "DomainForest" | Group3, Group4 |
Domain3 | Group5, Group6 | "Domain Forest" | Group5, Group6 |
Domain Name | Configured Groups | Forest Name Identifier Value | Visible Groups for Mapping |
|---|---|---|---|
Domain1 | Group1, Group2 | "domainForest" | Group1, Group2, Group3, Group4 |
Domain2 | Group3, Group4 | "domainForest" | Group1, Group2, Group3, Group4 |
Domain3 | Group5, Group6 | <blank> | Group5,Group6 |
Domain Name | Configured Groups | Forest Name Identifier Value | Visible Groups for Mapping |
|---|---|---|---|
Domain1 | Group1, Group2 | "domainForest" | Group1, Group2, Group3, Group4, Group5, Group6 |
Domain2 | Group3, Group4 | "domainForest" | Group1, Group2, Group3, Group4, Group5, Group6 |
Domain3 | Group5, Group6 | "domainForest" | Group1, Group2, Group3, Group4, Group5, Group6 |
Import Validation Failed
When an Active Directory entity is imported, the import fails only if the value specified in the XML file does not match the data type of the field. For example, if the value test is supplied for the <port> element, the import will fail. Here is an XML snippet that shows when this problem would occur:
<Row>
<adminPassword><![CDATA[]]></adminPassword>
<adminPrincipal><![CDATA[CN=Administrator,CN=Users,DC=domain,DC=com]]></adminPrincipal>
<domain><![CDATA[dc=domain,dc=com]]></domain>
<port>test</port> <================================ INVALID DATA TYPE VALUE FOR <port>. MUST BE AN INTEGER.
<protocol><![CDATA[LDAP]]></protocol>
<server><![CDATA[10.80.21.164]]></server>
</Row>
Here is a screen shot that shows what you will see in Composer:
The following errors are written to the ApplicationLog:
ERROR: [message: Conversion Error on Field port : Unable To Convert From com.sun.org.apache.xerces.internal.dom.ElementNSImpl to INTEGER]
ERROR: Entity import failed
Import Validation Successful
For scenarios where validation fails due to a missing required field or invalid configuration, the directory service entity can still be imported, but it will be marked as disabled. To enable the entity, the invalid fields must be updated.
| | A directory service entity cannot be used for authentication until it is enabled. The process of enabling a directory service entity that was imported as disabled is manual. You must navigate to the disabled entity in ThingWorx Composer, enable it, and save it. |
Here is an example of an invalid configuration, with a comment below the invalid parameter (protocol):
<Row>
<adminPassword><![CDATA[]]></adminPassword>
<adminPrincipal><![CDATA[CN=Administrator,CN=Users,DC=domain,DC=com]]></adminPrincipal>
<domain><![CDATA[dc=domain,dc=com]]></domain>
<port>test</port>
<protocol><![CDATA[INVALID-PROTOCOL]]></protocol>
<== INVALID CONFIGURATION VALUE FOR <protocol>. MUST BE EITHER LDAP OR LDAPS.
<server><![CDATA[10.80.21.164]]></server>
</Row>
Note that this entity successfully imports into ThingWorx:
However, notice that the Enabled check box on the entity itself is not selected, which means that the entity is disabled. Here is an example:
The following error for this scenario appears in the ApplicationLog:
ERROR: Directory Service Error: The URI Scheme must be LDAP or LDAPS
Configuration Error Messages
The following table lists the possible error messages that could appear in the ApplicationLog based on invalid configured fields in the Active Directory entity:
Field | Configuration Section | Error Message | ||
|---|---|---|---|---|
URI Scheme | Connection Settings | Directory Service Error: The URI Scheme must be LDAP or LDAPS. | ||
Server FQDN or IP Address/ Server Network Port | Connection Settings | Directory Service Error: The Server FQDN or IP address cannot be null. Directory Service Error: java.net.MalformedURLException: Not an LDAP URL: <IP>:<Port> Cannot parse url: <IP><Port Directory Service Error: java.net.ConnectException: Connection refused (Connection refused) to 'Server FQDN or IP address' and 'Server Network Port' <IP>:<Port> | ||
Server Network Port | Connection Settings | Directory Service Error: The Server Network port must be in the range of 0 to 65535. | ||
Domain Distinguished Name | Connection Settings | Directory Service Error: The Domain cannot be null. | ||
Administrative Principal Name | Connection Settings | Directory Service Error: The Administrative Principal Name cannot be null.
| ||
Administrative Password | Connection Settings | Directory Service Error: The Administrative Password cannot be null.
| ||
User ID Attribute Name | Schema Mappings | Directory Service Error: The attributeUserIdName cannot be null. | ||
User Base Distinguished Name | Schema Mappings | Directory Service Error: The userBaseDN cannot be null. | ||
Group Object Class Name | Schema Mappings | Directory Service Error: The groupObjectClass cannot be null. | ||
Group Membership Attribute Name | Schema Mappings | Directory Service Error: The memberOfAttribute cannot be null. | ||
Group Attribute Name | Schema Mappings | Directory Service Error: The groupAttribute cannot be null. | ||
User Flags Attribute Name | Schema Mappings | Directory Service Error: The userControlAttribute cannot be null. | ||
User Control Attribute's Disabled Bit | Schema Mappings | Directory Service Error: The userDisableBit cannot be null and must be an integer. | ||
User Control Attribute's Lockout Bit | Schema Mappings | Directory Service Error: The userLockoutBit cannot be null and must be an integer. | ||
Active Directory Group Name | Group Mappings | Directory Service Error: The activeDirectoryGroupName cannot be null. | ||
ThingWorx Group Name | Group Mappings | Directory Service Error: The thingworxGroupName cannot be null. | ||
Provisioned User's Default Home Mashup | User Defaults | Directory Service Error: The userDefaultHomeMashupName cannot be an invalid mashup name. | ||
Provisioned User's Default Mobile Mashup | User Defaults | Directory Service Error: The userDefaulMobileMashupName cannot be an invalid mashup name. | ||
Provisioned User's Default Tags | User Defaults | Directory Service Error: The userDefaulTags cannot have invalid tags. Directory Service Error: The userDefaulTags cannot have an invalid tag name. | ||
ThingWorx User Name | User Provisioning Exclusion List | Directory Service Error: The thingworxUserName cannot be null. |
Testing Active Directory Connectivity
As of v.8.3.5, 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:
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. |
Troubleshooting: Active Directory Domain Prefix and Dynamic User Login
The Active Directory directory service has a configuration setting, Provisioned User's Default Domain Prefix, which can potentially interfere with Dynamic User Login. Here is the set of User Defaults:
The Provisioned User's Default Domain Prefix setting allows you to specify a prefix that restricts which users the directory service can authenticate. If you have multiple Active Directory directory services configured for the same ThingWorx Platform, consider using this option to prevent all the directory services from trying to authenticate the same user.
Note, however, that this prefix is stripped from the user name that is passed to Active Directory. If the specified prefix happens to be the User's Active Directory domain, the user cannot log in to Active Directory.
For example:
1. DOMAIN\ is specified as the Provisioned User's Default Domain Prefix.
2. User DOMAIN\user1 tries to log in to ThingWorx Platform.
3. DOMAIN\ is stripped from the user name that is passed to Active Directory and user1 cannot log in
This issue does not currently affect an Active Directory directory service that has Dynamic User Login disabled.
To work around this issue, follow these practices:
• Avoid using Default Domain Prefix (Preferred) — Avoid using the User's Default Domain Prefix setting when Dynamic User Login is enabled.
• Use a different prefix that users must enter, or have users enter the domain prefix twice — An additional prefix can be specified that is not the DOMAIN\ prefix required for login via DOMAIN\SamAccountName. For example you could have a prefix be PREFIX- and users would then login with PREFIX-DOMAIN\prefix.
Troubleshooting: Invalid Name for UserExtension Property
When mapping an Active Directory attribute to a ThingWorx UserExtension property, you select a name of the UserExtension property from a drop-down menu. The following error message may appear in the ThingWorx Application Log:
Property name: <property_name> not found
in UserExtensions properties
in UserExtensions properties
This error is caused by the following conditions:
• The XML file imported for the Active Directory directory service contains an invalid name for a userExtensionPropertyName AND
• A user logs in and is authenticated by the Active Directory directory service that has the invalid userExtensionPropertyName configured.
This error can occur if you edited the XML file manually. You can remove the invalid entry from the table of User Extension Property Mappings in the Configuration page on the directory service entity in ThingWorx Composer.