Overview of directory synchronization

If you are already using Active Directory (AD) in your on-premises environment, you’ve  probably invested a lot of time creating user accounts, populating their attributes, and adding them to the appropriate groups. Directory synchronization takes all that information, users, groups, contacts, email addresses, phone numbers and names and synchronizes it to Office 365 from your Ad. The synchronization is ongoing, which allows you to continue to manage users, groups, and contacts from your local AD. The synchronization is one way (from AD to Office 365) and at this time, once enabled, cannot be disabled.

Directory Synchronization is required if you want to use Active Directory Federation Services (ADFS). A couple other things to note however; Directory Synchronization cannot be used if you are going to do a cutover migration. Also, it’s recommended that if you’re going to use ADFS, that you enable it before enabling Directory Sync.


The requirements for the server that Directory Synchronization gets installed on are:

  • It must be a 32 bit Windows 2003 or 2008 Server
  • It must be a member of the domain, but can’t be installed on a domain controller
  • The server can’t have SQL or SQL Express already installed (for larger installations it is possible to use an existing SQL server)
  • An account that is a member of the Enterprise Administrators group

One good thing about directory sync is that it’s not really mission critical. If the server were to crash, the impact wouldn’t be that substantial. Updates from the local AD simply wouldn’t be replicated to Office 365 and you would just have to reinstall directory sync on another server, before being back in business.

Installation and configuration

The installation of directory sync is very straight forward. It’s pretty much a next, next, next install, during which you only have to choose the install path. The install process installs several components behind the scenes:

  • Microsoft Online directory synchronization, which is really just identity lifecycle manager 2007
  • Microsoft SQL Server 2008 R2
  • Microsoft Online services sign-in assistant

When the installation is complete, you’ll need to launch the configuration wizard to configure the synchronization. Again, not a lot of options, you must specify your Office 365 credentials, as well as your AD credentials, before choosing whether or you’ll be using rich coexistence. The rich coexistence option is only available if you have Exchange 2010.

Enabling rich coexistence also allows the Microsoft Online directory sync tool to write access to your local AD.

What is changed during the installation?

We’ve already talked about the various applications that are installed during the initial configuration, but there are a couple other things going on during the install.

First, an account named MSOL_AD_Sync is created in the user’s OU in the AD. This is the account that dir sync uses to interact with the AD. The enterprise admin credentials specified during the configuration are not used on an ongoing basis. If you selected the rich coexistence option, there is a group created; MS_AD_Sync_RichCoexistence.

The following permissions are also granted:

The MSOL_AD_Sync User account has the following permissions granted:

  • Replicate directory changes
  • Replication synchronization
  • Replicating directory changes all

 MS_AD_Sync_RichCoexistence has the following permissions granted:

  • Write msExchangeSafeRecipientsHash on user objects
  • Write msExchangeBlockedSendersHash on user’s objects
  • Write msExchUCVoiceMailSettings on user’s objects
  • Write msExchArchiveStatus on user’s objects
  • Write msExchSafeSendersHash on user’s objects
  • Write ProxyAddresses on user, contact, and group objects

Lifting on the hood on directory sync

This portion of the document should be used with extreme caution, as it’s all unsupported. Much like lifting the hood on your car, you probably don’t want to start taking things apart or changing things, unless you know what you are doing. It’s typically OK to look around and can be useful for troubleshooting.

If you are like the MessageOps team, you probably want to know more about what directory synchronization is doing behind the scenes. It’s such as basic install, and there isn’t much documentation about how it all works. The key thing to realize is that directory synchronization is really just Microsoft Identity Lifecycle Manager 2007. You can launch the configuration interface by running:

C:\Program Files\Microsoft Online Directory Sync\SYNCBUS\UIShell\miisclient.exe


Upon launching the MIIS Client you will see the Operations Area. The Microsoft Online Directory Synchronization uses 2 Management agents. The SourceAD management agent reads the information from the source AD. The TargetWebService management agent writes the information to the Microsoft Online Directory. The operations area will allow you see a log of what the management agents have done.

In this example, we’ll take a look at the initial synchronization, which is located at the bottom of the history and has a profile name of full import full sync. Once selected, in the lower left pane of the window you’ll see synchronization statistics, which allow you to see what objects have been synchronized, as well as which objects have been filtered out, and therefore won’t be synchronized to the metaverse and Microsoft Online.

identity manager operations screenshot

Source AD management agent


