Active Directory synchronization

From Sense/Net 6.0 Wiki

Jump to: navigation, search

Contents

[edit] General

Sense/Net 6.0 comes with Active Directory (AD) synchronization features:

  • portal users can be synchronized to AD servers, and
  • AD users can be synchronized to the portal.

Changes are updated with batch synchronization meaning that all changes are synchronized periodically in one step with the execution of a stand-alone application.


By setting up Active Directory synchronization users gain the following advantages:

  • when using both Sense/Net 6.0 portal and Active Directory server in an enterprise environment user profiles need not to be maintained in both of the user directories (portal and AD).
  • accessing advanced WebDav features via Integrated Windows authentication (such as editing Office documents online) is easily installed using portal->AD sync.
  • installing a new Sense/Net 6.0 portal with Forms authentication into an environment with already existing AD server containing dozens of users is easily done by using AD->portal sync and activating Forms authentication from AD.


Refer to the following guides on how to activate AD sync in either direction and for detailed explanation on what different changes on either side trigger:


It is also possible to connect to a Novel eDirectory and synchronize users to the portal. Refer to the following guides on how to configure AD sync with Novell support:

[edit] Basic concepts and features

[edit] Object types

Synchronization affects the following types of objects:

Synced object types
AD object portal object
user User
group (security / distribution) Group
organizationalUnit Organizational Unit
Organization (only with eDir->portal sync) Organizational Unit
container AD Folder
domain Domain

[edit] Sync-trees

Mapping of objects is configured by the definition of so-called sync-trees. A sync-tree defines the root element of the tree of synchronized objects both on the portal and in the AD. This means that whole object trees can be easily synchronized by simply defining the root element of the tree and the mapping of this root element to the portal / to the AD. Every object under the sync-tree root is mapped with respect to the mapping of the root objects. In order to customize which objects should be synchronized under in a sync-tree exceptions can be configured. See detailed explanation in the configuration section.

[edit] Servers and Domains

Different sync-trees may be defined on different servers and under different domains. This means that it is possible to sync objects from different domain controllers to the portal and to different domain controllers from the portal. Please note that the current implementation handles separate domains with the following restrictions:

  • Moving of objects between domains hosted by different servers is not supported
  • Cross-reference of objects between domains hosted by different servers is not supported
  • Child domains hosted by separate servers must be synced to portal as if they were in no relation (should not be placed under each other)

[edit] Guid and last sync date

The synchronization of objects is based on the objects' objectGuid property in AD (the corresponding property of portal objects is called syncGuid). This means that whenever an object is updated the corresponding object to be updated is found by searching for the object having the same guid:

  • When updating an AD object the corresponding portal object with the same guid is searched under /Root/IMS
  • When updating a portal object the corresponding AD object with the same guid is searched in all of the sync-trees

When a new object is created the objectGuid property of the AD object is copied into the syncGuid property of the portal object. In the portal->AD direction the creation of a portal object triggers a creation of an AD object: the created AD object's objectGuid is copied back to the portal object's syncGuid.

The portal objects that are synchronized contain another property: lastSync. This date property shows the time of the last synchronization. This date is primarily used in AD->portal user and group synchronization: by default only those users'/groups' properties are synced that have been modified since the last synchronization. Note that moving objects in AD is always updated on the portal regardless of this property. Also note that moving objects on the portal will not update this property in the current implementation.

[edit] User synchronization

Syncing of users includes the following:

  • creating new users
  • updating user property changes
  • renaming and moving users within AD server and sync-tree bounds
  • deleting users

Notes:

  • The different user properties in AD and on the portal can be mapped onto each other using the global AD sync configuration file.
  • By default portal user property Name and AD user properties Name and sAMAccountName are mapped to each other:
    • renaming a portal user will cause the corresponding AD object's Name and sAMAccountName properties to be set to the portal user's Name property
    • renaming an AD user will cause the corresponding portal user's Name property to be set to the AD user's sAMAccountName property
    • the default sAMAccountName can be changed by defining a property mapping with Name PortalProperty and a custom AD property instead of sAMAccountName as AdProperty
  • User properties in AD->portal direction are only updated when the AD object's whenchanged property exceeds the portal object's lastSync property - except when the AlwaysSyncObjects global configuration switch is set to true
  • Multi-valued AD properties are handled as single-valued: if not empty the first item will be treated as the value of the property (eg. even if you give 2 other telephone numbers (otherPhone) only the first one will be synced to portal). In case you need to sync more properties of the same type create another property in the AD scheme (eg. secondaryPhone) and define a property mapping in the configuration.
  • User deletions are never synchronized as physically deleting the user on the other server. For example if you delete a user on the portal the corresponding user in AD is not deleted but set to disabled and moved to a special folder instead that can be defined in the configuration - the same applies to the other direction. Note that there might be special contstraints defined either on the portal or in an AD that ensures that two object never has the same property value for a configured property. In order to avoid the collision of properties of previously disabled and newly created users marked properties of a disabled user are prefixed with the date of deletion. Definition of these properties can also be set in the property mapping configuration.

[edit] Group synchronization

Syncing of groups includes the following:

  • creating new groups
  • updating group membership changes
  • renaming and moving groups within AD server and sync-tree bounds
  • deleting groups

Notes:

  • Group membership changes in AD->portal direction are only synced when the AD object's whenchanged property exceeds the portal object's lastSync property - except when the AlwaysSyncObjects global configuration switch is set to true

[edit] Folder (Container/AD Folder/Organizational Unit) synchronization

