Understanding the default configuration

Updated: July 22, 2015

Important

This topic will be archived soon.
There is a new product called “Azure Active Directory Connect” that replaces AADSync and DirSync.
Azure AD Connect incorporates the components and functionality previously released as Dirsync and AAD Sync.
At some point in the future, support for Dirsync and AAD Sync will end.
These tools are no longer being updated individually with feature improvements, and all future improvements will be included in updates to Azure AD Connect.

For the most recent information about Azure Active Directory Connect, see Integrating your on-premises identities with Azure Active Directory

This document walks you through a default configuration of Azure Active Directory Sync. The goal is that the reader will understand how the configuration model, named declarative provisioning, in Azure Active Directory Sync is working in a real-world example. This document assumes that you have already installed and configure Azure Active Directory Sync using the installation wizard.

Scenario description

In this example we are using a deployment with one account forest (A), one resource forest (R), and one AAD directory.

Each connected directory has a cached copy, called the connector space, of the relevant information in Azure Active Directory Sync. In the middle we have the metaverse, the consolidated view of the objects being synchronized.

This is the same as scenario 2 described in Azure Active Directory Sync scenario overview.

Synchronization Rule Editor

The configuration and be viewed and changed with the tool Synchronization Rules Editor (SRE) and a shortcut to it can be found in the start menu.

The SRE is a resource kit tool but it is installed with Azure Active Directory Sync. To be able to start it you must be a member of the ADSyncAdmins group. When it starts, you will see something like this:

In this pane you will see all Synchronization Rules created for your configuration. Each line in the table is one Synchronization Rule. To the left under Rule Types the two different types are listed: Inbound and Outbound. Inbound and Outbound is from the view of the metaverse. We will mainly focus on the inbound rules in this overview.The actual list of Synchronization Rules will depend on the detected schema in AD. In the picture above the account forest (Azure Active Directory Sync.com) does not have any services, such as Exchange and Lync, and no Synchronization Rules have been created for these services. However, in the resource forest we will find Synchronization Rules for these services. The content of the rules will be different depending on the version detected. For example in a deployment with Exchange 2013 we will have more attribute flows configured than in Exchange 2010 and Exchange 2007.

Synchronization Rule

A Synchronization Rule is a configuration object with a set of attributes flowing when a condition is satisfied. It is also used to describe how an object in a connector space is related to an object in the metaverse, known as join or match. The Synchronization Rules have a precedence indicating how they relate to each other. A Synchronization Rule with a lower numeric value in precedence has a higher precedence and in case of an attribute flow conflict, higher precedence will win the conflict resolution.

As an example we will look at the Synchronization Rule “In from AD – User AccountEnabled”. We will mark this line in the SRE and select Edit.A Synchronization Rule has four configuration sections: Description, Scoping filter, Join rules, and Transformations.

Description

The first section provides basic information such as a name and description.

We also find information about which connected system this rule is related to, which object type in the connected system it applies to, and the metaverse object type. The metaverse object type is always person regardless if the source object type is a user, iNetOrgPerson, or contact. The metaverse object type should never change so it is created as a generic type. The Link Type can be set to Join, StickyJoin, or Provision. This setting works together with the Join Rules section and we will cover this later.

Scoping Filter

The Scoping Filter section is used to configure when a Synchronization Rule should apply. Since the name of the Synchronization Rule we are looking at indicates it should only be applied for enabled users, the scope is configured so the AD attribute userAccountControl must not have the bit 2 set. When we find a user in AD we will apply this rule if userAccountControl is set to the decimal value 512 (enabled normal user) but it will not apply if the user we find has userAccountControl set to 514 (disabled normal user).

The scoping filter has Groups and Clauses which can be nested. All clauses inside a group must be satisfied for a Synchronization Rule to apply. When multiple groups are defined then at least one group must be satisfied for the rule to apply. I.e. a logical OR is evaluated between groups and a logical AND is evaluated inside a group. An example of this can be found in the outbound Synchronization Rule Out to AAD – Group Join, shown below. There are two synchronization filter groups, one for security groups (securityEnabled EQUAL True) and one for distribution groups (securityEnabled EQUAL False).

This rule is used to define which Groups should be provisioned to AAD. Distribution Groups must be mail enabled to be synchronized with AAD, but for security groups this is not required. As you can also see, a lot of additional attributes are evaluated as well.

Join Rules

The third section is used to configure how objects in the connector space relate to objects in the metaverse. The rule we have looked at earlier does not have any configuration for Join Rules, so instead we are going to look at In from AD – User Join.

The content of the join rules will depend on the matching option selected in the installation wizard. For an inbound rule the evaluation starts with an object in the source connector space and each group in join rules is evaluated in sequence. If a source object is evaluated to match exactly one object in the metaverse using one of the join rules, the objects are joined together. If all rules have been evaluated and there is no match, then the Link Type on the description page is used. If this setting is set to Provision then a new object is created in the target, the metaverse. To provision a new object to the metaverse is also known as to project an object to the metaverse. The join rules are only evaluated once. When a connector space object and a metaverse object are joined together, they will remain joined as long as the scope of the Synchronization Rule is still satisfied. When evaluating Synchronization Rules only one Synchronization Rule with join rules defined must be in scope. If multiple Synchronization Rules with join rules are found for one object, an error is thrown. For this reason the best practice is to have only one Synchronization Rule with join defined when multiple Synchronization Rules are in scope for an object. In the out-of-box configuration for Azure Active Directory Sync these rules can be found by looking at the name and find those with the word Join at the end of the name. A Synchronization Rule without any join rules defined will apply the attribute flows if another Synchronization Rule joined the objects together or provisioned a new object in the target.

Transformations

