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
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
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 properties" in ThingWorx