Syncing of folders includes the following:

  • creating new folders
  • renaming and moving folders within AD server and sync-tree bounds
  • deleting folders

Notes:

  • Moving a folder to another location causes all of its children to be moved as well.
  • Deleting a folder causes all of its child folders and groups to be deleted as well. Child users will be disabled and moved to a special trash folder that can be defined in the configuration (see configuration for details).
  • If deleting/moving of child objects fails the folder is not deleted

[edit] Configuration

The settings of AD sync can be found under 

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

The configuration xml can be divided into 3 main parts:

  • General settings (<General>)
  • Forms authentication from AD settings (<FormsAuthenticationFromAD>)
  • Sync-tree definitions (<SyncTrees>)
  • User property mapping definitions (<PropertyMappings>)

[edit] General settings

The following settings can be customized under the <General> settings node:

  • 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.
  • 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.
  • PortalNameMaxLength: the created portal user's name's length will not exceed the value set here (if set to longer in AD it will be truncated in portal)
  • 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.
  • SaveFailedPassword: 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.
  • NovellSupport: set this property to true when using eDir->portal sync (optional).
  • CustomADAdminAccount: this property holds information about the user having sufficient rights to retrieve information from eDirectory when using eDir->portal sync (optional).

[edit] Forms authentication from AD definitions

To activate AD authentication and to enable AD users to log onto portal the addresses of AD servers and domains have to be defined under the <FormsAuthenticationFromAD> configuration node. An authentication setting (<AuthSetting>) consists of the following:

  • ADServer: AD server address
  • Domain: domain of users. Note that this property is only to determine if the user is to be authenticated against an AD (the actual domain of the user in AD might differ from the one given here)
  • virtualADUser: when this attribute is set to true AD users don't need to be synced to portal - when an AD user logs into the portal a special user is loaded and user properties are synced instantaneously.
  • CustomLoginProperty: when this attribute is set to true a custom AD property is used for authentication instead of login name (for example email). To set this custom property, define a new PropertyMapping in the property mapping section of the configuration with Name PortalProperty and the custom AD property as AdPoperty.

[edit] 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.
  • 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.
  • ADExceptions: objects under the AD path defined here will not be synchronized (separate exceptions should be defined in an ADException node)
  • PortalExceptions: objects under the portal path defined here will not be synchronized (separate exceptions should be defined in a PortalException node)

[edit] 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:
    • AD->portal: values of AD properties are concatenated with the separator in corresponding order and the resulting value is set to the single 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
    • 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

[edit] Example configuration xml 

<?xml version="1.0" encoding="utf-8"?>
<DirectoryServices>
	<General>
		<DeletedPortalObjectsPath>/Root/IMS/Deleted</DeletedPortalObjectsPath>
		<CreatedAdUsersDisabled>false</CreatedAdUsersDisabled>
		<ADNameMaxLength>20</ADNameMaxLength>
		<ADsAMAccountNameMaxLength>20</ADsAMAccountNameMaxLength>
		<PortalNameMaxLength>20</PortalNameMaxLength>
		<AlwaysSyncObjects>true</AlwaysSyncObjects>
		<SaveFailedPassword>false</SaveFailedPassword>
	</General>
	<FormsAuthenticationFromAD>
		<AuthSetting virtualADUser="false">
			<ADServer>192.168.0.75</ADServer>
			<Domain>NATIV</Domain>
		</AuthSetting>
	</FormsAuthenticationFromAD>
	<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>
			<ADExceptions>
				<ADException>OU=NotSyncedOrg,OU=MyOrg,DC=Nativ,DC=local</ADException>
			</ADExceptions>
			<PortalExceptions>
				<PortalException>/Root/IMS/NATIV/MyOrg/nosync</PortalException>
			</PortalExceptions>
		</SyncTree>
		<SyncTree>
			<AdPath>OU=OtherOrg,DC=MyCompany,DC=corp</AdPath>
			<PortalPath>/Root/IMS/MYCOMPANY/OtherOrg</PortalPath>
			<DomainIp>192.168.0.96</DomainIp>
			<DeletedADObjectsPath>OU=Deleted,OU=OtherOrg,DC=MyCompany,DC=corp</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>

[edit] Logging and Error Handling

Every initiated action is logged in the system. A daily logfile is created at 

/Root/System/SystemPlugins/Tools/DirectoryServices/Log

Both portal->AD and AD->portal actions are logged here in the same file. Should an error occur during an action the execution will not hang instead the error is logged and the execution proceeds to the next action. Every single action and error is timestamped. In case of portal->AD sync there is a possibility to redo/retry an unsuccessfully executed action, see details.

A typical log file may have a content similar to the following (the first part shows the end of an AD->portal sync, the second part shows the beginning of a portal->AD action): 

... 
 
2009.09.01. 10:42:37:       Deleting portal container (orgunit/domain/folder) (Portal object: /Root/IMS/NATIV/MyOrg/test)
2009.09.01. 10:42:49:  ------- Deleting portal containers (domains, orgunits, containers) (OU=TestOrg,DC=OtherDomain,DC=corp --> /Root/IMS/OTHERDOMAIN/TestOrg)
 
 
AD sync finished with
                0 warnings
                0 errors
 
========================================================
Log started: 2009.09.01. 11:12:47
========================================================
2009.09.01. 11:12:47:       Creating new AD user (Portal object: /Root/IMS/OTHERDOMAIN/TestOrg/)
2009.09.01. 11:13:21: ERROR - exception: Logon failure: unknown user name or bad password.
 
...
Retrieved from "http://wiki.sensenet.com/index.php?title=Active_Directory_synchronization"
Personal tools