Active Directory Groups and Dynamic User Login
This topic explains the following features of using Active Directory with your ThingWorx Platform:
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, 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.
To troubleshoot a problem with Dynamic User Login, refer to Troubleshooting: Active Directory Domain Prefix and Dynamic User Login.
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 Mappings 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, 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, userPrincipalName | ||
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 Mappings configuration. See the next sections for the examples of using this option. | forestNameIdentifier | n/a |