cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

Reviewing the new Active Directory feature and avoiding pitfalls while setting it up

Tanzanite

Reviewing the new Active Directory feature and avoiding pitfalls while setting it up

With the release of ThingWorx 8.2.1 , we now have the possibility to auto provision the user attributes along with the user on its first login in ThingWorx via Active Directory Authentication. In the previous releases this was not available and after the initial user provisioning, users had to fill in rest of the user attribute details e.g. zipCode, City, Title, MobilePhone , etc.

However with ThingWorx 8.2.1 and later we have following new attributes for configuration when the Active Directory entity is created in ThingWorx, namely

 

  • activeDirectoryAttributeName
  • userExtensionPropertyName
  • userExtensionDefaultValue

activeDirectoryAttributeName : Represents the attribute within AD for an user

 

userExtensionPropertyName : This represents the attribute available for the user, as defined in the UserExtensions ThingShape

 

userExtensionDefaultValue : Default value that will be assigned in case the attribute value in AD for a particular user is empty/null

 

XML representation for these new tags

 

 

<ConfigurationTable description="User Extension Property Mapping Configuration Table" isMultiRow="true" name="UserExtensionPropertyMapping" ordinal="6">
                    <DataShape>
                        <FieldDefinitions>
                            <FieldDefinition aspect.friendlyName="Active Directory Attribute Name" baseType="STRING" description="Active Directory Attribute Name" name="activeDirectoryAttributeName" ordinal="0"/>
                            <FieldDefinition aspect.friendlyName="Provisioned User's User Extension Property Default Value" baseType="STRING" description="Provisioned User's User Extension Property Default Value" name="userExtensionDefaultValue" ordinal="2"/>
                            <FieldDefinition aspect.friendlyName="Provisioned User's User Extension Property Name" aspect.isPrimaryKey="true" baseType="STRING" description="Provisioned User's User Extension Property Name" name="userExtensionPropertyName" ordinal="1"/>
                        </FieldDefinitions>
                    </DataShape>
                    <Rows>
                        <Row>
                            <activeDirectoryAttributeName>
                                <![CDATA[userPrincipalName]]>
                            </activeDirectoryAttributeName>
                            <userExtensionDefaultValue>
                                <![CDATA[blah]]>
                            </userExtensionDefaultValue>
                            <userExtensionPropertyName>
                                <![CDATA[emailAddress]]>
                            </userExtensionPropertyName>
                        </Row>
                        <Row>
                            <activeDirectoryAttributeName>
                                <![CDATA[streetAddress]]>
                            </activeDirectoryAttributeName>
                            <userExtensionDefaultValue>
                                <![CDATA[SomeDefaultValue]]>
                            </userExtensionDefaultValue>
                            <userExtensionPropertyName>
                                <![CDATA[mailingAddress]]>
                            </userExtensionPropertyName>
                        </Row>
                        <Row>
                            <activeDirectoryAttributeName/>
                            <userExtensionDefaultValue>
                                <![CDATA[DefaultValue]]>
                            </userExtensionDefaultValue>
                            <userExtensionPropertyName>
                                <![CDATA[title]]>
                            </userExtensionPropertyName>
                        </Row>
                        <Row>
                            <activeDirectoryAttributeName>
                                <![CDATA[DefaultDemoTitle]>
                            </activeDirectoryAttributeName>
                            <userExtensionDefaultValue/>
                            <userExtensionPropertyName/>
                        </Row>
                        <Row>
                            <activeDirectoryAttributeName/>
<![CDATA[pincode]> <userExtensionDefaultValue/> <userExtensionPropertyName> <![CDATA[zipCode]]> </userExtensionPropertyName> </Row> </Rows> </ConfigurationTable

 

Note: This is not a complete XML file for creating the Active Directory entity in ThingWorx, rather only a part of the XML for basic initial XML configuration refer to the Managing Users in Active Directory section in Security > Directory Service Authentication in ThingWorx Help Center

 

With the above configuration once the Active Directory entity is successfully created under the ThingWorx Composer > Security > Directory Services, navigate to it and scroll down to the section named User Extension Property Mapping Configuration Table

 

14-03-2018 14-41-02.jpgConfiguration for Directory Service

Extending on basic structure

Once the Active Directory entity is successfully created and connected to the target Active Directory, all the users that now gets provisioned from Active Directory within ThingWorx will get their attributes filled up automatically, given that the mapping is correct and the value actually exists in Active Directory for those mapped attributes, something like this

14-03-2018 14-44-36.jpg

 

 

PS: Attributes not mapped will be left blank in the user's user extension properties

 

Auto populating of entities will also happen even after the user has been created on first login. Meaning if there are further AD attributes which are mapped with the user's user extension properties, value for them will also be pulled on next login done by the user there is no need for ThingWorx restart here.

 

As shown in the screenshot above for section User Extension Property Mapping Configuration Table, these values can be added or deleted.

 

Pitfalls to avoid

It may happen that despite the mapping values may not auto populate, for such scenarios ensure that:

 

  • AD attribute used in the section Active Directory Attribute Name must match exactly the way it is in the AD, e.g. zipCode mentioned in the section Active Directory Attribute Name may be called as Zip Code in the AD attribute. This may likely lead to error <attribute_name> attribute not found in ApplicationLog.log
  • Empty/invalid values in AD's user attributes will not populate the User's user extension properties
  • Attribute names used in the column Provisioned User's User Extension Property Name also need to exactly match the way they are defined in the UserExtensions ThingShape, failing to do so will likely lead to error  Property name: {} not found in UserExtensions properties in ApplicationLog.log
  • To void using incorrect attribute name copy out the exact property names from UserExtensions ThingShape
  • UserExtensions ThingShape can be located in ThingWorx Composer > Modeling > Thing Shapes ; click on the UserExtensions > Properties to view all available properties
  • UserExtensions ThingShape can also be edited to add more properties to it, which can later be used for mapping it with the AD attributes

 

Additional read:

An enhancement jira has been filed to allow users to have a drop down menu for column Provisioned User's User Extension Property Name, for quick and accurate selection, see Some User Extension Property Mapping fails with warning "Property name: not found in UserExtensions ...