Security > Directory Services Authentication > Managing Users in Active Directory
  
Managing Users in Active Directory
User and user group management can be done in ThingWorx if the users already exist in Microsoft’s 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
XML Example: Single Directory Service
XML Example: Two Directory Services
Configuration for Directory Services
Connection Settings
Dynamic User Login
Group Mappings
Group Mapping with Dynamic User Login
Group Validation For Group Mapping
Nested Group Membership
Schema Mappings
User Provisioning
User Default Settings
User Provisioning Exclusion List
User Login Scenarios
User Lockout Scenarios
Active Directory or ThingWorx Directory Service Changes
Mapping Active Directory User Attributes to the ThingWorx UserExtension Property
Mapping Users and Groups that Exist in Multiple Domains
Import Validation Failed
Import Validation Successful
Configuration Error Messages
Testing Active Directory Connectivity
Troubleshooting: Active Directory Domain Prefix and Dynamic User Login
Troubleshooting: Invalid Name for UserExtension Property
Getting Started
To get started, create a directory service in ThingWorx by importing an entities XML file into ThingWorx. After the file is imported, configuration for the directory service can be defined in ThingWorx. The following rules must be followed in 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 runtime.
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 runtime that corresponds to the order that ThingWorx should consult the Directory Service during credential validation.
* 
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. Reference the examples below.
Back to top
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>