In the image above there are 193 Adds. This appears to be all the objects read from the AD. Not all of these objects will be replicated to Microsoft Online as filters (explained later) will prevent them from synchronizing. Clicking on the adds will allow you to see what objects have been read as shown below.

object details screenshot


The projections show which objects have been written to the metaverse. In the example above you’ll see that of the 193 objects read, only 14 are written to the metaverse. Just because an object is written to the metaverse doesn’t mean it will be written to Microsoft Online, as the TargetWebService also has filter rules when synchronizing from the Metaverse to Microsoft Online. Again, you can click on projections to see what objects have been written to the metaverse.

Filtered disconnectors

Filtered disconnectors show the objects what are not synchronized, due to the objects matching a defined filter rule. Filter rules will be explained in more detail later. You can click on filtered disconnectors to see which objects were filtered.

objects retrieved screenshot

In the example above, you’ll notice the guest account is selected. If you click on properties button, you’ll see the attributes for the guest account.

connector properties screenshot

You can then click the preview button followed by generate preview, to see why the object was filtered. After the preview has been generated, click the connector filter to see what filter matched the selected object. In this case you’ll see that the guest account matched the is CriticalSystemObject filter, and therefore won’t be synchronized.

preview screenshot


The TargetWebService is the agent that reads information from the metaverse and writes information to Microsoft Online. You’ll notice in the Agent Operations log that the TargetWebService performs two operations on each run, an import and an export.

identity manager operations screenshot

Clicking on the profile name export and then clicking adds, shows what has been synchronized to Microsoft Online. In this case, 7 objects were synchronized to Microsoft Online. This screenshot is from the same session as earlier, in which 14 objects were written to the metaverse, but as you see above, only 7 were synchronized to Microsoft Online.

The reason is that the objects did not have a display name specified. When you click adds, you’ll notice that the objects GUIDs are listed instead of names, but you can click on the GUID to display the objects properties. Upon completion of the export, the following event is written to the application event log which indicates that synchronization the is complete.

event properties screenshot

Management agents

As mentioned earlier in the document, the Microsoft Online directory synchronization uses 2 management agents. The SourceAD management agent reads the information from the source AD. The TargetWebService management agent writes the information to the Microsoft Online Directory. We’ll now dig into those agents a bit more.

SourceAD management agent

Opening the properties of the SourceAD Management Agent reveals several details about what is synchronized by the agent.

Connect to AD Forest

In the connect to AD Forest area, you will notice that the account used by the Directory Sync is the MSOL_AD_Sync account which is created when you first configure directory synchronization. So, although directory sync requires you enter enterprise admin credentials during the initial setup, the agent is using the MSOL_AD_Sync to read from the AD.

Configure directory partitions

The configure directory partitions has several options which could be modified. Again, it cannot be stressed enough that any modifications are in no way supported and could cause major problems if done incorrectly.

In the select directory partitions area, all of the domains in your forest will appear and be selected by default. If you wanted to only synchronize a single domain in the forest, you could deselect the other domains. Use caution when deselecting domains, as objects previously synchronized from those domains will be removed from Microsoft Online, and will not be recoverable.

configure directory screenshot

You can specify which domain controllers should be used by the management agent in the domain controller connection settings.

In the select containers for this partition area, you can click the containers button to select which OUs are synchronized. When prompted for credentials, just enter your administrator account credentials. By default, all OUs are selected. If you choose to deselect any OUs, be aware that objects located in those OUs that were previously synchronized to Microsoft Online will be deleted and will not be recoverable.

select containers screenshot

Select object types and select attributes

The object types and select attributes areas define which types of objects and attributes are synchronized. Deselecting object types will prevent them from synchronizing to Microsoft Online. If you deselect a specific object class, it will also make other configuration changes to the SourceAD agent, making a roll back very difficult. Although none of these changes are supported or recommended by Microsoft, if you change the object types it’s likely you’d have to do a complete reinstall to get the original settings back.

properties screenshot

The select attributes shows the attributes that will be synchronized. More information on which attributes are synchronized can be found later in the article.

properties 2 screenshot

Configure connector filter

In the configure connector filter settings, you will find the logic that is used to determine which objects are synchronized to Microsoft Online. The rules for synchronizing users and inetOrgPerson objects are visible in the GUI. If an object matches any of the criteria, it is not synchronized.

So, you can see that if an object does not have the SamAccountName populated, it will not be synchronized. There is an additional attribute which must be present for an object to synchronize, DisplayName. If DisplayName isn’t populated, the user object will be synchronized to the metaverse, but not to Microsoft Online.

