AD to Portal sync (old)

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.0
  • Enterprise
  • Community
  • Planned

Overview

The synchronization of users from AD to the portal can be done by executing a stand-alone console application. The program can be found in the webfolder at

bin\SyncAD2Portal.exe

When executed the program connects to the AD servers according to the sync-trees specified in the configuration and synchronizes all objects to the portal in the following order:

  • All Organizational Units and AD Folders in all sync-trees are updated
  • All Users in all sync-trees are updated
  • All Groups in all sync-trees are updated
  • All Users on the portal that are not present in AD are deleted
  • All Groups on the portal that are not present in AD are deleted
  • All Organizational Units and AD Folders on the portal that are not present in AD are deleted

For general details please refer to Active Directory Synchronization.

Details

Installation

To configure AD->portal sync follow these steps:

  1. Customize and save configuration node
  2. Customize and save SyncAD2Portal.exe.config. Set connectionstring and don't forget to configure MSMQ.
  3. Make sure that the user running the console application has sufficient rights to connect to the AD and retrieve objects from it*
  4. 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.

Configuration

The settings for AD to Portal sync be found under

/Root/System/SystemPlugins/Tools/DirectoryServices/AD2PortalConfig.xml

Please note that all configuration values (AD and Content Repository paths, property names, etc.) are case sensitive. Please use the exact same names here as the ones you see in the Active Directory.

Below you can see a fully featured skeleton of an AD->portal 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>
    <DeletedPortalObjectsPath></DeletedPortalObjectsPath>
    <AlwaysSyncObjects>[true/false]</AlwaysSyncObjects>
    <UserType></UserType>
  </General>
  <SyncTrees>
    <SyncTree>
      <AdPath></AdPath>
      <PortalPath></PortalPath>
      <DomainIp></DomainIp>
      <ADExceptions>
        <ADException></ADException>
      </ADExceptions>
      <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>)

General settings

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)
  • DeletedPortalObjectsPath: when objects are deleted from the AD, the corresponding portal objects except users are also deleted. Portal users instead are moved to the path defined in this configuration node.
  • AlwaysSyncObjects: when set to true objects from AD are always synced regardless of what their whenchanged attributes are set to. Note that path of objects is always synchronized, this setting refers to property changes.
  • UserType: the custom user type that is created when a new AD user is synced to the portal (optional, default is User)

Sync-tree definitions

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.

Please note that in case of AD->Portal sync if the portal object located at PortalPath was created manually its SyncGuid property of the object has to be manually set to the objectGuid of the corresponding AD object!

The PortalPath should be the exact match of AdPath (ie OU=x,OU=y,OU=z,DC=a,DC=b should be mapped to /Root/IMS/a/z/y/x). To skip a line of levels (ie. /Root/IMS/a/x) the top container (x) should be manually created and SyncGuid property should be set before syncing!

Up until version 6.0.3 a manually set SyncGuid property should be given lower-case (ie.: e8cce49b-fe11-48ad-807d-387926bfffdd)!

  • DomainIp: IP Address of the AD server containing the sync-tree root object
  • ADExceptions (optional): objects under the AD path defined here will not be synchronized (separate exceptions should be defined in an ADException node)
  • SyncGroups (optional): when set to false, groups under the current sync-tree will not be synchronized. Useful to speed up syncing when group sync is not necessary. Default is true. This feature is only available in version 6.0.4 and above.

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:
    • AD->portal: the single AD property value is split up along the separator and the resulting values are set to the given portal properties in corresponding order

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.

Example/Tutorials

The following xml is a simple example for an AD->portal synchronization configuration. It synchronizes users, groups, organizational units, containers from OU=MyOrg,DC=Nativ,DC=local to /Root/IMS/NATIV/MyOrg from the AD server at 192.168.0.75. For users four properties are synced: mail, givenName, sn, initials - the latter 3 are concatenated into a single string and set as FullName of the synced portal users.

<?xml version="1.0" encoding="utf-8"?>
<DirectoryServices>
  <General>
    <DeletedPortalObjectsPath>/Root/IMS/Deleted</DeletedPortalObjectsPath>
    <AlwaysSyncObjects>true</AlwaysSyncObjects>
    <SyncEnabledState>false</SyncEnabledState>
    <SyncUserName>true</SyncUserName>
  </General>
  <SyncTrees>
    <SyncTree>
      <AdPath>OU=MyOrg,DC=Nativ,DC=local</AdPath>
      <PortalPath>/Root/IMS/NATIV/MyOrg</PortalPath>
      <DomainIp>192.168.0.75</DomainIp>
    </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>

FAQ

Q: How can I assign permission settings for the groups in AD?

A: After the first synchronization users and groups will be created on the portal. Group membership information is also synchronized, so the portal groups will cotain those users whose pairs in AD are members of the corresponding AD groups. You can assign permissions to the created portal groups after the first synchronization. These permission settings will remain unchanged for subsequent synchronizations, as long as the groups are not deleted from AD.


Q: Can I synchronize objects from AD after I have manually created them in the portal?

A: Only if you set the SyncGuid property of the portal object (let it be an OU, an ADFolder, a Group, or a User) to the value of the objectGuid property of the corresponding AD object, and start the sync afterwards. This method however is not advised. We encourage you to set up the AD sync configuration so that all portal objects are created by the first synchronization.


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 portal 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: This is considered as deletion and object is deleted from the portal (users are disabled, other objects are deleted).


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 it is undefined - we never executed such tests.


Q: What happens if I move an unsynced object under a sync-tree?

A: This is considered as creating a new object so a new object is created on the portal.


Q: What happens if I move a synced object out from a sync-tree and then move it back later?

A: In case of users the object is deleted and thus moved to the trash folder. Then it is moved back and its properties get updated - provided that the trash folder is under /Root/IMS. In case of other types of objects the object will be deleted and later a new object is created.


Q: What happens if I create a new user under a sync-tree but the properties defined cause an error on the portal?

A: The user is not created on the portal. Before you try to resync the user make sure to save it in the AD so that its whenchanged property is updated or update the configuration so that users are always synced.


Q: What happens if I update a user so that its name and some properties are changed but the changes cause an error on the portal?

A: The changes are not updated and the error is logged. Before you try to resync the user make sure to save it in the AD so that its whenchanged property is updated or update the configuration so that users are always synced.


Q: What happens if I create a new object in AD and an object with the same name (but no Guid) already exists on the portal?

A: If the existing object with the same name is not under a sync-tree, the object will not be created. Otherwise the new object still cannot be created, but the obstacle object is deleted from the portal, as there won't be any corresponding object in the AD. Thus in the next sync phase the object from AD is synced and a new object on the portal is created.


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 put an unsynced user in a synced group and later move the user under the same sync-tree?

A: Groups are always updated, so the new user created on the portal will be a member of the synced group.


Q: What happens if I delete a user from the AD?

A: The corresponding user on the portal 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 container from the AD?

A: Every portal 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 AD?

A: The corresponding portal group is deleted. Contained member users remain unchanged.


Q: What happens if I deleted a synced user from the AD 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 remove a synced AD user's property?

A: The value of the property on the portal is set to empty.

Related links

References