Back to top
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>
Back to top
Configuration for Directory Services
Once you have imported an XML file for an Active Directory directory service, you need to 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 in 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 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 group lookup, so if you are taking advantage of 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 lookup of a user object in Active Directory with the username and the password given during ThingWorx login.
* 
When configuring multiple Directory Services objects, do not overlap user search bases within your Active Directory structure.
Back to top
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 lists and briefly describes the Connection Settings for a directory service.
Connection Settings
* 
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 user group lookup.
domain
n/a
DC=test, DC=acme, DC=com
Dynamic User Login
Whether Dynamic User Login is enabled. See the section below 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 is dependent 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
Back to top
Dynamic User Login
* 
It is recommended that users authenticate with the ThingWorx platform using the same username every time when Dynamic User Login is enabled. Failure to do so will result in the same user creating multiple ThingWorx platform user accounts due to a current limitation with the ThingWorx platform. 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
Authenticate the user who is logging into ThingWorx Platform directory to Active Directory with their user name and password.
Currently supported means of Active Directory authentication: displayName, UPN and domain\samAccountName
If Dynamic User Login is disabled, the workflow for user login remains the same as it exists in ThingWorx Platform 8.3.0 through 8.3.4.
Back to top
Group Mappings
Make sure that you understand ThingWorx visibility, permission, and organization rules for users and groups to make sure that mapping is as intended. If permissions are not assigned correctly, it may result in users having access to 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 in ThingWorx Composer navigate to the Active Directory directory service in Composer (Security > Directory Services > <Active Directory Service Name>. Display the Configuration page, and scroll down to the Group Mappings section, and click Add, as indicated in the following figure:
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. 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. The form displayed when Dynamic User Login is enabled appears after this one.
GroupMappings Form, with Dynamic User Login Disabled
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.
GroupMappings Form, with Dynamic User Login Enabled
When the Provide Credentials dialog appears, set the AdministrativePrincipalName and AdministrativePassword, and click Set.
Provide Credentials Dialog
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 runtime.
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 runtime. 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.
Back to top
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 TestConnecction service works with all the required credentials. Any time that the parameters are empty, the services use the administrator credentials.
* 
Back to top
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. For example, if you enter the groupName Group*, the service immediately returns "false". This service is intended to provide information about a single group. Using a wild card may imply multiple groups and is not a valid search criteria.
Back to top
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
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.
Back to top
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.
Schema Mappings
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 amount of domain groups.
* 
If you have a large number of groups, this parameter should be configured (do not leave empty). If left empty, the performance of retrieving the large quantity of groups may be impacted.
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.
* 
Use distinguishedName to display the full path to the location of the group in Active Directory. This provides context of the sub-domain that it belongs to when a group exists in more than one domain.
groupAttribute
cn
cn
User Flags Attribute Name
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, reference 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, reference 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 below for examples of using this option.
forestNameIdentifier
n/a
Back to top
User Provisioning
The options for user provisioning include allowing for automated creation, modification, and deletion of 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 the login of a user is attempted.
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 creating 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 deletion to be successful. If the user belongs to the User Provisioning Exclusion List configuration table, this field has no affect on auto deleting the user.
userDeletionEnabled
false
Set to true to allow the Directory Service in ThingWorx to delete users.
Back to top
User Default Settings
* 
All User Default Settings 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 that should 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.
* 
It is recommended to use a domain prefix if the same user exists in several domain servers and their domains. This minimizes un-deterministic behavior that could arise due to the "water flow" down functionality upon failed user validation.
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.
* 
This setting may cause unexpected results with Dynamic User Login enabled as the Provisioned User’s Default Domain Prefix is stripped from the username entered at the time of user authentication before attempting to bind with Active Directory. For example, if the “Provisioned User’s Default Domain Prefix” is set to “mydomain\” and a User enters “mydomain\username” while authenticating with ThingWorx, only “username” is sent to Active Directory for authentication. This authentication may fail for that user even if “mydomain\username” is that User’s domain\samAccountName within Active Directory
* 
If the same username exists in multiple Active Directory domains, authentication will fail if the current user logging in is not the actual user found in Active Directory. This will be based on the order of being queried.
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
This option should be used 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 tag(s) for all provisioned users (i.e. auto-created/updated users) is preferred.
Back to top
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 a Active Directory directory service, existing users may not wish their configuration and existence to be managed by Active Directory; only credential validation is desired. Users that fit this profile 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, so it should also not be auto modified. Doing so could cause undesired configuration changes at login.
Back to top
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 result in a change to 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
Back to top
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, based on the lock evaluation, determines the lockout.
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
* 
The recommended lockout configuration is to have ThingWorx and Active Directory match.
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
Back to top
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 user default settings change, then it is highly recommended to use the TerminateUserSessions service in the CurrentSessionInfo Resource for that user in ThingWorx.
* 
If any of the following configuration changes are made, and a user exists that 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 User ID Attribute Name configuration value in the Schema Mappings configuration is a user name.
Domain prefix changed.
Back to top
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 navigate to the Active Directory directory service in Composer (Security > Directory Services > <Active Directory Service Name>. Display the Configuration page and scroll down to the section, User Extension Property Mapping Configuration Table, and click Add, as indicated here:
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.
Once you make a selection and click Add; the new row appears in the Configuration Table:
* 
The options in the following configuration table are only available in ThingWorx 8.2.1 and later.
Attribute
Description
activeDirectoryAttributeName
The name of an attribute in the AD 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.
* 
If an attribute is specified but is not found on a user in Active Directory, the following error message will appear in the Application Log:
Attribute: <attribute_name> not found.
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.
* 
If you see an error message in the Application Log that the name of the userExtensionProperty is invalid, see Troubleshooting: Invalid Name for UserExtension Property.
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 maps groups from each others' domain within their Group Mapping configuration.
Back to top
Validation
Forest Name Identifier Value
Result
<blank> or empty string
Groups only visible from the specific Directory Service object being requested from.
string that does not match any other Directory Service configuration
Groups only visible from the specific Directory Service object being requested from.
string that matches one or more Directory Service configurations
Groups visible from the specific Directory Service object being requested as well as the other Directory Service objects that have the matching Forest Name Identifier.
Example 1: Groups visible from the specific Directory Service object being requested as well as 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
Example 2: The Forest Name Identifier on all Directory Service objects is different
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
Example 3: The Forest Name Identifier on 2 of the 3 Directory Service objects is identical
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
Example 4: The Forest Name Identifier on all three Directory Service objects is identical
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
Back to top
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
Back to top
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 platform:
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
Back to top
Configuration Error Messages
Here are the possible errors that could show up in the ApplicationLog based on invalid configured fields in the Active Directory entity:
Configuration Error Messages
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.
* 
If "Dynamic User Login" is NOT enabled/checked, the Administrative Principal Name is required.
Administrative Password
Connection Settings
Directory Service Error: The Administrative Password cannot be null.
* 
If Dynamic User Login is NOT enabled, the Administrative Password is required.
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.
Back to top
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
This 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 Test Connection button is hidden.
Back to top
Troubleshooting: Active Directory Domain Prefix and Dynamic User Login
The Active Directory directory service has a configuration setting, called 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 having 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 ActiveDirectory. If the specified prefix happens to be the User's Active Directory domain, the user cannot log in to Active Directory.
For example:
DOMAIN\ is specified as the Provisioned User's Default Domain Prefix.
User DOMAIN\user1 tries to log in to ThingWorx platform.
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.
Workarounds
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.
Back to top
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
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 DirectoryService entity in ThingWorx Composer.
Back to Mapping Active Directory User Attributes to the ThingWorx UserExtension Property
Back to top