Using this information, you could develop a way to exclude certain user objects from the directory sync. One such way would be to change the mailNickName of the objects you want to exclude to SystemMailbox (some unique value such as SamAccountname). If you are currently using Exchange, you can’t just change the mailNickName attribute, without making other modifications to the user object, so please contact MessageOps for guidance if you want to make the change and a script that will automate the process.

Another option would be to add a new filter rule. You would simply have to select an attribute which is not currently used in your environment, such as iPhone and specify a value that would define not to sync the object, such as DoNotSync. In this case, the filter would look like:

filter screenshot

Any user object that has DoNotSync in the iPhone field would not be synchronized to Microsoft Online. Be extremely careful, however, when creating filters, because if a previously synchronized account matches the filter, it will be deleted within Microsoft Online and the user’s mail will be gone. Since none of these changes are supported, you will be on your own if you make them.

The rules to synchronize contacts and groups are not visible in the GUI. They are controlled by a rules extension DLL. Although MessageOps does not know exactly what the DLL does, it appears to do the following.

If the group has the mail or proxyAddresses attribute populated, along with the DisplayName, it will synchronize to Office 365 as a distribution group. Security groups do not require that the DisplayName be populated, unless they also have the mail or proxyAddresses populated.

Contact objects appear to just require the DisplayName and Mail or ProxyAddresses populated for them to sync to Office 365.

Configurate join and projection rules

It is very unlikely that you would want to change any settings in the configure join and project rules are. If you did, it would probably cause Dir Sync to stop working. In this area you see that the ObjectGuid of the objects is used as the anchor attribute. The anchor attribute acts as a unique identifier for an object in the SourceAD agent’s connector space.

Configure attribute flow

The configure attribute flow area controls what attributes are synchronized from the AD to the metaverse. For more information about what attributes are synchronized, see the “What Attributes are Synchronized” section of this article.

Target webservice agent

The TargetWebService agent is responsible for replicating information from the metaverse to Microsoft Online. When looking at the agent configuration options, there aren’t many settings that appear to be easily configurable. Many of the other options are similar to those found on the SourceAD Agent, and therefore won’t be discussed further.

As mentioned earlier, it appears that the target agent is responsible for not synchronizing objects that do not have a display name. The SourceAD agent places objects without DisplayNames in the metaverse, but the TargetWebService does not synchronize them to Microsoft Online.

Metaverse search

The Metaverse Search area will allow you see the objects, and their attributes, that have been synchronized to the Metaverse. To see the objects, simply click search.

maleware search screenshot

The search results will show all objects in the metaverse. In the image above you’ll notice that 14 objects are in the metaverse and displayName is only column displayed. You can click on the column settings link to display additional attributes. You can also limit the search by changing the scope by object type drop down list or clicking the add clause action to filter by attribute.

The metaverse search area could be useful if you are trying to determine why certain objects aren’t synchronizing to Microsoft Online.


The Joiner will allow you to see the objects which have not been synchronized. Selecting the management agent SourceAD and disconnector type disconnectors, and then clicking search will display all the disconnectors.

joiner screenshot

In the image above, notice the objectType column. You’ll see that these objects are all DomainDNS, organizationUnites, or containers. If you look at the SourceAD management agent’s join and projection rules, you’ll notice that these types of objects are not joined or projected to the metaverse.

configure join and projection rules screenshot

Changing the search options by selecting the management agent SourceAD and disconnector type filtered disconnectors, and then clicking search will display all the filtered disconnectors.

joiner 2 screenshot

Clicking on administrator in the example above will display the attributes associated with that user.

import screenshot

If you want to see why this user was filtered, click the preview button, then click the generate preview button. You’ll notice the filter that matched is that isCriticalSystemObjects is set to true on the object, so it is not synchronized.

preview 2 screenshot

Controlling the frequency of directory synchronization

By default, the directory synchronization runs every three hours. If you want to increase or decrease the frequency, you will need to modify the following file:

C:\program files\Microsoft Online Directory Sync\Microsoft.Online.DirSync.Scheduler.exe.Config

Just open with notepad, and you’ll see a line that looks like:

<add key=”SyncTimeInterval” value=”3:0:0″ />

By default, the SyncTimeInterval is set to three hours. If you wanted it to run every 30 minutes, you’d change the value to “0:30:0”. We wouldn’t recommend going any lower than 15-30 minutes.

Have a question or need help? The experts at MessageOps are ready to assist you. Contact us today to learn more or see if you qualify for free implementation or migration assistance.

Was this article helpful?