The transformation section defines all attribute flows which will apply to the target object when the objects are joined and the scope filter is satisfied. Going back to our In from AD – User AccountEnabled Synchronization Rule we will find the following transformations:

To put this in context, in an Account-Resource forest deployment we expect to find an enabled account in the account forest and a disabled account in the resource forest with Exchange and Lync settings. The Synchronization Rule we are looking at contains the attributes required for login and we want these to flow from the forest where we found an enabled account. All these attribute flows are put together in one Synchronization Rule.A transformation can have different types: Constant, Direct, and Expression. A constant flow will always flow a particular value, in the case above we will always set the value True in the metaverse attribute named accountEnabled. A Direct flow will flow the value of the attribute in the source to the target attribute. The third flow type is Expression and it allows for more advanced configurations. The expression language is VBA (Visual Basic for Applications) so user with experience of Microsoft Office or VBScript will recognize the format. Attributes are enclosed in square brackets, [attributeName]. Attribute names and function names are case sensitive, but the Synchronization Rules Editor will evaluate the expressions and provide a warning if the expression is not valid.All expressions are expressed on a single line with nested functions. To show the power of the configuration language, here is the flow for pwdLastSet, but with additional comments inserted:

// If-then-else
IIF(
// (The evaluation for IIF) Is the attribute pwdLastSet present in AD? 
IsPresent([pwdLastSet]),
// (The True part of IIF) If it is, then from right to left, convert the AD time format to a .Net datetime, change it to the time format used by AAD, and finally convert it to a string.
CStr(FormatDateTime(DateFromNum([pwdLastSet]),"yyyyMMddHHmmss.0Z")),
// (The False part of IIF) Nothing to contribute
NULL
)

The topic of transformation is large and it provides a large portion of the custom configuration possible with Azure Active Directory Sync. Custom configuration will not be covered in this overview document but we will look at some additional attribute flows later in this document.

Precedence

We have now looked at some individual Synchronization Rules, but the rules work together in the configuration. In some cases an attribute value is contributed from multiple synchronization rules to the same target attribute. In this case attribute precedence is used to determine which attribute will win. As an example, let us look at the attribute sourceAnchor. This attribute is an important attribute to be able to login to Azure AD. We can find an attribute flow for this attribute in two different Synchronization Rules, In from AD – User AccountEnabled and In from AD – User Common. Due to Synchronization Rule precedence, the sourceAnchor attribute will be contributed from the forest with an enabled account first if there are several objects joined to the metaverse object. If there are no enabled accounts, then we will use the catch-all Synchronization Rule In from AD – User Common. This will ensure that even for accounts which are disabled we will still provide a sourceAnchor.The precedence for Synchronization Rules is set in groups by the installation wizard. A group of rules all have the same name, but they are connected to different connected directories. The installation wizard will give the rule In from AD – User Join highest precedence and iterate over all connected AD directories. It will then continue with the next groups of rules in a predefined order. Inside a group the rules are added in the order the Connectors where added in the wizard. If another Connector is added through the wizard, the Synchronization Rules will be reordered and the new Connector’s rules will be inserted last in each group.

Putting it all together

We now know enough about Synchronization Rules to be able to understand how the configuration works with the different Synchronization Rules. If we look at a user and the attributes which are contributed to the metaverse, the rules are applied in the following order:

Name	Comment
In from AD – User Join	Rule for joining connector space objects with metaverse.
In from AD – UserAccount Enabled	Attributes required for login to Azure AD and Office 365. We want these attributes from the enabled account.
In from AD – User Common from Exchange	Attributes found in the Global Address List. We assume the data quality is best in the forest where we have found the user’s mailbox.
In from AD – User Common	Attributes found in the Global Address List. In case we didn’t find a mailbox, any other joined object can contribute the attribute value.
In from AD – User Exchange	Will only exist if Exchange has been detected. Will flow all infrastructure Exchange attributes.
In from AD – User Lync	Will only exist if Lync has been detected. Will flow all infrastructure Lync attributes.

Other things to note

We will finish this document by looking at one particular attribute flow.

cloudFiltered

This attribute flow can be found in the In from AD – Join User. Even though it is not needed for joining, it is put in this rule since it is core. All outbound Synchronization Rules have a scope filter on the cloudFiltered attribute and we will see how to use this for additional filtering in a different document. This flow will by default filter out a number of objects which will not appear in the cloud. The double vertical bar || in the expression below is a logical OR.

// if-then-else
IIF(
// Don’t synchronize default AD objects, such as Administrator
IsPresent([isCriticalSystemObject]) || 
// Don’t synchronize objects with no sAMAccountName set
IsPresent([sAMAccountName]) = False || 
// Don’t synchronize these special Exchange mailboxes
[sAMAccountName] = "SUPPORT_388945a0" || 
Left([mailNickname], 14) = "SystemMailbox{" || 
(Left([mailNickname], 4) = "CAS_" && (InStr([mailNickname], "}") > 0)) || 
(Left([sAMAccountName], 4) = "CAS_" && (InStr([sAMAccountName], "}") > 0)) ||  
// Don’t synchronize Exchange system mailboxes
CBool(IIF(IsPresent([msExchRecipientTypeDetails]), 
BitAnd([msExchRecipientTypeDetails],&H21C07000) > 0,NULL)) ||
// Don’t synchronize the Azure Active Directory Sync/DirSync service accounts
Left([sAMAccountName], 4) = "AAD_" || Left([sAMAccountName], 5) = "MSOL_" ||
// Don’t synchronize replication conflict objects
CBool(InStr(DNComponent(CRef([dn]),1),"\\0ACNF:")>0), 
// Then, If any of these OR clauses is True, then flow “True”
True, 
// Else, if not, then don’t flow anything
NULL
)

See Also

Concepts

Azure Active Directory Sync