Portal to AD sync
The synchronization of users from the portal to an AD can be done by configuring an AD provider to the portal that will save every change on the portal to an AD action node. The saved actions can later be synced by executing a stand-alone console application. The program can be found in the webfolder at
When executed the program goes through all saved actions, connects to the AD servers according to the sync-trees specified in the configuration and registers changes of saved actions in the AD in corresponding order.
For general details please refer to Active Directory Synchronization.
To configure portal->AD sync follow these steps:
- 1. Customize and save configuration node
- 2. Add the following line to the Web.config's appSettings section:
<add key="DirectoryProvider" value="SenseNet.DirectoryServices.ADProvider" />
- 3. Customize and save SyncPortal2AD.exe.config. Set connectionstring and don't forget to configure MSMQ.
- 4. Make sure that the user running the console application has sufficient rights to connect to the AD and modify/create objects in it*
- 5. Optionally create a task in the task scheduler to run the application periodically.
*Note that it is adequate to create a user in the AD having the same username and password as the currently logged on Windows user.
If an object is changed on the portal under a configured sync-tree a saved action node is created under
These saved action content are then later processed by the stand-alone scheduled synchronizer application and syncing of portal objects are done accordingly. A saved action node is a standard xml file with similar content as follows:
<?xml version="1.0" encoding="utf-8"?> <ADAction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <ActionType>CreateNewADUser</ActionType> <NodeId>2123</NodeId> <PassWd>1</PassWd> <NewPath>/Root/IMS/NATIV/MyOrg/myNewUser</NewPath> <LastException>Connecting to AD server failed at SenseNet.DirectoryServices.SyncPortal2AD.CreateNewADUser(User user, String newPath, String passwd) in C:\development\SenseNet\Dev\Application\Source\SenseNet\DirectoryServices\SyncPortal2AD.cs:line 313 at SenseNet.DirectoryServices.ADAction.Execute() in C:\development\SenseNet\Dev\Application\Source\SenseNet\DirectoryServices\ADAction.cs:line 82 at SenseNet.DirectoryServices.ADProvider.Worker.DoWork(Object threadContext) in C:\development\SenseNet\Dev\Application\Source\SenseNet\DirectoryServices\ADProvider.cs:line 123 Logon failure: unknown user name or bad password. </LastException> </ADAction>
The info file contains the type of the action, the referenced portal node's ID, and two optional parameters: the cleartext password of the user when it is set or changed and the path of the object when created or moved. The cleartext password is only stored here when allowed by the SaveClearTextPassword node in the configuration. Note that error information is also registered here, not only in the log.
If the execution of a saved action is successful and no error is raised then the corresponding saved action node is deleted. When executing an action fails the saved action node is updated with the error description and the program moves on to the next action. Failed actions can later be re-executed by running the console application once again.
The settings for Portal to AD sync be found under
Below you can see a fully featured skeleton of an portal->AD configuration xml:
<?xml version="1.0" encoding="utf-8"?> <DirectoryServices> <General> <NovellSupport>[true/false]</NovellSupport> <CustomADAdminAccount> <UserName></UserName> <Password></Password> </CustomADAdminAccount> <SyncEnabledState>[true/false]</SyncEnabledState> <SyncUserName>[true/false]</SyncUserName> <CreatedAdUsersDisabled>[true/false]</CreatedAdUsersDisabled> <ADNameMaxLength>20</ADNameMaxLength> <ADsAMAccountNameMaxLength>20</ADsAMAccountNameMaxLength> <SaveClearTextPassword>false</SaveClearTextPassword> <AllowRename>[true/false]</AllowRename> <AllowMove>[true/false]</AllowMove> </General> <SyncTrees> <SyncTree> <AdPath></AdPath> <PortalPath></PortalPath> <DomainIp></DomainIp> <DeletedADObjectsPath></DeletedADObjectsPath> <PortalExceptions> <PortalException></PortalException> </PortalExceptions> <SyncGroups></SyncGroups> </SyncTree> </SyncTrees> <PropertyMappings> <PropertyMapping separator=""> <AdProperty unique="" maxLength=""></AdProperty> <PortalProperty unique="" maxLength=""></PortalProperty> </PropertyMapping> </PropertyMappings> </DirectoryServices>
The configuration xml can be divided into 3 main parts:
- General settings (<General>)
- Sync-tree definitions (<SyncTrees>)
- User property mapping definitions (<PropertyMappings>)
The following settings can be customized under the <General> settings node:
- NovellSupport: set this property to true when using eDir to Portal sync (optional).
- CustomADAdminAccount: this property holds information about the user having sufficient rights to retrieve information from eDirectory when using eDir to Portal sync (optional).
- SyncEnabledState: when set to true the enabled/disabled state of users are synchronized (optional, default is false)
- SyncUserName: when set to true the name of users are synchronized (optional, default is false)
- CreatedAdUsersDisabled: when set to true every user created in the AD will be created as disabled. Otherwise every AD user is created in the same state as its corresponding portal object was set to.
- ADNameMaxLength: the created AD user's name's length will not exceed the value set here (if set to longer it will be truncated in AD)
- ADsAMAccountNameMaxLength: the created AD user's or group's account name property's length will not exceed the value set here (if set to longer on the portal it will be truncated in AD). Leave this value set to 20 as this is the default maximum length of an account name in AD.
- SaveClearTextPassword: when set to true cleartext passwords of users are stored in saved action files when changing or setting passwords of portal users under a configured sync-tree.
- AllowRename: set this property to true to enable renaming of AD objects (optional, default is false).
- AllowMove: set this property to true to enable moving of AD objects (optional, default is false).
One or more sync-trees has to be defined in the configuration under the node <SyncTrees>. A sync-tree definition should contain the following:
- AdPath: path of the AD sync-tree root object. The referred AdPath has to exist on the AD server.
- PortalPath: path of the portal sync-tree root object. The PortalPath may refer to a non-existing path on the portal - in this case it will be automatically created using the parent and ancestor names defined in the PortalPath and the corresponding AD object types according to AdPath.
- DomainIp: IP Address of the AD server containing the sync-tree root object
- DeletedADObjectsPath: when objects are deleted from the portal, the corresponding AD objects except users are also deleted. AD users instead are moved to the path defined in this configuration node.
- PortalExceptions: objects under the portal path defined here will not be synchronized (separate exceptions should be defined in a PortalException node)
- SyncGroups (optional): when set to false, groups under the current sync-tree will not be synchronized. Useful when users don't have permission to modify group membership in AD, however they have permissions to modify repository group memberships - in which case syncing group memberships to AD would cause security threat. Default is true. This feature is only available in version 6.2 and above. Note: if set to false AD actions will not be created for groups upon change/creation, however existing AD actions will be executed regardless of this setting - delete AD actions corresponding to groups when changing this property if this behavior is not acceptable.
User property mapping definitions
Mappings of different user properties can be defined under the <PropertyMappings> configuration node. A property mapping consists of the following definitions:
- AdProperty node: defines an AD user's property name
- PortalProperty node: defines a portal user's property name
- unique attribute: indicates that the property's value must be unique, so when the object is deleted this property's value is going to be prefixed with deletion date
- maxLength attribute: indicates that the property's value's length may not exceed the defined. If the length of the property's value is greater than what defined here then the value will be truncated.
In special cases the different properties cannot be mapped one-on-one to each other. With the aid of the separator attribute of the PropertyMapping node a separator character can be defined that splits up a property value to many. The following scenarios are supported:
- one AD property and one portal property: the given property values are mapped to each other one-on-one
- more AD property and one portal property:
- portal->AD: the single portal property value is split up along the separator and the resulting values are set to the given AD properties in corresponding order
- one AD property and more portal property:
- portal->AD: values of portal properties are concatenated with the separator in corresponding order and the resulting value is set to the single AD property
for System operators
To run Active Directory Synchronization the console tool has to be executed using a proper account that have sufficient permissions in the AD.
The following xml is a simple example for an portal->AD synchronization configuration. It synchronizes users, groups, organizational units, containers from /Root/IMS/NATIV/MyOrg to OU=MyOrg,DC=Nativ,DC=local to the AD server at 192.168.0.75. For users two properties are synced: Email and FullName - the latter is separated along commas into three separate strings and set as givenName, sn, initials properties of the synced AD users.
<?xml version="1.0" encoding="utf-8"?> <DirectoryServices> <General> <CreatedAdUsersDisabled>false</CreatedAdUsersDisabled> <ADNameMaxLength>20</ADNameMaxLength> <ADsAMAccountNameMaxLength>20</ADsAMAccountNameMaxLength> <SaveClearTextPassword>false</SaveClearTextPassword> <SyncEnabledState>false</SyncEnabledState> <SyncUserName>true</SyncUserName> <AllowRename>false</AllowRename> </General> <SyncTrees> <SyncTree> <AdPath>OU=MyOrg,DC=Nativ,DC=local</AdPath> <PortalPath>/Root/IMS/NATIV/MyOrg</PortalPath> <DomainIp>192.168.0.75</DomainIp> <DeletedADObjectsPath>CN=Deleted,OU=MyOrg,DC=Nativ,DC=local</DeletedADObjectsPath> </SyncTree> </SyncTrees> <PropertyMappings> <PropertyMapping> <AdProperty unique="true">mail</AdProperty> <PortalProperty unique="true">Email</PortalProperty> </PropertyMapping> <PropertyMapping separator=","> <AdProperty>givenName</AdProperty> <AdProperty>sn</AdProperty> <AdProperty maxLength="6">initials</AdProperty> <PortalProperty>FullName</PortalProperty> </PropertyMapping> </PropertyMappings> </DirectoryServices>
Q: What happens if I move a synced orgunit to another path in the same sync-tree?
A: The orgunit and all of its contents will be moved on the AD to the corresponding place.
Q: What happens if I move a synced object to a path that is not under any defined sync-tree?
A: An error message is popped up as this move is not permitted.
Q: What happens if I move a synced object to a path that is under a different sync-tree?
A: If the target sync-tree resides on the same AD server as the source sync-tree, the object is moved. Otherwise an error message is popped up as it is not permitted to move objects to different AD servers.
Q: What happens if I move an unsynced object under a sync-tree?
A: An error message is popped up as this move is not permitted. Create a new user under the sync-tree instead.
Q: What happens if I create a new user under a sync-tree but the AD server is unavailable?
A: The user is created on the portal and an error is logged. The user can later be synced by re-executing failed actions.
Q: What happens if I create a new user under a sync-tree but the properties defined cause an error in the AD?
A: The user is not created and an error is logged. Try changing user properties and re-executing failed actions.
Q: What happens if I update a user so that its name and some properties are changed but some property changes cause an error in the AD?
A: No changes are updated and an error is logged.
Q: What happens if I update a user so that its name and some properties are changed but the name change cause an error in the AD?
A: Property changes get updated but the name remains unchanged and an error is logged.
Q: What happens if I create a new orgunit but the AD server is unavailable and when it becomes available I create a new user under the created orgunit?
A: Both creating the orgunit and the user will raise an error and create failed action files. Re-execution of these will fix the problem and create the orgunit and the user in the portal in corresponding order.
Q: What happens if I put an unsynced user in a synced group?
A: A warning is logged. This does not affect the other users in the group.
Q: What happens if I delete a user from the portal?
A: The corresponding user in the AD is disabled and moved to the configured trash folder. It is renamed and its unique property values are prefixed with the date of deletion.
Q: What happens if I delete an orgunit or AD Folder from the portal?
A: Every AD object contained in the corresponding container is deleted including the container itself. Contained users are disabled and moved to trash folder (see user deletion).
Q: What happens if I delete a group from the portal?
A: The corresponding AD group is deleted. Contained member users remain unchanged.
Q: What happens if I deleted a synced user from the portal and then I create a new user with the same properties?
A: The deleted user is moved to trash and a new user is created with a new Guid.
Q: What happens if I configure a sync-tree to refer to an existing portal path with users in it and I update a user?
A: Nothing happens, since the object does not have a Guid and is considered an unsynced object.
Q: What happens if I clear the value of a synced user's property?
A: The corresponding AD property is erased from the users datasheet.