Active Directory Users

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

This topic explains what you need to know about Active Directory users, from provisioning through lockout scenarios:

• User Provisioning

• User Default Settings

• User Provisioning Exclusion List

• User Login Scenarios

• User Lockout Scenarios

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.

It is recommended to use a domain prefix if the same user exists in several domain servers and their domains. This minimizes non-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 user who is 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

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

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