Troubleshooting Active Directory Issues
This topic provides the following sections to help you troubleshoot issues with Active Directory:
Entity Import Failed with Unable to Convert Error
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
To resolve the issue, check the XML carefully to ensure that the values provided are of the appropriate data type.
Back to Getting Started
Import Validation Fails But Import Succeeds
For scenarios where validation fails due to a missing required field or invalid configuration, the directory service entity can still be imported, but it will be marked as disabled. To enable the entity, the invalid fields must be updated.
 | A directory service entity cannot be used for authentication until it is enabled. The process of enabling a directory service entity that was imported as disabled is manual. You must navigate to the disabled entity in ThingWorx Composer, enable it, and save it. |
Here is an example of an invalid configuration, with a comment below the invalid parameter (protocol):
<Row>
<adminPassword><![CDATA[]]></adminPassword>
<adminPrincipal><![CDATA[CN=Administrator,CN=Users,DC=domain,DC=com]]></adminPrincipal>
<domain><![CDATA[dc=domain,dc=com]]></domain>
<port>test</port>
<protocol><![CDATA[INVALID-PROTOCOL]]></protocol>
<== INVALID CONFIGURATION VALUE FOR <protocol>. MUST BE EITHER LDAP OR LDAPS.
<server><![CDATA[10.80.21.164]]></server>
</Row>
Note that this entity successfully imports into ThingWorx:
However, notice that the Enabled check box on the entity itself is not selected, which means that the entity is disabled. Here is an example:
The following error for this scenario appears in the ApplicationLog:
ERROR: Directory Service Error: The URI Scheme must be LDAP or LDAPS
Back to Getting Started
Configuration Error Messages
The following table lists the possible error messages that could appear in the ApplicationLog based on invalid configured fields in the Active Directory entity. A short table follows that provides links to the Configuration Sections listed in this table:
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. |
The following table links to topics related to the configuration sections in the table above:
Configuration Section | Topic |
|---|---|
Connection Settings | |
Schema Mappings | |
Group Mappings | |
User Defaults | |
User Provisioning Exclusion List |
Troubleshooting: Active Directory Domain Prefix and Dynamic User Login
The Active Directory directory service has a configuration setting, Provisioned User's Default Domain Prefix, which can potentially interfere with Dynamic User Login. Here is the set of User Defaults:
The Provisioned User's Default Domain Prefix setting allows you to specify a prefix that restricts which users the directory service can authenticate. If you have multiple Active Directory directory services configured for the same ThingWorx Platform, consider using this option to prevent all the directory services from trying to authenticate the same user.
Note, however, that this prefix is stripped from the user name that is passed to Active Directory. If the specified prefix happens to be the User's Active Directory domain, the user cannot log in to Active Directory.
For example:
1. DOMAIN\ is specified as the Provisioned User's Default Domain Prefix.
2. User DOMAIN\user1 tries to log in to ThingWorx Platform.
3. DOMAIN\ is stripped from the user name that is passed to Active Directory and user1 cannot log in
This issue does not currently affect an Active Directory directory service that has Dynamic User Login disabled.
To work around this issue, follow these practices:
• Avoid using Default Domain Prefix (Preferred) — Avoid using the User's Default Domain Prefix setting when Dynamic User Login is enabled.
• Use a different prefix that users must enter, or have users enter the domain prefix twice — An additional prefix can be specified that is not the DOMAIN\ prefix required for login via DOMAIN\SamAccountName. For example you could have a prefix be PREFIX- and users would then login with PREFIX-DOMAIN\prefix.
Back to Dynamic User Login
Troubleshooting: Invalid Name for UserExtension Property
When mapping an Active Directory attribute to a ThingWorx UserExtension property, you select a name of the UserExtension property from a drop-down menu. The following error message may appear in the ThingWorx Application Log:
Property name: <property_name> not found
in UserExtensions properties
in UserExtensions properties
This error is caused by the following conditions:
• The XML file imported for the Active Directory directory service contains an invalid name for a userExtensionPropertyName AND
• A user logs in and is authenticated by the Active Directory directory service that has the invalid userExtensionPropertyName configured.
This error can occur if you edited the XML file manually. You can remove the invalid entry from the table of User Extension Property Mappings in the Configuration page on the directory service entity in ThingWorx Composer.