|
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.
|
|
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.
|
|
The examples below are for an administrator user.
|
|
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.
|
|
When configuring multiple directory services objects, do not overlap user search bases within your Active Directory structure.
|
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 |
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. |
The following GroupMappings form is displayed when Dynamic User Login is disabled. |
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. |
The wild-card character ("*") is NOT allowed as part of the input for groupName. |
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 |
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. |
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. |
The administrator user is automatically added to this list, and should not be removed. |
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 |
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 |
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. |
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. |
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 |
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. |
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. |
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. |
If Dynamic User Login is enabled, then the "Administrative Principal Name" and "Administrative Password" are not used and the Verify button is hidden. |