You are on page 1of 520

Table of Contents

Overview
What is Azure AD Connect?
What is Azure AD Connect Sync?
Users and contacts
Architecture
Declarative Provisioning
Default configuration
What is Azure AD Connect and Federation?
Get started
Prerequisites
Install Azure AD Connect
Express settings
Custom settings
Upgrade from DirSync
Upgrade from a previous version
Install using an existing ADSync database
Install using SQL delegated administrator permissions
How to
Plan and design
Design concepts
Topologies for Azure AD Connect
Active Directory Federation Services in Azure
Special considerations for instances
When you already have Azure AD
Manage Azure AD Connect
Renew certs for O365 and Azure AD
Update the SSL certificate for an Active Directory Federation Services (AD FS) farm
Enable device writeback
User sign-on options
Multiple domain support for federating
Automatic upgrade
Use a SAML 2.0 Identity Provider (IdP) for Single Sign On
Manage Azure AD Connect Sync
GDPR compliance and Azure AD Connect
Prevent accidental deletes
Password synchronization
Azure AD service account
Installation wizard
How UserPrincipalName is populated
Change the default configuration
Configure Filtering
Scheduler
Directory extensions
Changing the Azure AD Sync service account password
Changing the AD DS account password
Enable AD recycle bin
Synchronization Service Manager
Manage Federation Services
Manage and customize
Federate multiple instances of Azure AD with single instance of AD FS
Troubleshoot
Connectivity
Errors during synchronization
Object is not synchronized
Object sync using the troubleshooting task
Password synchronization
LargeObject error caused by userCertificate
How to recover from LocalDB 10-GB limit
Reference
Code samples
Identity synchronization and duplicate attribute resiliency
Hybrid Identity Required Ports and Protocols
Features in preview
Version History
Accounts and permissions
Azure AD Connect Sync
Attributes synchronized to Azure Active Directory
Connector Version Release History
Functions Reference
Operational tasks and consideration
Azure AD federation compatibility list
Technical Concepts
Service features
Related
Monitor your on-premises identity infrastructure and synchronization services in the
cloud
Hybrid Identity Design Guide
Resources
Azure Roadmap
Azure AD Connect FAQ
DirSync Deprecation
Pricing calculator
Integrate your on-premises directories with
Azure Active Directory
1/3/2018 • 7 min to read • Edit Online

Azure AD Connect will integrate your on-premises directories with Azure Active Directory. This allows you
to provide a common identity for your users for Office 365, Azure, and SaaS applications integrated with
Azure AD. This topic will guide you through the planning, deployment, and operation steps. It is a
collection of links to the topics related to this area.

IMPORTANT
Azure AD Connect is the best way to connect your on-premises directory with Azure AD and Office 365. This is a
great time to upgrade to Azure AD Connect from Windows Azure Active Directory Sync (DirSync) or Azure AD Sync
as these tools are now deprecated are no longer supported as of April 13, 2017.

Why use Azure AD Connect


Integrating your on-premises directories with Azure AD makes your users more productive by providing a
common identity for accessing both cloud and on-premises resources. Users and organizations can take
advantage of the following:
Users can use a single identity to access on-premises applications and cloud services such as Office
365.
Single tool to provide an easy deployment experience for synchronization and sign-in.
Provides the newest capabilities for your scenarios. Azure AD Connect replaces older versions of
identity integration tools such as DirSync and Azure AD Sync. For more information, see Hybrid Identity
directory integration tools comparison.
How Azure AD Connect works
Azure Active Directory Connect is made up of three primary components: the synchronization services, the
optional Active Directory Federation Services component, and the monitoring component named Azure
AD Connect Health.

Synchronization - This component is responsible for creating users, groups, and other objects. It is also
responsible for making sure identity information for your on-premises users and groups is matching
the cloud.
AD FS - Federation is an optional part of Azure AD Connect and can be used to configure a hybrid
environment using an on-premises AD FS infrastructure. This can be used by organizations to address
complex deployments, such as domain join SSO, enforcement of AD sign-in policy, and smart card or
3rd party MFA.
Health Monitoring - Azure AD Connect Health can provide robust monitoring and provide a central
location in the Azure portal to view this activity. For additional information, see Azure Active Directory
Connect Health.

Install Azure AD Connect


You can find the download for Azure AD Connect on Microsoft Download Center.

SOLUTION SCENARIO

Before you start - Hardware and prerequisites Steps to complete before you start to install Azure AD
Connect.

Express settings If you have a single forest AD then this is the


recommended option to use.
User sign in with the same password using password
synchronization.

Customized settings Used when you have multiple forests. Supports many
on-premises topologies.
Customize your sign-in option, such as ADFS for
federation or use a 3rd party identity provider.
Customize synchronization features, such as filtering
and writeback.

Upgrade from DirSync Used when you have an existing DirSync server already
running.
SOLUTION SCENARIO

Upgrade from Azure AD Sync or Azure AD Connect There are several different methods depending on your
preference.

After installation you should verify it is working as expected and assign licenses to the users.
Next steps to Install Azure AD Connect
TOPIC LINK

Download Azure AD Connect Download Azure AD Connect

Install using Express settings Express installation of Azure AD Connect

Install using Customized settings Custom installation of Azure AD Connect

Upgrade from DirSync Upgrade from Azure AD sync tool (DirSync)

After installation Verify the installation and assign licenses

Learn more about Install Azure AD Connect


You also want to prepare for operational concerns. You might want to have a stand-by server so you easily
can fall over if there is a disaster. If you plan to make frequent configuration changes, you should plan for
a staging mode server.

TOPIC LINK

Supported topologies Topologies for Azure AD Connect

Design concepts Azure AD Connect design concepts

Accounts used for installation More about Azure AD Connect credentials and
permissions

Operational planning Azure AD Connect sync: Operational tasks and


considerations

User sign-in options Azure AD Connect User sign-in options

Configure sync features


Azure AD Connect comes with several features you can optionally turn on or are enabled by default. Some
features might sometimes require more configuration in certain scenarios and topologies.
Filtering is used when you want to limit which objects are synchronized to Azure AD. By default all users,
contacts, groups, and Windows 10 computers are synchronized. You can change the filtering based on
domains, OUs, or attributes.
Password synchronization synchronizes the password hash in Active Directory to Azure AD. The end-user
can use the same password on-premises and in the cloud but only manage it in one location. Since it uses
your on-premises Active Directory as the authority, you can also use your own password policy.
Password writeback will allow your users to change and reset their passwords in the cloud and have your
on-premises password policy applied.
Device writeback will allow a device registered in Azure AD to be written back to on-premises Active
Directory so it can be used for conditional access.
The prevent accidental deletes feature is turned on by default and protects your cloud directory from
numerous deletes at the same time. By default it allows 500 deletes per run. You can change this setting
depending on your organization size.
Automatic upgrade is enabled by default for express settings installations and ensures your Azure AD
Connect is always up to date with the latest release.
Next steps to configure sync features
TOPIC LINK

Configure filtering Azure AD Connect sync: Configure filtering

Password synchronization Azure AD Connect sync: Implement password


synchronization

Password writeback Getting started with password management

Device writeback Enabling device writeback in Azure AD Connect

Prevent accidental deletes Azure AD Connect sync: Prevent accidental deletes

Automatic upgrade Azure AD Connect: Automatic upgrade

Customize Azure AD Connect sync


Azure AD Connect sync comes with a default configuration that is intended to work for most customers
and topologies. But there are always situations where the default configuration does not work and must
be adjusted. It is supported to make changes as documented in this section and linked topics.
If you have not worked with a synchronization topology before you want to start to understand the basics
and the terms used as described in the technical concepts. Azure AD Connect is the evolution of MIIS2003,
ILM2007, and FIM2010. Even if some things are identical, a lot has changed as well.
The default configuration assumes there might be more than one forest in the configuration. In those
topologies a user object might be represented as a contact in another forest. The user might also have a
linked mailbox in another resource forest. The behavior of the default configuration is described in users
and contacts.
The configuration model in sync is called declarative provisioning. The advanced attribute flows are using
functions to express attribute transformations. You can see and examine the entire configuration using
tools which comes with Azure AD Connect. If you need to make configuration changes, make sure you
follow the best practices so it is easier to adopt new releases.
Next steps to customize Azure AD Connect sync
TOPIC LINK

All Azure AD Connect sync articles Azure AD Connect sync

Technical concepts Azure AD Connect sync: Technical Concepts


TOPIC LINK

Understanding the default configuration Azure AD Connect sync: Understanding the default
configuration

Understanding users and contacts Azure AD Connect sync: Understanding Users and
Contacts

Declarative provisioning Azure AD Connect Sync: Understanding Declarative


Provisioning Expressions

Change the default configuration Best practices for changing the default configuration

Configure federation features


Azure AD Connect provides several features that simplify federating with Azure AD using AD FS and
managing your federation trust. Azure AD Connect supports AD FS on Windows Server 2012R2 or later.
Update SSL certificate of AD FS farm even if you are not using Azure AD Connect to manage your
federation trust.
Add an AD FS server to your farm to expand the farm as required.
Repair the trust with Azure AD in a few simple clicks.
ADFS can be configured to support multiple domains. For example you might have multiple top domains
you need to use for federation.
if your ADFS server has not been configured to automatically update certificates from Azure AD or if you
use a non-ADFS solution, then you will be notified when you have to update certificates.
Next steps to configure federation features
TOPIC LINK

All AD FS articles Azure AD Connect and federation

Configure ADFS with subdomains Multiple Domain Support for Federating with Azure AD

Manage AD FS farm AD FS management and customization with Azure AD


Connect

Manually updating federation certificates Renewing Federation Certificates for Office 365 and
Azure AD

More information and references


TOPIC LINK

Version history Version history

Compare DirSync, Azure ADSync, and Azure AD Connect Directory integration tools comparison

Non-ADFS compatibility list for Azure AD Azure AD federation compatibility list


TOPIC LINK

Configuring a SAML 2.0 Idp Using a SAML 2.0 Identity Provider (IdP) for Single Sign
On

Attributes synchronized Attributes synchronized

Monitoring using Azure AD Connect Health Azure AD Connect Health

Frequently Asked Questions Azure AD Connect FAQ

Additional Resources
Ignite 2015 presentation on extending your on-premises directories to the cloud.
Azure AD Connect sync: Understand and
customize synchronization
1/26/2018 • 3 min to read • Edit Online

The Azure Active Directory Connect synchronization services (Azure AD Connect sync) is a main component of
Azure AD Connect. It takes care of all the operations that are related to synchronize identity data between your
on-premises environment and Azure AD. Azure AD Connect sync is the successor of DirSync, Azure AD Sync,
and Forefront Identity Manager with the Azure Active Directory Connector configured.
This topic is the home for Azure AD Connect sync (also called sync engine) and lists links to all other topics
related to it. For links to Azure AD Connect, see Integrating your on-premises identities with Azure Active
Directory.
The sync service consists of two components, the on-premises Azure AD Connect sync component and the
service side in Azure AD called Azure AD Connect sync service.

Azure AD Connect sync topics


TOPIC WHAT IT COVERS AND WHEN TO READ

Azure AD Connect sync fundamentals

Understanding the architecture For those of you who are new to the sync engine and want
to learn about the architecture and the terms used.

Technical concepts A short version of the architecture topic and briefly explains
the terms used.

Topologies for Azure AD Connect Describes the different topologies and scenarios the sync
engine supports.

Custom configuration

Running the installation wizard again Explains what options you have available when you run the
Azure AD Connect installation wizard again.

Understanding Declarative Provisioning Describes the configuration model called declarative


provisioning.

Understanding Declarative Provisioning Expressions Describes the syntax for the expression language used in
declarative provisioning.

Understanding the default configuration Describes the out-of-box rules and the default
configuration. Also describes how the rules work together
for the out-of-box scenarios to work.

Understanding Users and Contacts Continues on the previous topic and describes how the
configuration for users and contacts works together, in
particular in a multi-forest environment.
TOPIC WHAT IT COVERS AND WHEN TO READ

How to make a change to the default configuration Walks you through how to make a common configuration
change to attribute flows.

Best practices for changing the default configuration Support limitations and for making changes to the out-of-
box configuration.

Configure Filtering Describes the different options for how to limit which
objects are being synchronized to Azure AD and step-by-
step how to configure these options.

Features and scenarios

Prevent accidental deletes Describes the prevent accidental deletes feature and how
to configure it.

Scheduler Describes the built-in scheduler, which is importing,


synchronizing, and exporting data.

Implement password synchronization Describes how password synchronization works, how to


implement, and how to operate and troubleshoot.

Device writeback Describes how device writeback works in Azure AD Connect.

Directory extensions Describes how to extend the Azure AD schema with your
own custom attributes.

Office 365 PreferredDataLocation Describes how to put the user's Office 365 resources in the
same region as the user.

Sync Service

Azure AD Connect sync service features Describes the sync service side and how to change sync
settings in Azure AD.

Duplicate attribute resiliency Describes how to enable and use userPrincipalName and
proxyAddresses duplicate attribute values resiliency.

Operations and UI

Synchronization Service Manager Describes the Synchronization Service Manager UI, including
Operations, Connectors, Metaverse Designer, and
Metaverse Search tabs.

Operational tasks and considerations Describes operational concerns, such as disaster recovery.

How To...

Reset the Azure AD account How to reset the credentials of the service account used to
connect from Azure AD Connect sync to Azure AD.

More information and references


TOPIC WHAT IT COVERS AND WHEN TO READ

Ports Lists which ports you need to open between the sync
engine and your on-premises directories and Azure AD.

Attributes synchronized to Azure Active Directory Lists all attributes being synchronized between on-premises
AD and Azure AD.

Functions Reference Lists all functions available in declarative provisioning.

Additional Resources
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: Understanding Users,
Groups, and Contacts
1/17/2018 • 5 min to read • Edit Online

There are several different reasons why you would have multiple Active Directory forests and there are several
different deployment topologies. Common models include an account-resource deployment and GAL sync’ed
forests after a merger & acquisition. But even if there are pure models, hybrid models are common as well. The
default configuration in Azure AD Connect sync does not assume any particular model but depending on how user
matching was selected in the installation guide, different behaviors can be observed.
In this topic, we will go through how the default configuration behaves in certain topologies. We will go through
the configuration and the Synchronization Rules Editor can be used to look at the configuration.
There are a few general rules the configuration assumes:
Regardless of which order we import from the source Active Directories, the end result should always be the
same.
An active account will always contribute sign-in information, including userPrincipalName and
sourceAnchor.
A disabled account will contribute userPrincipalName and sourceAnchor, unless it is a linked mailbox, if there is
no active account to be found.
An account with a linked mailbox will never be used for userPrincipalName and sourceAnchor. It is assumed
that an active account will be found later.
A contact object might be provisioned to Azure AD as a contact or as a user. You don’t really know until all
source Active Directory forests have been processed.

Groups
Important points to be aware of when synchronizing groups from Active Directory to Azure AD:
Azure AD Connect excludes built-in security groups from directory synchronization.
Azure AD Connect does not support synchronizing Primary Group memberships to Azure AD.
Azure AD Connect does not support synchronizing Dynamic Distribution Group memberships to Azure AD.
To synchronize an Active Directory group to Azure AD as a mail-enabled group:
If the group's proxyAddress attribute is empty, its mail attribute must have a value
If the group's proxyAddress attribute is non-empty, it must contain at least one SMTP proxy address
value. Here are some examples:
An Active Directory group whose proxyAddress attribute has value
{"X500:/0=contoso.com/ou=users/cn=testgroup"} will not be mail-enabled in Azure AD. It
does not have an SMTP address.
An Active Directory group whose proxyAddress attribute has values
{"X500:/0=contoso.com/ou=users/cn=testgroup","SMTP:johndoe@contoso.com"} will be mail-
enabled in Azure AD.
An Active Directory group whose proxyAddress attribute has values
{"X500:/0=contoso.com/ou=users/cn=testgroup", "smtp:johndoe@contoso.com"} will also be
mail-enabled in Azure AD.

Contacts
Having contacts representing a user in a different forest is common after a merger & acquisition where a GALSync
solution is bridging two or more Exchange forests. The contact object is always joining from the connector space to
the metaverse using the mail attribute. If there is already a contact object or user object with the same mail
address, the objects are joined together. This is configured in the rule In from AD – Contact Join. There is also a
rule named In from AD – Contact Common with an attribute flow to the metaverse attribute sourceObjectType
with the constant Contact. This rule has very low precedence so if any user object is joined to the same metaverse
object, then the rule In from AD – User Common will contribute the value User to this attribute. With this rule,
this attribute will have the value Contact if no user has been joined and the value User if at least one user has been
found.
For provisioning an object to Azure AD, the outbound rule Out to AAD – Contact Join will create a contact object
if the metaverse attribute sourceObjectType is set to Contact. If this attribute is set to User, then the rule Out to
AAD – User Join will create a user object instead. It is possible that an object is promoted from Contact to User
when more source Active Directories are imported and synchronized.
For example, in a GALSync topology we will find contact objects for everyone in the second forest when we import
the first forest. This will stage new contact objects in the AAD Connector. When we later import and synchronize
the second forest, we will find the real users and join them to the existing metaverse objects. We will then delete
the contact object in AAD and create a new user object instead.
If you have a topology where users are represented as contacts, make sure you select to match users on the mail
attribute in the installation guide. If you select another option, then you will have an order-dependent
configuration. Contact objects will always join on the mail attribute, but user objects will only join on the mail
attribute if this option was selected in the installation guide. You could then end up with two different objects in the
metaverse with the same mail attribute if the contact object was imported before the user object. During export to
Azure AD, an error will be thrown. This behavior is by design and would indicate bad data or that the topology was
not correctly identified during the installation.

Disabled accounts
Disabled accounts are synchronized as well to Azure AD. Disabled accounts are common to represent resources in
Exchange, for example conference rooms. The exception is users with a linked mailbox; as previously mentioned,
these will never provision an account to Azure AD.
The assumption is that if a disabled user account is found, then we will not find another active account later and
the object is provisioned to Azure AD with the userPrincipalName and sourceAnchor found. In case another active
account will join to the same metaverse object, then its userPrincipalName and sourceAnchor will be used.

Changing sourceAnchor
When an object has been exported to Azure AD then it is not allowed to change the sourceAnchor anymore. When
the object has been exported the metaverse attribute cloudSourceAnchor is set with the sourceAnchor value
accepted by Azure AD. If sourceAnchor is changed and not match cloudSourceAnchor, the rule Out to AAD –
User Join will throw the error sourceAnchor attribute has changed. In this case, the configuration or data must
be corrected so the same sourceAnchor is present in the metaverse again before the object can be synchronized
again.

Additional Resources
Azure AD Connect Sync: Customizing Synchronization options
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: Understanding the
architecture
1/17/2018 • 21 min to read • Edit Online

This topic covers the basic architecture for Azure AD Connect sync. In many aspects, it is similar to its predecessors
MIIS 2003, ILM 2007, and FIM 2010. Azure AD Connect sync is the evolution of these technologies. If you are
familiar with any of these earlier technologies, the content of this topic will be familiar to you as well. If you are new
to synchronization, then this topic is for you. It is however not a requirement to know the details of this topic to be
successful in making customizations to Azure AD Connect sync (called sync engine in this topic).

Architecture
The sync engine creates an integrated view of objects that are stored in multiple connected data sources and
manages identity information in those data sources. This integrated view is determined by the identity information
retrieved from connected data sources and a set of rules that determine how to process this information.
Connected Data Sources and Connectors
The sync engine processes identity information from different data repositories, such as Active Directory or a SQL
Server database. Every data repository that organizes its data in a database-like format and that provides standard
data-access methods is a potential data source candidate for the sync engine. The data repositories that are
synchronized by sync engine are called connected data sources or connected directories (CD).
The sync engine encapsulates interaction with a connected data source within a module called a Connector. Each
type of connected data source has a specific Connector. The Connector translates a required operation into the
format that the connected data source understands.
Connectors make API calls to exchange identity information (both read and write) with a connected data source. It
is also possible to add a custom Connector using the extensible connectivity framework. The following illustration
shows how a Connector connects a connected data source to the sync engine.

Data can flow in either direction, but it cannot flow in both directions simultaneously. In other words, a Connector
can be configured to allow data to flow from the connected data source to sync engine or from sync engine to the
connected data source, but only one of those operations can occur at any one time for one object and attribute. The
direction can be different for different objects and for different attributes.
To configure a Connector, you specify the object types that you want to synchronize. Specifying the object types
defines the scope of objects that are included in the synchronization process. The next step is to select the attributes
to synchronize, which is known as an attribute inclusion list. These settings can be changed any time in response to
changes to your business rules. When you use the Azure AD Connect installation wizard, these settings are
configured for you.
To export objects to a connected data source, the attribute inclusion list must include at least the minimum
attributes required to create a specific object type in a connected data source. For example, the sAMAccountName
attribute must be included in the attribute inclusion list to export a user object to Active Directory because all user
objects in Active Directory must have a sAMAccountName attribute defined. Again, the installation wizard does
this configuration for you.
If the connected data source uses structural components, such as partitions or containers to organize objects, you
can limit the areas in the connected data source that are used for a given solution.
Internal structure of the sync engine namespace
The entire sync engine namespace consists of two namespaces that store the identity information. The two
namespaces are:
The connector space (CS)
The metaverse (MV)
The connector space is a staging area that contains representations of the designated objects from a connected
data source and the attributes specified in the attribute inclusion list. The sync engine uses the connector space to
determine what has changed in the connected data source and to stage incoming changes. The sync engine also
uses the connector space to stage outgoing changes for export to the connected data source. The sync engine
maintains a distinct connector space as a staging area for each Connector.
By using a staging area, the sync engine remains independent of the connected data sources and is not affected by
their availability and accessibility. As a result, you can process identity information at any time by using the data in
the staging area. The sync engine can request only the changes made inside the connected data source since the
last communication session terminated or push out only the changes to identity information that the connected
data source has not yet received, which reduces the network traffic between the sync engine and the connected
data source.
In addition, sync engine stores status information about all objects that it stages in the connector space. When new
data is received, sync engine always evaluates whether the data has already been synchronized.
The metaverse is a storage area that contains the aggregated identity information from multiple connected data
sources, providing a single global, integrated view of all combined objects. Metaverse objects are created based on
the identity information that is retrieved from the connected data sources and a set of rules that allow you to
customize the synchronization process.
The following illustration shows the connector space namespace and the metaverse namespace within the sync
engine.

Sync engine identity objects


The objects in the sync engine are representations of either objects in the connected data source or the integrated
view that sync engine has of those objects. Every sync engine object must have a globally unique identifier (GUID).
GUIDs provide data integrity and express relationships between objects.
Connector space objects
When sync engine communicates with a connected data source, it reads the identity information in the connected
data source and uses that information to create a representation of the identity object in the connector space. You
cannot create or delete these objects individually. However, you can manually delete all objects in a connector
space.
All objects in the connector space have two attributes:
A globally unique identifier (GUID)
A distinguished name (also known as DN)
If the connected data source assigns a unique attribute to the object, then objects in the connector space can also
have an anchor attribute. The anchor attribute uniquely identifies an object in the connected data source. The sync
engine uses the anchor to locate the corresponding representation of this object in the connected data source. Sync
engine assumes that the anchor of an object never changes over the lifetime of the object.
Many of the Connectors use a known unique identifier to generate an anchor automatically for each object when it
is imported. For example, the Active Directory Connector uses the objectGUID attribute for an anchor. For
connected data sources that do not provide a clearly defined unique identifier, you can specify anchor generation
as part of the Connector configuration.
In that case, the anchor is built from one or more unique attributes of an object type, neither of which changes, and
that uniquely identifies the object in the connector space (for example, an employee number or a user ID).
A connector space object can be one of the following:
A staging object
A placeholder
Staging Objects
A staging object represents an instance of the designated object types from the connected data source. In addition
to the GUID and the distinguished name, a staging object always has a value that indicates the object type.
Staging objects that have been imported always have a value for the anchor attribute. Staging objects that have
been newly provisioned by sync engine and are in the process of being created in the connected data source do not
have a value for the anchor attribute.
Staging objects also carry current values of business attributes, and operational information needed by sync engine
to perform the synchronization process. Operational information includes flags that indicate the type of updates
that are staged on the staging object. If a staging object has received new identity information from the connected
data source that has not yet been processed, the object is flagged as pending import. If a staging object has new
identity information that has not yet been exported to the connected data source, it is flagged as pending export.
A staging object can be an import object or an export object. The sync engine creates an import object by using
object information received from the connected data source. When sync engine receives information about the
existence of a new object that matches one of the object types selected in the Connector, it creates an import object
in the connector space as a representation of the object in the connected data source.
The following illustration shows an import object that represents an object in the connected data source.
The sync engine creates an export object by using object information in the metaverse. Export objects are exported
to the connected data source during the next communication session. From the perspective of the sync engine,
export objects do not exist in the connected data source yet. Therefore, the anchor attribute for an export object is
not available. After it receives the object from sync engine, the connected data source creates a unique value for the
anchor attribute of the object.
The following illustration shows how an export object is created by using identity information in the metaverse.

The sync engine confirms the export of the object by reimporting the object from the connected data source. Export
objects become import objects when sync engine receives them during the next import from that connected data
source.
Placeholders
The sync engine uses a flat namespace to store objects. However, some connected data sources such as Active
Directory use a hierarchical namespace. To transform information from a hierarchical namespace into a flat
namespace, sync engine uses placeholders to preserve the hierarchy.
Each placeholder represents a component (for example, an organizational unit) of an object's hierarchical name
that has not been imported into sync engine but is required to construct the hierarchical name. They fill gaps
created by references in the connected data source to objects that are not staging objects in the connector space.
The sync engine also uses placeholders to store referenced objects that have not yet been imported. For example, if
sync is configured to include the manager attribute for the Abbie Spencer object and the received value is an object
that has not been imported yet, such as CN=Lee Sperry,CN=Users,DC=fabrikam,DC=com, the manager
information is stored as placeholders in the connector space. If the manager object is later imported, the
placeholder object is overwritten by the staging object that represents the manager.
Metaverse objects
A metaverse object contains the aggregated view that sync engine has of the staging objects in the connector
space. Sync engine creates metaverse objects by using the information in import objects. Several connector space
objects can be linked to a single metaverse object, but a connector space object cannot be linked to more than one
metaverse object.
Metaverse objects cannot be manually created or deleted. The sync engine automatically deletes metaverse objects
that do not have a link to any connector space object in the connector space.
To map objects within a connected data source to a corresponding object type within the metaverse, sync engine
provides an extensible schema with a predefined set of object types and associated attributes. You can create new
object types and attributes for metaverse objects. Attributes can be single-valued or multivalued, and the attribute
types can be strings, references, numbers, and Boolean values.
Relationships between staging objects and metaverse objects
Within the sync engine namespace, the data flow is enabled by the link relationship between staging objects and
metaverse objects. A staging object that is linked to a metaverse object is called a joined object (or connector
object). A staging object that is not linked to a metaverse object is called a disjoined object (or disconnector
object). The terms joined and disjoined are preferred to not confuse with the Connectors responsible for importing
and exporting data from a connected directory.
Placeholders are never linked to a metaverse object
A joined object comprises a staging object and its linked relationship to a single metaverse object. Joined objects
are used to synchronize attribute values between a connector space object and a metaverse object.
When a staging object becomes a joined object during synchronization, attributes can flow between the staging
object and the metaverse object. Attribute flow is bidirectional and is configured by using import attribute rules
and export attribute rules.
A single connector space object can be linked to only one metaverse object. However, each metaverse object can be
linked to multiple connector space objects in the same or in different connector spaces, as shown in the following
illustration.

The linked relationship between the staging object and a metaverse object is persistent and can be removed only
by rules that you specify.
A disjoined object is a staging object that is not linked to any metaverse object. The attribute values of a disjoined
object are not processed any further within the metaverse. The attribute values of the corresponding object in the
connected data source are not updated by sync engine.
By using disjoined objects, you can store identity information in sync engine and process it later. Keeping a staging
object as a disjoined object in the connector space has many advantages. Because the system has already staged
the required information about this object, it is not necessary to create a representation of this object again during
the next import from the connected data source. This way, sync engine always has a complete snapshot of the
connected data source, even if there is no current connection to the connected data source. Disjoined objects can
be converted into joined objects, and vice versa, depending on the rules that you specify.
An import object is created as a disjoined object. An export object must be a joined object. The system logic
enforces this rule and deletes every export object that is not a joined object.

Sync engine identity management process


The identity management process controls how identity information is updated between different connected data
sources. Identity management occurs in three processes:
Import
Synchronization
Export
During the import process, sync engine evaluates the incoming identity information from a connected data source.
When changes are detected, it either creates new staging objects or updates existing staging objects in the
connector space for synchronization.
During the synchronization process, sync engine updates the metaverse to reflect changes that have occurred in
the connector space and updates the connector space to reflect changes that have occurred in the metaverse.
During the export process, sync engine pushes out changes that are staged on staging objects and that are flagged
as pending export.
The following illustration shows where each of the processes occurs as identity information flows from one
connected data source to another.

Import process
During the import process, sync engine evaluates updates to identity information. Sync engine compares the
identity information received from the connected data source with the identity information about a staging object
and determines whether the staging object requires updates. If it is necessary to update the staging object with
new data, the staging object is flagged as pending import.
By staging objects in the connector space before synchronization, sync engine can process only the identity
information that has changed. This process provides the following benefits:
Efficient synchronization. The amount of data processed during synchronization is minimized.
Efficient resynchronization. You can change how sync engine processes identity information without
reconnecting the sync engine to the data source.
Opportunity to preview synchronization. You can preview synchronization to verify that your assumptions
about the identity management process are correct.
For each object specified in the Connector, the sync engine first tries to locate a representation of the object in the
connector space of the Connector. Sync engine examines all staging objects in the connector space and tries to find
a corresponding staging object that has a matching anchor attribute. If no existing staging object has a matching
anchor attribute, sync engine tries to find a corresponding staging object with the same distinguished name.
When sync engine finds a staging object that matches by distinguished name but not by anchor, the following
special behavior occurs:
If the object located in the connector space has no anchor, then sync engine removes this object from the
connector space and marks the metaverse object it is linked to as retry provisioning on next
synchronization run. Then it creates the new import object.
If the object located in the connector space has an anchor, then sync engine assumes that this object has either
been renamed or deleted in the connected directory. It assigns a temporary, new distinguished name for the
connector space object so that it can stage the incoming object. The old object then becomes transient, waiting
for the Connector to import the rename or deletion to resolve the situation.
If sync engine locates a staging object that corresponds to the object specified in the Connector, it determines what
kind of changes to apply. For example, sync engine might rename or delete the object in the connected data source,
or it might only update the object’s attribute values.
Staging objects with updated data are marked as pending import. Different types of pending imports are available.
Depending on the result of the import process, a staging object in the connector space has one of the following
pending import types:
None. No changes to any of the attributes of the staging object are available. Sync engine does not flag this
type as pending import.
Add. The staging object is a new import object in the connector space. Sync engine flags this type as pending
import for additional processing in the metaverse.
Update. Sync engine finds a corresponding staging object in the connector space and flags this type as pending
import so that updates to the attributes can be processed in the metaverse. Updates include object renaming.
Delete. Sync engine finds a corresponding staging object in the connector space and flags this type as pending
import so that the joined object can be deleted.
Delete/Add. Sync engine finds a corresponding staging object in the connector space, but the object types do
not match. In this case, a delete-add modification is staged. A delete-add modification indicates to the sync
engine that a complete resynchronization of this object must occur because different sets of rules apply to this
object when the object type changes.
By setting the pending import status of a staging object, it is possible to reduce significantly the amount of data
processed during synchronization because doing so allows the system to process only those objects that have
updated data.
Synchronization process
Synchronization consists of two related processes:
Inbound synchronization, when the content of the metaverse is updated by using the data in the connector
space.
Outbound synchronization, when the content of the connector space is updated by using data in the metaverse.
By using the information staged in the connector space, the inbound synchronization process creates in the
metaverse the integrated view of the data that is stored in the connected data sources. Either all staging objects or
only those with a pending import information are aggregated, depending on how the rules are configured.
The outbound synchronization process updates export objects when metaverse objects change.
Inbound synchronization creates the integrated view in the metaverse of the identity information that is received
from the connected data sources. Sync engine can process identity information at any time by using the latest
identity information that it has from the connected data source.
Inbound synchronization
Inbound synchronization includes the following processes:
Provision (also called Projection if it is important to distinguish this process from outbound synchronization
provisioning). The Sync engine creates a new metaverse object based on a staging object and links them.
Provision is an object-level operation.
Join. The Sync engine links a staging object to an existing metaverse object. A join is an object-level operation.
Import attribute flow. Sync engine updates the attribute values, called attribute flow, of the object in the
metaverse. Import attribute flow is an attribute-level operation that requires a link between a staging object and
a metaverse object.
Provision is the only process that creates objects in the metaverse. Provision affects only import objects that are
disjoined objects. During provision, sync engine creates a metaverse object that corresponds to the object type of
the import object and establishes a link between both objects, thus creating a joined object.
The join process also establishes a link between import objects and a metaverse object. The difference between join
and provision is that the join process requires that the import object are linked to an existing metaverse object,
where the provision process creates a new metaverse object.
Sync engine tries to join an import object to a metaverse object by using criteria that is specified in the
Synchronization Rule configuration.
During the provision and join processes, sync engine links a disjoined object to a metaverse object, making them
joined. After these object-level operations are completed, sync engine can update the attribute values of the
associated metaverse object. This process is called import attribute flow.
Import attribute flow occurs on all import objects that carry new data and are linked to a metaverse object.
Outbound synchronization
Outbound synchronization updates export objects when a metaverse object change but is not deleted. The
objective of outbound synchronization is to evaluate whether changes to metaverse objects require updates to
staging objects in the connector spaces. In some cases, the changes can require that staging objects in all connector
spaces be updated. Staging objects that are changed are flagged as pending export, making them export objects.
These export objects are later pushed out to the connected data source during the export process.
Outbound synchronization has three processes:
Provisioning
Deprovisioning
Export attribute flow
Provisioning and deprovisioning are both object-level operations. Deprovisioning depends on provisioning
because only provisioning can initiate it. Deprovisioning is triggered when provisioning removes the link between
a metaverse object and an export object.
Provisioning is always triggered when changes are applied to objects in the metaverse. When changes are made to
metaverse objects, sync engine can perform any of the following tasks as part of the provisioning process:
Create joined objects, where a metaverse object is linked to a newly created export object.
Rename a joined object.
Disjoin links between a metaverse object and staging objects, creating a disjoined object.
If provisioning requires sync engine to create a new connector object, the staging object to which the metaverse
object is linked is always an export object, because the object does not yet exist in the connected data source.
If provisioning requires sync engine to disjoin a joined object, creating a disjoined object, deprovisioning is
triggered. The deprovisioning process deletes the object.
During deprovisioning, deleting an export object does not physically delete the object. The object is flagged as
deleted, which means that the delete operation is staged on the object.
Export attribute flow also occurs during the outbound synchronization process, similar to the way that import
attribute flow occurs during inbound synchronization. Export attribute flow occurs only between metaverse and
export objects that are joined.
Export process
During the export process, sync engine examines all export objects that are flagged as pending export in the
connector space, and then sends updates to the connected data source.
The sync engine can determine the success of an export but it cannot sufficiently determine that the identity
management process is complete. Objects in the connected data source can always be changed by other processes.
Because sync engine does not have a persistent connection to the connected data source, it is not sufficient to make
assumptions about the properties of an object in the connected data source based only on a successful export
notification.
For example, a process in the connected data source could change the object’s attributes back to their original
values (that is, the connected data source could overwrite the values immediately after the data is pushed out by
sync engine and successfully applied in the connected data source).
The sync engine stores export and import status information about each staging object. If values of the attributes
that are specified in the attribute inclusion list have changed since the last export, the storage of import and export
status enables sync engine to react appropriately. Sync engine uses the import process to confirm attribute values
that have been exported to the connected data source. A comparison between the imported and exported
information, as shown in the following illustration, enables sync engine to determine whether the export was
successful or if it needs to be repeated.

For example, if sync engine exports attribute C, which has a value of 5, to a connected data source, it stores C=5 in
its export status memory. Each additional export on this object results in an attempt to export C=5 to the connected
data source again because sync engine assumes that this value has not been persistently applied to the object (that
is, unless a different value was imported recently from the connected data source). The export memory is cleared
when C=5 is received during an import operation on the object.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect sync: Understanding Declarative
Provisioning
1/17/2018 • 10 min to read • Edit Online

This topic explains the configuration model in Azure AD Connect. The model is called Declarative Provisioning and
it allows you to make a configuration change with ease. Many things described in this topic are advanced and not
required for most customer scenarios.

Overview
Declarative provisioning is processing objects coming in from a source connected directory and determines how
the object and attributes should be transformed from a source to a target. An object is processed in a sync pipeline
and the pipeline is the same for inbound and outbound rules. An inbound rule is from a connector space to the
metaverse and an outbound rule is from the metaverse to a connector space.

The pipeline has several different modules. Each one is responsible for one concept in object synchronization.

Source, The source object


Scope, Finds all sync rules that are in scope
Join, Determines relationship between connector space and metaverse
Transform, Calculates how attributes should be transformed and flow
Precedence, Resolves conflicting attribute contributions
Target, The target object

Scope
The scope module is evaluating an object and determines the rules that are in scope and should be included in the
processing. Depending on the attributes values on the object, different sync rules are evaluated to be in scope. For
example, a disabled user with no Exchange mailbox does have different rules than an enabled user with a mailbox.

The scope is defined as groups and clauses. The clauses are inside a group. A logical AND is used between all
clauses in a group. For example, (department =IT AND country = Denmark). A logical OR is used between groups.

The scope in this picture should be read as (department = IT AND country = Denmark) OR (country=Sweden). If
either group 1 or group 2 is evaluated to true, then the rule is in scope.
The scope module supports the following operations.
OPERATION DESCRIPTION

EQUAL, NOTEQUAL A string compare that evaluates if value is equal to the value
in the attribute. For multi-valued attributes, see ISIN and
ISNOTIN.

LESSTHAN, LESSTHAN_OR_EQUAL A string compare that evaluates if value is less than of the
value in the attribute.

CONTAINS, NOTCONTAINS A string compare that evaluates if value can be found


somewhere inside value in the attribute.

STARTSWITH, NOTSTARTSWITH A string compare that evaluates if value is in the beginning of


the value in the attribute.

ENDSWITH, NOTENDSWITH A string compare that evaluates if value is in the end of the
value in the attribute.

GREATERTHAN, GREATERTHAN_OR_EQUAL A string compare that evaluates if value is greater than of the
value in the attribute.

ISNULL, ISNOTNULL Evaluates if the attribute is absent from the object. If the
attribute is not present and therefore null, then the rule is in
scope.

ISIN, ISNOTIN Evaluates if the value is present in the defined attribute. This
operation is the multi-valued variation of EQUAL and
NOTEQUAL. The attribute is supposed to be a multi-valued
attribute and if the value can be found in any of the attribute
values, then the rule is in scope.

ISBITSET, ISNOTBITSET Evaluates if a particular bit is set. For example, can be used to
evaluate the bits in userAccountControl to see if a user is
enabled or disabled.

ISMEMBEROF, ISNOTMEMBEROF The value should contain a DN to a group in the connector


space. If the object is a member of the group specified, the
rule is in scope.

Join
The join module in the sync pipeline is responsible for finding the relationship between the object in the source
and an object in the target. On an inbound rule, this relationship would be an object in a connector space finding a
relationship to an object in the metaverse.

The goal is to see if there is an object already in the metaverse, created by another Connector, it should be
associated with. For example, in an account-resource forest the user from the account forest should be joined with
the user from the resource forest.
Joins are used mostly on inbound rules to join connector space objects together to the same metaverse object.
The joins are defined as one or more groups. Inside a group, you have clauses. A logical AND is used between all
clauses in a group. A logical OR is used between groups. The groups are processed in order from top to bottom.
When one group has found exactly one match with an object in the target, then no other join rules are evaluated. If
zero or more than one object is found, processing continues to the next group of rules. For this reason, the rules
should be created in the order of most explicit first and more fuzzy at the end.

The joins in this picture are processed from top to bottom. First the sync pipeline sees if there is a match on
employeeID. If not, the second rule sees if the account name can be used to join the objects together. If that is not a
match either, the third and final rule is a more fuzzy match by using the name of user.
If all join rules have been evaluated and there is not exactly one match, the Link Type on the Description page is
used. If this option is set to Provision, then a new object in the target is created.

An object should only have one single sync rule with join rules in scope. If there are multiple sync rules where join
is defined, an error occurs. Precedence is not used to resolve join conflicts. An object must have a join rule in scope
for attributes to flow with the same inbound/outbound direction. If you need to flow attributes both inbound and
outbound to the same object, you must have both an inbound and an outbound sync rule with join.
Outbound join has a special behavior when it tries to provision an object to a target connector space. The DN
attribute is used to first try a reverse-join. If there is already an object in the target connector space with the same
DN, the objects are joined.
The join module is only evaluated once when a new sync rule comes into scope. When an object has joined, it is
not disjoining even if the join criteria is no longer satisfied. If you want to disjoin an object, the sync rule that
joined the objects must go out of scope.
Metaverse delete
A metaverse object remains as long as there is one sync rule in scope with Link Type set to Provision or
StickyJoin. A StickyJoin is used when a Connector is not allowed to provision a new object to the metaverse, but
when it has joined, it must be deleted in the source before the metaverse object is deleted.
When a metaverse object is deleted, all objects associated with an outbound sync rule marked for provision are
marked for a delete.

Transformations
The transformations are used to define how attributes should flow from the source to the target. The flows can
have one of the following flow types: Direct, Constant, or Expression. A direct flow, flows an attribute value as-is
with no additional transformations. A constant value sets the specified value. An expression uses the declarative
provisioning expression language to express how the transformation should be. The details for the expression
language can be found in the understanding declarative provisioning expression language topic.

The Apply once checkbox defines that the attribute should only be set when the object is initially created. For
example, this configuration can be used to set an initial password for a new user object.
Merging attribute values
In the attribute flows there is a setting to determine if multi-valued attributes should be merged from several
different Connectors. The default value is Update, which indicates that the sync rule with highest precedence
should win.

There is also Merge and MergeCaseInsensitive. These options allow you to merge values from different sources.
For example, it can be used to merge the member or proxyAddresses attribute from several different forests.
When you use this option, all sync rules in scope for an object must use the same merge type. You cannot define
Update from one Connector and Merge from another. If you try, you receive an error.
The difference between Merge and MergeCaseInsensitive is how to process duplicate attribute values. The sync
engine makes sure duplicate values are not inserted into the target attribute. With MergeCaseInsensitive,
duplicate values with only a difference in case are not going to be present. For example, you should not see both
"SMTP:bob@contoso.com" and "smtp:bob@contoso.com" in the target attribute. Merge is only looking at the
exact values and multiple values where there only is a difference in case might be present.
The option Replace is the same as Update, but it is not used.
Control the attribute flow process
When multiple inbound sync rules are configured to contribute to the same metaverse attribute, then precedence
is used to determine the winner. The sync rule with highest precedence (lowest numeric value) is going to
contribute the value. The same happens for outbound rules. The sync rule with highest precedence wins and
contribute the value to the connected directory.
In some cases, rather than contribute a value, the sync rule should determine how other rules should behave.
There are some special literals used for this case.
For inbound Synchronization Rules, the literal NULL can be used to indicate that the flow has no value to
contribute. Another rule with lower precedence can contribute a value. If no rule contributed a value, then the
metaverse attribute is removed. For an outbound rule, if NULL is the final value after all sync rules have been
processed, then the value is removed in the connected directory.
The literal AuthoritativeNull is similar to NULL but with the difference that no lower precedence rules can
contribute a value.
An attribute flow can also use IgnoreThisFlow. It is similar to NULL in the sense that it indicates there is nothing
to contribute. The difference is that it does not remove an already existing value in the target. It is like the attribute
flow has never been there.
Here is an example:
In Out to AD - User Exchange hybrid the following flow can be found:
IIF([cloudSOAExchMailbox] = True,[cloudMSExchSafeSendersHash],IgnoreThisFlow)
This expression should be read as: if the user mailbox is located in Azure AD, then flow the attribute from Azure AD
to AD. If not, do not flow anything back to Active Directory. In this case, it would keep the existing value in AD.
ImportedValue
The function ImportedValue is different than all other functions since the attribute name must be enclosed in
quotes rather than square brackets:
ImportedValue("proxyAddresses") .

Usually during synchronization an attribute uses the expected value, even if it hasn’t been exported yet or an error
was received during export (“top of the tower”). An inbound synchronization assumes that an attribute that hasn’t
yet reached a connected directory eventually reaches it. In some cases, it is important to only synchronize a value
that has been confirmed by the connected directory (“hologram and delta import tower”).
An example of this function can be found in the out-of-box Synchronization Rule In from AD – User Common from
Exchange. In Hybrid Exchange, the value added by Exchange online should only be synchronized when it has been
confirmed that the value was exported successfully:
proxyAddresses <- RemoveDuplicates(Trim(ImportedValue("proxyAddresses")))

Precedence
When several sync rules try to contribute the same attribute value to the target, the precedence value is used to
determine the winner. The rule with highest precedence, lowest numeric value, is going to contribute the attribute
in a conflict.

This ordering can be used to define more precise attribute flows for a small subset of objects. For example, the
out-of-box-rules make sure that attributes from an enabled account (User AccountEnabled) have precedence
from other accounts.
Precedence can be defined between Connectors. That allows Connectors with better data to contribute values first.
Multiple objects from the same connector space
If you have several objects in the same connector space joined to the same metaverse object, precedence must be
adjusted. If several objects are in scope of the same sync rule, then the sync engine is not able to determine
precedence. It is ambiguous which source object should contribute the value to the metaverse. This configuration
is reported as ambiguous even if the attributes in the source have the same value.
For this scenario, you need to change the scope of the sync rules so the source objects have different sync rules in
scope. That allows you to define different precedence.

Next steps
Read more about the expression language in Understanding Declarative Provisioning Expressions.
See how declarative provisioning is used out-of-box in Understanding the default configuration.
See how to make a practical change using declarative provisioning in How to make a change to the default
configuration.
Continue to read how users and contacts work together in Understanding Users and Contacts.
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Reference topics
Azure AD Connect sync: Functions Reference
Azure AD Connect sync: Understanding Declarative
Provisioning Expressions
1/17/2018 • 3 min to read • Edit Online

Azure AD Connect sync builds on declarative provisioning first introduced in Forefront Identity Manager 2010. It
allows you to implement your complete identity integration business logic without the need to write compiled
code.
An essential part of declarative provisioning is the expression language used in attribute flows. The language used
is a subset of Microsoft® Visual Basic® for Applications (VBA). This language is used in Microsoft Office and users
with experience of VBScript will also recognize it. The Declarative Provisioning Expression Language is only using
functions and is not a structured language. There are no methods or statements. Functions are instead nested to
express program flow.
For more details, see Welcome to the Visual Basic for Applications language reference for Office 2013.
The attributes are strongly typed. A function only accepts attributes of the correct type. It is also case-sensitive.
Both function names and attribute names must have proper casing or an error is thrown.

Language definitions and Identifiers


Functions have a name followed by arguments in brackets: FunctionName(argument 1, argument N).
Attributes are identified by square brackets: [attributeName]
Parameters are identified by percent signs: %ParameterName%
String constants are surrounded by quotes: For example, "Contoso" (Note: must use straight quotes "" and not
smart quotes “”)
Numeric values are expressed without quotes and expected to be decimal. Hexadecimal values are prefixed
with &H. For example, 98052, &HFF
Boolean values are expressed with constants: True, False.
Built-in constants and literals are expressed with only their name: NULL, CRLF, IgnoreThisFlow
Functions
Declarative provisioning uses many functions to enable the possibility to transform attribute values. These
functions can be nested so the result from one function is passed in to another function.
Function1(Function2(Function3()))

The complete list of functions can be found in the function reference.


Parameters
A parameter is defined either by a Connector or by an administrator using PowerShell. Parameters usually contain
values that are different from system to system, for example the name of the domain the user is located in. These
parameters can be used in attribute flows.
The Active Directory Connector provided the following parameters for inbound Synchronization Rules:

PARAMETER NAME COMMENT

Domain.Netbios Netbios format of the domain currently being imported, for


example FABRIKAMSALES
PARAMETER NAME COMMENT

Domain.FQDN FQDN format of the domain currently being imported, for


example sales.fabrikam.com

Domain.LDAP LDAP format of the domain currently being imported, for


example DC=sales,DC=fabrikam,DC=com

Forest.Netbios Netbios format of the forest name currently being imported,


for example FABRIKAMCORP

Forest.FQDN FQDN format of the forest name currently being imported, for
example fabrikam.com

Forest.LDAP LDAP format of the forest name currently being imported, for
example DC=fabrikam,DC=com

The system provides the following parameter, which is used to get the identifier of the Connector currently
running:
Connector.ID

Here is an example that populates the metaverse attribute domain with the netbios name of the domain where the
user is located:
domain <- %Domain.Netbios%

Operators
The following operators can be used:
Comparison: <, <=, <>, =, >, >=
Mathematics: +, -, *, -
String: & (concatenate)
Logical: && (and), || (or)
Evaluation order: ( )
Operators are evaluated left to right and have the same evaluation priority. That is, the * (multiplier) is not
evaluated before - (subtraction). 2*(5+3) is not the same as 2*5+3. The brackets ( ) are used to change the
evaluation order when left to right evaluation order isn't appropriate.

Multi-valued attributes
The functions can operate on both single-valued and multi-valued attributes. For multi-valued attributes, the
function operates over every value and applies the same function to every value.
For example:
Trim([proxyAddresses]) Do a Trim of every value in the proxyAddress attribute.
Word([proxyAddresses],1,"@") & "@contoso.com" For every value with an @-sign, replace the domain with
@contoso.com.
IIF(InStr([proxyAddresses],"SIP:")=1,NULL,[proxyAddresses]) Look for the SIP-address and remove it from the
values.

Next steps
Read more about the configuration model in Understanding Declarative Provisioning.
See how declarative provisioning is used out-of-box in Understanding the default configuration.
See how to make a practical change using declarative provisioning in How to make a change to the default
configuration.
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Reference topics
Azure AD Connect sync: Functions Reference
Azure AD Connect sync: Understanding the default
configuration
3/6/2018 • 15 min to read • Edit Online

This article explains the out-of-box configuration rules. It documents the rules and how these rules impact the
configuration. It also walks you through the default configuration of Azure AD Connect sync. The goal is that the
reader understands how the configuration model, named declarative provisioning, is working in a real-world
example. This article assumes that you have already installed and configure Azure AD Connect sync using the
installation wizard.
To understand the details of the configuration model, read Understanding Declarative Provisioning.

Out-of-box rules from on-premises to Azure AD


The following expressions can be found in the out-of-box configuration.
User out-of-box rules
These rules also apply to the iNetOrgPerson object type.
A user object must satisfy the following to be synchronized:
Must have a sourceAnchor.
After the object has been created in Azure AD, then sourceAnchor cannot change. If the value is changed on-
premises, the object stops synchronizing until the sourceAnchor is changed back to its previous value.
Must have the accountEnabled (userAccountControl) attribute populated. With an on-premises Active
Directory, this attribute is always present and populated.
The following user objects are not synchronized to Azure AD:
IsPresent([isCriticalSystemObject]) . Ensure many out-of-box objects in Active Directory, such as the built-in
administrator account, are not synchronized.
IsPresent([sAMAccountName]) = False . Ensure user objects with no sAMAccountName attribute are not
synchronized. This case would only practically happen in a domain upgraded from NT4.
Left([sAMAccountName], 4) = "AAD_" , Left([sAMAccountName], 5) = "MSOL_" . Do not synchronize the service
account used by Azure AD Connect sync and its earlier versions.
Do not synchronize Exchange accounts that would not work in Exchange Online.
[sAMAccountName] = "SUPPORT_388945a0"
Left([mailNickname], 14) = "SystemMailbox{"
(Left([mailNickname], 4) = "CAS_" && (InStr([mailNickname], "}") > 0))
(Left([sAMAccountName], 4) = "CAS_" && (InStr([sAMAccountName], "}")> 0))
Do not synchronize objects that would not work in Exchange Online.
CBool(IIF(IsPresent([msExchRecipientTypeDetails]),BitAnd([msExchRecipientTypeDetails],&H21C07000) > 0,NULL))
This bitmask (&H21C07000) would filter out the following objects:
Mail-enabled Public Folder (In Preview as of version 1.1.524.0)
System Attendant Mailbox
Mailbox Database Mailbox (System Mailbox)
Universal Security Group (wouldn't apply for a user, but is present for legacy reasons)
Non-Universal Group (wouldn't apply for a user, but is present for legacy reasons)
Mailbox Plan
Discovery Mailbox
CBool(InStr(DNComponent(CRef([dn]),1),"\\0ACNF:")>0) . Do not synchronize any replication victim objects.
The following attribute rules apply:
sourceAnchor <- IIF([msExchRecipientTypeDetails]=2,NULL,..) . The sourceAnchor attribute is not contributed
from a linked mailbox. It is assumed that if a linked mailbox has been found, the actual account is joined later.
Exchange related attributes are only synchronized if the attribute mailNickName has a value.
When there are multiple forests, then attributes are consumed in the following order:
1. Attributes related to sign-in (for example userPrincipalName) are contributed from the forest with an
enabled account.
2. Attributes that can be found in an Exchange GAL (Global Address List) are contributed from the forest
with an Exchange Mailbox.
3. If no mailbox can be found, then these attributes can come from any forest.
4. Exchange related attributes (technical attributes not visible in the GAL) are contributed from the forest
where mailNickname ISNOTNULL .
5. If there are multiple forests that would satisfy one of these rules, then the creation order (date/time) of
the Connectors (forests) is used to determine which forest contributes the attributes.
Contact out-of-box rules
A contact object must satisfy the following to be synchronized:
The contact must be mail-enabled. It is verified with the following rules:
IsPresent([proxyAddresses]) = True) . The proxyAddresses attribute must be populated.
A primary email address can be found in either the proxyAddresses attribute or the mail attribute. The
presence of an @ is used to verify that the content is an email address. One of these two rules must be
evaluated to True.
(Contains([proxyAddresses], "SMTP:") > 0) && (InStr(Item([proxyAddresses],
Contains([proxyAddresses], "SMTP:")), "@") > 0))
. Is there an entry with "SMTP:" and if there is, can an @ be found in the string?
(IsPresent([mail]) = True && (InStr([mail], "@") > 0) . Is the mail attribute populated and if it is,
can an @ be found in the string?
The following contact objects are not synchronized to Azure AD:
IsPresent([isCriticalSystemObject]) . Ensure no contact objects marked as critical are synchronized. Shouldn't
be any with a default configuration.
((InStr([displayName], "(MSOL)") > 0) && (CBool([msExchHideFromAddressLists]))) .
(Left([mailNickname], 4) = "CAS_" && (InStr([mailNickname], "}") > 0)) . These objects wouldn't work in
Exchange Online.
CBool(InStr(DNComponent(CRef([dn]),1),"\\0ACNF:")>0) . Do not synchronize any replication victim objects.
Group out-of-box rules
A group object must satisfy the following to be synchronized:
Must have less than 50,000 members. This count is the number of members in the on-premises group.
If it has more members before synchronization starts the first time, the group is not synchronized.
If the number of members grow from when it was initially created, then when it reaches 50,000
members it stops synchronizing until the membership count is lower than 50,000 again.
Note: The 50,000 membership count is also enforced by Azure AD. You are not able to synchronize
groups with more members even if you modify or remove this rule.
If the group is a Distribution Group, then it must also be mail enabled. See Contact out-of-box rules for this
rule is enforced.
The following group objects are not synchronized to Azure AD:
IsPresent([isCriticalSystemObject]) . Ensure many out-of-box objects in Active Directory, such as the built-in
administrators group, are not synchronized.
[sAMAccountName] = "MSOL_AD_Sync_RichCoexistence" . Legacy group used by DirSync.
BitAnd([msExchRecipientTypeDetails],&amp;H40000000) . Role Group.
CBool(InStr(DNComponent(CRef([dn]),1),"\\0ACNF:")>0) . Do not synchronize any replication victim objects.

ForeignSecurityPrincipal out-of-box rules


FSPs are joined to "any" (*) object in the metaverse. In reality, this join only happens for users and security groups.
This configuration ensures that cross-forest memberships are resolved and represented correctly in Azure AD.
Computer out-of-box rules
A computer object must satisfy the following to be synchronized:
userCertificate ISNOTNULL . Only Windows 10 computers populate this attribute. All computer objects with a
value in this attribute are synchronized.

Understanding the out-of-box rules scenario


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

In this configuration, it is assumed there is an enabled account in the account forest and a disabled account in the
resource forest with a linked mailbox.
Our goal with the default configuration is:
Attributes related to sign-in are synchronized from the forest with the enabled account.
Attributes that can be found in the GAL (Global Address List) are synchronized from the forest with the mailbox.
If no mailbox can be found, any other forest is used.
If a linked mailbox is found, the linked enabled account must be found for the object to be exported to Azure
AD.
Synchronization Rule Editor
The configuration can 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 and it is installed with Azure AD Connect sync. To be able to start it, you must be a
member of the ADSyncAdmins group. When it starts, you see something like this:

In this pane, you 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. You are mainly going to focus on the inbound rules in
this overview. The actual list of Synchronization Rules depends on the detected schema in AD. In the picture above,
the account forest (fabrikamonline.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
(res.fabrikamonline.com) you find Synchronization Rules for these services. The content of the rules is different
depending on the version detected. For example, in a deployment with Exchange 2013 there are more attribute
flows configured than in Exchange 2010/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 value indicating how they relate to each other. A
Synchronization Rule with a lower numeric value has a higher precedence and in an attribute flow conflict, higher
precedence wins the conflict resolution.
As an example, look at the Synchronization Rule In from AD – User AccountEnabled. Mark this line in the SRE
and select Edit.
Since this rule is an out-of-box rule, you receive a warning when you open the rule. You should not make any
changes to out-of-box rules, so you are asked what your intentions are. In this case, you only want to view the rule.
Select No.
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.

You 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 when
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 is covered later.
You can also see that this sync rule is used for password sync. If a user is in scope for this sync rule, the password
is synchronized from on-premises to cloud (assuming you have enabled the password sync feature).
Scoping filter
The Scoping Filter section is used to configure when a Synchronization Rule should apply. Since the name of the
Synchronization Rule you 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 the sync engine finds a
user in AD, it applies this sync rule when userAccountControl is set to the decimal value 512 (enabled normal
user). It does not apply the rule when the user has userAccountControl set to 514 (disabled normal user).
The scoping filter has Groups and Clauses that 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. That is, a logical OR is evaluated between groups and a logical AND is evaluated inside a group. An
example of this configuration can be found in the outbound Synchronization Rule Out to AAD – Group Join.
There are several synchronization filter groups, for example 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 Azure AD. Distribution Groups must be mail
enabled to be synchronized with Azure AD, but for security groups an email is not required.
Join rules
The third section is used to configure how objects in the connector space relate to objects in the metaverse. The
rule you have looked at earlier does not have any configuration for Join Rules, so instead you are going to look at
In from AD – User Join.

The content of the join rule depends 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 the 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. If all rules have been evaluated and there is no match, then the Link Type on the
description page is used. If this configuration 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, they
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 AD Connect 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 applies the attribute flows when another Synchronization Rule joined the objects together
or provisioned a new object in the target.
If you look at the picture above, you can see that the rule is trying to join objectSID with
msExchMasterAccountSid (Exchange) and msRTCSIP-OriginatorSid (Lync), which is what we expect in an
account-resource forest topology. You find the same rule on all forests. The assumption is that every forest could
be either an account or resource forest. This configuration also works if you have accounts that live in a single
forest and do not have to be joined.
Transformations
The transformation section defines all attribute flows that apply to the target object when the objects are joined
and the scope filter is satisfied. Going back to the In from AD – User AccountEnabled Synchronization Rule, you
find the following transformations:
To put this configuration in context, in an Account-Resource forest deployment, it is expected 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 you are looking at contains the attributes required for sign-in and these attributes should
flow from the forest where there is 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 always flows a hardcoded value. In the case above, it always sets the value True in the
metaverse attribute named accountEnabled.
A direct flow always flows the value of the attribute in the source to the target attribute as-is.
The third flow type is Expression and it allows for more advanced configurations.
The expression language is VBA (Visual Basic for Applications), so people 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 evaluates 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 Azure AD, and finally convert it to a string.
CStr(FormatDateTime(DateFromNum([pwdLastSet]),"yyyyMMddHHmmss.0Z")),
// (The False part of IIF) Nothing to contribute
NULL
)

See Understanding Declarative Provisioning Expressions for more information on the expression language for
attribute flows.
Precedence
You 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 wins. As an example, look at the attribute
sourceAnchor. This attribute is an important attribute to be able to sign in to Azure AD. You 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 is contributed from the
forest with an enabled account first when there are several objects joined to the metaverse object. If there are no
enabled accounts, then the sync engine uses the catch-all Synchronization Rule In from AD – User Common. This
configuration ensures that even for accounts that are disabled, there is still a sourceAnchor.

The precedence for Synchronization Rules is set in groups by the installation wizard. All rules in a group have the
same name, but they are connected to different connected directories. The installation wizard gives the rule In
from AD – User Join highest precedence and it iterates over all connected AD directories. It then continues with
the next groups of rules in a predefined order. Inside a group, the rules are added in the order the Connectors
were added in the wizard. If another Connector is added through the wizard, the Synchronization Rules are
reordered and the new Connector’s rules are 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 you look at a user and the attributes that 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 sign-in to Azure AD and Office 365.
We want these attributes from the enabled account.
NAME COMMENT

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 Only exists if Exchange has been detected. It flows all
infrastructure Exchange attributes.

In from AD – User Lync Only exists if Lync has been detected. It flows all infrastructure
Lync attributes.

Next steps
Read more about the configuration model in Understanding Declarative Provisioning.
Read more about the expression language in Understanding Declarative Provisioning Expressions.
Continue reading how the out-of-box configuration works in Understanding Users and Contacts
See how to make a practical change using declarative provisioning in How to make a change to the default
configuration.
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect and federation
12/11/2017 • 2 min to read • Edit Online

Azure Active Directory (Azure AD) Connect lets you configure federation with on-premises Active Directory
Federation Services (AD FS) and Azure AD. With federation sign-in, you can enable users to sign in to Azure AD-
based services with their on-premises passwords--and, while on the corporate network, without having to enter
their passwords again. By using the federation option with AD FS, you can deploy a new installation of AD FS, or
you can specify an existing installation in a Windows Server 2012 R2 farm.
This topic is the home for information on federation-related functionalities for Azure AD Connect. It lists links to all
related topics. For links to Azure AD Connect, see Integrating your on-premises identities with Azure Active
Directory.

Azure AD Connect: federation topics


TOPIC WHAT IT COVERS AND WHEN TO READ IT

Azure AD Connect user sign-in options

Understand user sign-in options Learn about various user sign-in options and how they affect
the Azure sign-in user experience.

Install AD FS by using Azure AD Connect

Prerequisites See the prerequisites for a successful AD FS installation via


Azure AD Connect.

Configure an AD FS farm Install a new AD FS farm by using Azure AD Connect.

Federate with Azure AD using alternate login ID Configure federation using alternate login ID

Modify the AD FS configuration

Repair the trust Repair the current trust between on-premises AD FS and
Office 365/Azure.

Add a new AD FS server Expand an AD FS farm with an additional AD FS server after


initial installation.

Add a new AD FS WAP server Expand an AD FS farm with an additional Web Application
Proxy (WAP) server after initial installation.

Add a new federated domain Add another domain to be federated with Azure AD.

Update the SSL certificate Update the SSL certificate for an AD FS farm.

Renew federation certificates for Office 365 and Azure AD Renew your O365 certificate with Azure AD.

Other federation configuration


TOPIC WHAT IT COVERS AND WHEN TO READ IT

Federate multiple instances of Azure AD with single instance Federate multiple Azure AD with single AD FS farm
of AD FS

Add a custom company logo/illustration Modify the sign-in experience by specifying the custom logo
that is shown on the AD FS sign-in page.

Add a sign-in description Change the sign-in description on the AD FS sign-in page.

Modify AD FS claim rules Modify or add claim rules in AD FS that correspond to Azure
AD Connect sync configuration.

Additional resources
Federating two Azure AD with single AD FS
AD FS deployment in Azure
High-availability cross-geographic AD FS deployment in Azure with Azure Traffic Manager
Prerequisites for Azure AD Connect
3/9/2018 • 13 min to read • Edit Online

This topic describes the pre-requisites and the hardware requirements for Azure AD Connect.

Before you install Azure AD Connect


Before you install Azure AD Connect, there are a few things that you need.
Azure AD
An Azure subscription or an Azure trial subscription. This subscription is only required for accessing the Azure
portal and not for using Azure AD Connect. If you are using PowerShell or Office 365, then you do not need an
Azure subscription to use Azure AD Connect. If you have an Office 365 license, then you can also use the Office
365 portal. With a paid Office 365 license, you can also get into the Azure portal from the Office 365 portal.
You can also use the Azure portal. This portal does not require an Azure AD license.
Add and verify the domain you plan to use in Azure AD. For example, if you plan to use contoso.com for your
users then make sure this domain has been verified and you are not only using the contoso.onmicrosoft.com
default domain.
An Azure AD tenant allows by default 50k objects. When you verify your domain, the limit is increased to 300k
objects. If you need even more objects in Azure AD, then you need to open a support case to have the limit
increased even further. If you need more than 500k objects, then you need a license, such as Office 365, Azure
AD Basic, Azure AD Premium, or Enterprise Mobility and Security.
ADSyncPrep is a PowerShell script module that provides functions that are used to prepare your Active
Directory environment for Azure AD Connect. ADSyncPrep requires the Azure AD Microsoft Online v1.1
PowerShell Module. Version 2 will not work. You will can install the module using the Install-Module cmdlet.
For more information see the link provided.
Prepare your on-premises data
Use IdFix to identify errors such as duplicates and formatting problems in your directory before you
synchronize to Azure AD and Office 365.
Review optional sync features you can enable in Azure AD and evaluate which features you should enable.
On-premises Active Directory
The AD schema version and forest functional level must be Windows Server 2003 or later. The domain
controllers can run any version as long as the schema and forest level requirements are met.
If you plan to use the feature password writeback, then the Domain Controllers must be on Windows Server
2008 (with latest SP) or later. If your DCs are on 2008 (pre-R2), then you must also apply hotfix KB2386717.
The domain controller used by Azure AD must be writable. It is not supported to use a RODC (read-only
domain controller) and Azure AD Connect does not follow any write redirects.
It is not supported to use on-premises forests/domains using SLDs (Single Label Domains).
It is not supported to use on-premises forests/domains using "dotted" (name contains a period ".") NetBios
names.
It is recommended to enable the Active Directory recycle bin.
Azure AD Connect server
Azure AD Connect cannot be installed on Small Business Server or Windows Server Essentials. The server must
be using Windows Server standard or better.
The Azure AD Connect server must have a full GUI installed. It is not supported to install on server core.
Azure AD Connect must be installed on Windows Server 2008 or later. This server may be a domain controller
or a member server when using express settings. If you use custom settings, then the server can also be stand-
alone and does not have to be joined to a domain.
If you install Azure AD Connect on Windows Server 2008 or Windows Server 2008 R2, then make sure to apply
the latest hotfixes from Windows Update. The installation is not able to start with an unpatched server.
If you plan to use the feature password synchronization, then the Azure AD Connect server must be on
Windows Server 2008 R2 SP1 or later.
If you plan to use a group managed service account, then the Azure AD Connect server must be on Windows
Server 2012 or later.
The Azure AD Connect server must have .NET Framework 4.5.1 or later and Microsoft PowerShell 3.0 or later
installed.
The Azure AD Connect server must not have PowerShell Transcription Group Policy enabled.
If Active Directory Federation Services is being deployed, the servers where AD FS or Web Application Proxy are
installed must be Windows Server 2012 R2 or later. Windows remote management must be enabled on these
servers for remote installation.
If Active Directory Federation Services is being deployed, you need SSL Certificates.
If Active Directory Federation Services is being deployed, then you need to configure name resolution.
If your global administrators have MFA enabled, then the URL https://secure.aadcdn.microsoftonline-
p.com must be in the trusted sites list. You are prompted to add this site to the trusted sites list when you are
prompted for an MFA challenge and it has not added before. You can use Internet Explorer to add it to your
trusted sites.
SQL Server used by Azure AD Connect
Azure AD Connect requires a SQL Server database to store identity data. By default a SQL Server 2012 Express
LocalDB (a light version of SQL Server Express) is installed. SQL Server Express has a 10GB size limit that
enables you to manage approximately 100,000 objects. If you need to manage a higher volume of directory
objects, you need to point the installation wizard to a different installation of SQL Server.
If you use a separate SQL Server, then these requirements apply:
Azure AD Connect supports all versions of Microsoft SQL Server from SQL Server 2008 (with latest
Service Pack) to SQL Server 2016 SP1. Microsoft Azure SQL Database is not supported as a database.
You must use a case-insensitive SQL collation. These collations are identified with a _CI_ in their name. It
is not supported to use a case-sensitive collation, identified by _CS_ in their name.
You can only have one sync engine per SQL instance. It is not supported to share a SQL instance with
FIM/MIM Sync, DirSync, or Azure AD Sync.
Accounts
An Azure AD Global Administrator account for the Azure AD tenant you wish to integrate with. This account
must be a school or organization account and cannot be a Microsoft account.
If you use express settings or upgrade from DirSync, then you must have an Enterprise Administrator account
for your local Active Directory.
Accounts in Active Directory if you use the custom settings installation path.
Connectivity
The Azure AD Connect server needs DNS resolution for both intranet and internet. The DNS server must be able
to resolve names both to your on-premises Active Directory and the Azure AD endpoints.
If you have firewalls on your Intranet and you need to open ports between the Azure AD Connect servers and
your domain controllers, then see Azure AD Connect Ports for more information.
If your proxy or firewall limit which URLs can be accessed, then the URLs documented in Office 365 URLs and IP
address ranges must be opened.
If you are using the Microsoft Cloud in Germany or the Microsoft Azure Government cloud, then see
Azure AD Connect sync service instances considerations for URLs.
Azure AD Connect (version 1.1.614.0 and after) by default uses TLS 1.2 for encrypting communication between
the sync engine and Azure AD. If TLS 1.2 isn't available on the underlying operating system, Azure AD Connect
incrementally falls back to older protocols (TLS 1.1 and TLS 1.0). For example, Azure AD Connect running on
Windows Server 2008 uses TLS 1.0 because Windows Server 2008 does not support TLS 1.1 or TLS 1.2.
Prior to version 1.1.614.0, Azure AD Connect by default uses TLS 1.0 for encrypting communication between
the sync engine and Azure AD. To change to TLS 1.2, follow the steps in Enable TLS 1.2 for Azure AD Connect.
If you are using an outbound proxy for connecting to the Internet, the following setting in the
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config\machine.config file must be added for the
installation wizard and Azure AD Connect sync to be able to connect to the Internet and Azure AD. This text
must be entered at the bottom of the file. In this code, <PROXYADRESS> represents the actual proxy IP address
or host name.

<system.net>
<defaultProxy>
<proxy
usesystemdefault="true"
proxyaddress="http://<PROXYADDRESS>:<PROXYPORT>"
bypassonlocal="true"
/>
</defaultProxy>
</system.net>

If your proxy server requires authentication, then the service account must be located in the domain and you
must use the customized settings installation path to specify a custom service account. You also need a different
change to machine.config. With this change in machine.config, the installation wizard and sync engine respond
to authentication requests from the proxy server. In all installation wizard pages, excluding the Configure page,
the signed in user's credentials are used. On the Configure page at the end of the installation wizard, the
context is switched to the service account that was created by you. The machine.config section should look like
this.

<system.net>
<defaultProxy enabled="true" useDefaultCredentials="true">
<proxy
usesystemdefault="true"
proxyaddress="http://<PROXYADDRESS>:<PROXYPORT>"
bypassonlocal="true"
/>
</defaultProxy>
</system.net>

When Azure AD Connect sends a web request to Azure AD as part of directory synchronization, Azure AD can
take up to 5 minutes to respond. It is common for proxy servers to have connection idle timeout configuration.
Please ensure the configuration is set to at least 6 minutes or more.
For more information, see MSDN about the default proxy Element.
For more information when you have problems with connectivity, see Troubleshoot connectivity problems.
Other
Optional: A test user account to verify synchronization.

Component prerequisites
PowerShell and .Net Framework
Azure AD Connect depends on Microsoft PowerShell and .NET Framework 4.5.1. You need this version or a later
version installed on your server. Depending on your Windows Server version, do the following:
Windows Server 2012R2
Microsoft PowerShell is installed by default. No action is required.
.NET Framework 4.5.1 and later releases are offered through Windows Update. Make sure you have
installed the latest updates to Windows Server in the Control Panel.
Windows Server 2008R2 and Windows Server 2012
The latest version of Microsoft PowerShell is available in Windows Management Framework 4.0,
available on Microsoft Download Center.
.NET Framework 4.5.1 and later releases are available on Microsoft Download Center.
Windows Server 2008
The latest supported version of PowerShell is available in Windows Management Framework 3.0,
available on Microsoft Download Center.
.NET Framework 4.5.1 and later releases are available on Microsoft Download Center.
Enable TLS 1.2 for Azure AD Connect
Prior to version 1.1.614.0, Azure AD Connect by default uses TLS 1.0 for encrypting the communication between
the sync engine server and Azure AD. You can change this by configuring .Net applications to use TLS 1.2 by
default on the server. More information about TLS 1.2 can be found in Microsoft Security Advisory 2960358.
1. TLS 1.2 cannot be enabled on Windows Server 2008. You need Windows Server 2008R2 or later. Make sure
you have the .Net 4.5.1 hotfix installed for your operating system, see Microsoft Security Advisory 2960358.
You might have this hotfix or a later release installed on your server already.
2. If you use Windows Server 2008R2, then make sure TLS 1.2 is enabled. On Windows Server 2012 server and
later versions, TLS 1.2 should already be enabled.
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2]
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client]
"DisabledByDefault"=dword:00000000 "Enabled"=dword:00000001
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server]
"DisabledByDefault"=dword:00000000 "Enabled"=dword:00000001
3. For all operating systems, set this registry key and restart the server.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 "SchUseStrongCrypto"=dword:00000001
4. If you also want to enable TLS 1.2 between the sync engine server and a remote SQL Server, then make sure
you have the required versions installed for TLS 1.2 support for Microsoft SQL Server.

Prerequisites for federation installation and configuration


Windows Remote Management
When using Azure AD Connect to deploy Active Directory Federation Services or the Web Application Proxy, check
these requirements:
If the target server is domain joined, then ensure that Windows Remote Managed is enabled
In an elevated PSH command window, use command Enable-PSRemoting –force
If the target server is a non-domain joined WAP machine, then there are a couple of additional requirements
On the target machine (WAP machine):
Ensure the winrm (Windows Remote Management / WS-Management) service is running via the
Services snap-in
In an elevated PSH command window, use command Enable-PSRemoting –force
On the machine on which the wizard is running (if the target machine is non-domain joined or untrusted
domain):
In an elevated PSH command window, use the command
Set-Item WSMan:\localhost\Client\TrustedHosts –Value <DMZServerFQDN> -Force –Concatenate
In Server Manager:
add DMZ WAP host to machine pool (server manager -> Manage -> Add Servers...use DNS
tab)
Server Manager All Servers tab: right click WAP server and choose Manage As..., enter local
(not domain) creds for the WAP machine
To validate remote PSH connectivity, in the Server Manager All Servers tab: right click WAP
server and choose Windows PowerShell. A remote PSH session should open to ensure
remote PowerShell sessions can be established.
SSL Certificate Requirements
It’s strongly recommended to use the same SSL certificate across all nodes of your AD FS farm and all Web
Application proxy servers.
The certificate must be an X509 certificate.
You can use a self-signed certificate on federation servers in a test lab environment. However, for a production
environment, we recommend that you obtain the certificate from a public CA.
If using a certificate that is not publicly trusted, ensure that the certificate installed on each Web
Application Proxy server is trusted on both the local server and on all federation servers
The identity of the certificate must match the federation service name (for example, sts.contoso.com).
The identity is either a subject alternative name (SAN) extension of type dNSName or, if there are no
SAN entries, the subject name specified as a common name.
Multiple SAN entries can be present in the certificate, provided one of them matches the federation
service name.
If you are planning to use Workplace Join, an additional SAN is required with the value
enterpriseregistration. followed by the User Principal Name (UPN) suffix of your organization, for
example, enterpriseregistration.contoso.com.
Certificates based on CryptoAPI next generation (CNG) keys and key storage providers are not supported. This
means you must use a certificate based on a CSP (cryptographic service provider) and not a KSP (key storage
provider).
Wild-card certificates are supported.
Name resolution for federation servers
Set up DNS records for the AD FS federation service name (for example sts.contoso.com) for both the intranet
(your internal DNS server) and the extranet (public DNS through your domain registrar). For the intranet DNS
record, ensure that you use A records and not CNAME records. This is required for windows authentication to
work correctly from your domain joined machine.
If you are deploying more than one AD FS server or Web Application Proxy server, then ensure that you have
configured your load balancer and that the DNS records for the AD FS federation service name (for example
sts.contoso.com) point to the load balancer.
For windows integrated authentication to work for browser applications using Internet Explorer in your intranet,
ensure that the AD FS federation service name (for example sts.contoso.com) is added to the intranet zone in IE.
This can be controlled via group policy and deployed to all your domain joined computers.

Azure AD Connect supporting components


The following is a list of components that Azure AD Connect installs on the server where Azure AD Connect is
installed. This list is for a basic Express installation. If you choose to use a different SQL Server on the Install
synchronization services page, then SQL Express LocalDB is not installed locally.
Azure AD Connect Health
Microsoft Online Services Sign-In Assistant for IT Professionals (installed but no dependency on it)
Microsoft SQL Server 2012 Command Line Utilities
Microsoft SQL Server 2012 Express LocalDB
Microsoft SQL Server 2012 Native Client
Microsoft Visual C++ 2013 Redistribution Package

Hardware requirements for Azure AD Connect


The table below shows the minimum requirements for the Azure AD Connect sync computer.

NUMBER OF OBJECTS IN
ACTIVE DIRECTORY CPU MEMORY HARD DRIVE SIZE

Fewer than 10,000 1.6 GHz 4 GB 70 GB

10,000–50,000 1.6 GHz 4 GB 70 GB

50,000–100,000 1.6 GHz 16 GB 100 GB

For 100,000 or more objects


the full version of SQL
Server is required

100,000–300,000 1.6 GHz 32 GB 300 GB

300,000–600,000 1.6 GHz 32 GB 450 GB

More than 600,000 1.6 GHz 32 GB 500 GB

The minimum requirements for computers running AD FS or Web Application Servers is the following:
CPU: Dual core 1.6 GHz or higher
MEMORY: 2 GB or higher
Azure VM: A2 configuration or higher

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Select which installation type to use for Azure AD
Connect
1/17/2018 • 2 min to read • Edit Online

Azure AD Connect has two installation types for new installation: Express and customized. This topic helps you to
decide which option to use during installation.

Express
Express is the most common option and is used by about 90% of all new installations. It was designed to provide a
configuration that works for the most common customer scenarios.
It assumes:
You have a single Active Directory forest on-premises.
You have an enterprise administrator account you can use for the installation.
You have less than 100,000 objects in your on-premises Active Directory.
You get:
Password synchronization from on-premises to Azure AD for single sign-on.
A configuration that synchronizes users, groups, contacts, and Windows 10 computers.
Synchronization of all eligible objects in all domains and all OUs.
Automatic upgrade is enabled to make sure you always use the latest available version.
Options where you can still use Express:
If you do not want to synchronize all OUs, you can still use Express and on the last page, unselect Start the
synchronization process...*. Then run the installation wizard again and change the OUs in configuration
options and enable scheduled sync.
You want to enable one of the features in Azure AD Premium, such as Password writeback. First go through
express to get the initial installation completed. Then run the installation wizard again and change the
configuration options.

Custom
The customized path allows many more options than express. It should be used in all cases where the configuration
described in previous section for express is not representative for your organization.
Use when:
You do not have access to an enterprise admin account in Active Directory.
You have more than one forest or you plan to synchronize more than one forest in the future.
You have domains in your forest not reachable from the Connect server.
You plan to use federation or pass-through authentication for user sign-in.
You have more than 100,000 objects and need to use a full SQL Server.
You plan to use group-based filtering and not only domain or OU-based filtering.

Upgrade from DirSync


If you are currently using DirSync, then follow the steps in Upgrade from DirSync to upgrade your existing
configuration. There are two different upgrade options:
In-place upgrade to install Connect on the same server.
Parallel deployment to install Connect on a new server while the existing DirSync server is still operational.

Upgrade from Azure AD Sync


If you are currently using Azure AD Sync, then you can follow the same steps as when you upgrade from one
Connect version to a newer. There are two different upgrade options:
In-place upgrade to install Connect on the same server.
Swing-migration to install Connect on a new server while the existing Azure AD Sync server is still operational.

Migrate from FIM2010 or MIM2016


If you are currently using Forefront Identity Manager 2010 or Microsoft Identity Manager 2016 with the Azure AD
Connector, then your only option is a migration. Follow the steps described in swing-migration. In the steps, replace
any mention of Azure AD Sync with FIM2010/MIM2016.

Next steps
Depending on the option you have selected to use, use the table of content to the left to find your article with the
detailed steps.
Getting started with Azure AD Connect using express
settings
1/17/2018 • 2 min to read • Edit Online

Azure AD Connect Express Settings is used when you have a single-forest topology and password
synchronization for authentication. Express Settings is the default option and is used for the most commonly
deployed scenario. You are only a few short clicks away to extend your on-premises directory to the cloud.
Before you start installing Azure AD Connect, make sure to download Azure AD Connect and complete the pre-
requisite steps in Azure AD Connect: Hardware and prerequisites.
If express settings does not match your topology, see related documentation for other scenarios.

Express installation of Azure AD Connect


You can see these steps in action in the videos section.
1. Sign in as a local administrator to the server you wish to install Azure AD Connect on. You should do this on the
server you wish to be the sync server.
2. Navigate to and double-click AzureADConnect.msi.
3. On the Welcome screen, select the box agreeing to the licensing terms and click Continue.
4. On the Express settings screen, click Use express settings.

5. On the Connect to Azure AD screen, enter the username and password of a global administrator for your Azure
AD. Click Next.
If you receive an error and have problems with connectivity, then see Troubleshoot connectivity problems.
6. On the Connect to AD DS screen, enter the username and password for an enterprise admin account. You can
enter the domain part in either NetBios or FQDN format, that is, FABRIKAM\administrator or
fabrikam.com\administrator. Click Next.

7. The Azure AD sign-in configuration page only shows if you did not complete verify your domains in the
prerequisites.
If you see this page, then review every domain marked Not Added and Not Verified. Make sure those
domains you use have been verified in Azure AD. Click the Refresh symbol when you have verified your
domains.
8. On the Ready to configure screen, click Install.
Optionally on the Ready to configure page, you can unselect the Start the synchronization process as
soon as configuration completes checkbox. You should unselect this checkbox if you want to do
additional configuration, such as filtering. If you unselect this option, the wizard configures sync but
leaves the scheduler disabled. It does not run until you enable it manually by rerunning the installation
wizard.
If you have Exchange in your on-premises Active Directory, then you also have an option to enable
Exchange Hybrid deployment. Enable this option if you plan to have Exchange mailboxes both in the
cloud and on-premises at the same time.
9. When the installation completes, click Exit.
10. After the installation has completed, sign off and sign in again before you use Synchronization Service Manager
or Synchronization Rule Editor.

Videos
For a video on using the express installation, see:

Next steps
Now that you have Azure AD Connect installed you can verify the installation and assign licenses.
Learn more about these features, which were enabled with the installation: Automatic upgrade, Prevent accidental
deletes, and Azure AD Connect Health.
Learn more about these common topics: scheduler and how to trigger sync.
Learn more about Integrating your on-premises identities with Azure Active Directory.

Related documentation
TOPIC LINK

Azure AD Connect overview Integrate your on-premises directories with Azure Active
Directory

Install using customized settings Custom installation of Azure AD Connect

Upgrade from DirSync Upgrade from Azure AD sync tool (DirSync)


TOPIC LINK

Accounts used for installation More about Azure AD Connect credentials and permissions
Custom installation of Azure AD Connect
2/16/2018 • 22 min to read • Edit Online

Azure AD Connect Custom settings is used when you want more options for the installation. It is used if you
have multiple forests or if you want to configure optional features not covered in the express installation. It is
used in all cases where the express installation option does not satisfy your deployment or topology.
Before you start installing Azure AD Connect, make sure to download Azure AD Connect and complete the pre-
requisite steps in Azure AD Connect: Hardware and prerequisites. Also make sure you have required accounts
available as described in Azure AD Connect accounts and permissions.
If customized settings does not match your topology, for example to upgrade DirSync, see related documentation
for other scenarios.

Custom settings installation of Azure AD Connect


Express Settings
On this page, click Customize to start a customized settings installation.
Install required components
When you install the synchronization services, you can leave the optional configuration section unchecked and
Azure AD Connect sets up everything automatically. It sets up a SQL Server 2012 Express LocalDB instance, create
the appropriate groups, and assign permissions. If you wish to change the defaults, you can use the following
table to understand the optional configuration options that are available.
OPTIONAL CONFIGURATION DESCRIPTION

Use an existing SQL Server Allows you to specify the SQL Server name and the instance
name. Choose this option if you already have a database
server that you would like to use. Enter the instance name
followed by a comma and port number in Instance Name if
your SQL Server does not have browsing enabled.

Use an existing service account By default Azure AD Connect uses a virtual service account
for the synchronization services to use. If you use a remote
SQL server or use a proxy that requires authentication, you
need to use a managed service account or use a service
account in the domain and know the password. In those
cases, enter the account to use. Make sure the user running
the installation is an SA in SQL so a login for the service
account can be created. See Azure AD Connect accounts and
permissions.
With the latest build, provisioning the database can now be
performed out of band by the SQL administrator and then
installed by the Azure AD Connect administrator with
database owner rights. For more information see Install
Azure AD Connect using SQL delegated administrator
permissions.

Specify custom sync groups By default Azure AD Connect creates four groups local to the
server when the synchronization services are installed. These
groups are: Administrators group, Operators group, Browse
group, and the Password Reset Group. You can specify your
own groups here. The groups must be local on the server
and cannot be located in the domain.

User sign-in
After installing the required components, you are asked to select your users single sign-on method. The following
table provides a brief description of the available options. For a full description of the sign-in methods, see User
sign-in.
SINGLE SIGN ON OPTION DESCRIPTION

Password Hash Sync Users are able to sign in to Microsoft cloud services, such as
Office 365, using the same password they use in their on-
premises network. The users passwords are synchronized to
Azure AD as a password hash and authentication occurs in
the cloud. See Password hash synchronization for more
information.

Pass-through Authentication Users are able to sign in to Microsoft cloud services, such as
Office 365, using the same password they use in their on-
premises network. The users password is passed through to
the on-premises Active Directory domain controller to be
validated.

Federation with AD FS Users are able to sign in to Microsoft cloud services, such as
Office 365, using the same password they use in their on-
premises network. The users are redirected to their on-
premises AD FS instance to sign in and authentication occurs
on-premises.

Do not configure No user sign-in feature is installed and configured. Choose


this option if you already have a 3rd party federation server
or another existing solution in place.

Enable Single Sign on This options is available with both password sync and Pass-
through authentication and provides a single sign on
experience for desktop users on the corporate network. See
Single sign-on for more information.
Note for AD FS customers this option is not available because
AD FS already offers the same level of single sign on.

Connect to Azure AD
On the Connect to Azure AD screen, enter a global admin account and password. If you selected Federation with
AD FS on the previous page, do not sign in with an account in a domain you plan to enable for federation. A
recommendation is to use an account in the default onmicrosoft.com domain, which comes with your Azure AD
directory.
This account is only used to create a service account in Azure AD and is not used after the wizard has completed.

If your global admin account has MFA enabled, then you need to provide the password again in the sign-in
popup and complete the MFA challenge. The challenge could be a providing a verification code or a phone call.
The global admin account can also have Privileged Identity Management enabled.
If you receive an error and have problems with connectivity, then see Troubleshoot connectivity problems.

Pages under the Sync section


Connect your directories
To connect to your Active Directory Domain Service, Azure AD Connect needs the forest name and credentials of
an account with sufficient permissions.
After entering the forest name and clicking Add Directory, a pop-up dialog appears and prompts you with the
following options:

OPTION DESCRIPTION

Create new account Select this option if you want Azure AD Connect wizard to
create the AD DS account required by Azure AD Connect for
connecting to the AD forest during directory synchronization.
When this option is selected, enter the username and
password for an enterprise admin account. The enterprise
admin account provided will be used by Azure AD Connect
wizard to create the required AD DS account. You can enter
the domain part in either NetBios or FQDN format, that is,
FABRIKAM\administrator or fabrikam.com\administrator.

Use existing account Select this option if you want to provide an existing AD DS
account to be used Azure AD Connect for connecting to the
AD forest during directory synchronization. You can enter the
domain part in either NetBios or FQDN format, that is,
FABRIKAM\syncuser or fabrikam.com\syncuser. This account
can be a regular user account because it only needs the
default read permissions. However, depending on your
scenario, you may need more permissions. For more
information, see Azure AD Connect Accounts and
permissions.
Azure AD sign-in configuration
This page allows you to review the UPN domains present in on-premises AD DS and which have been verified in
Azure AD. This page also allows you to configure the attribute to use for the userPrincipalName.

Review every domain marked Not Added and Not Verified. Make sure those domains you use have been
verified in Azure AD. Click the Refresh symbol when you have verified your domains. For more information, see
add and verify the domain
UserPrincipalName - The attribute userPrincipalName is the attribute users use when they sign in to Azure AD
and Office 365. The domains used, also known as the UPN-suffix, should be verified in Azure AD before the users
are synchronized. Microsoft recommends to keep the default attribute userPrincipalName. If this attribute is non-
routable and cannot be verified, then it is possible to select another attribute. You can for example select email as
the attribute holding the sign-in ID. Using another attribute than userPrincipalName is known as Alternate ID.
The Alternate ID attribute value must follow the RFC822 standard. An Alternate ID can be used with both
password sync and federation. The attribute must not be defined in Active Directory as multi-valued, even if it
only has a single value.

NOTE
When you enable Pass-through Authentication you must have at least one verified domain in order to continue through
the wizard.

WARNING
Using an Alternate ID is not compatible with all Office 365 workloads. For more information, refer to Configuring Alternate
Login ID.

Domain and OU filtering


By default all domains and OUs are synchronized. If there are some domains or OUs you do not want to
synchronize to Azure AD, you can unselect these domains and OUs.

This page in the wizard is configuring domain-based and OU-based filtering. If you plan to make changes, then
see domain-based filtering and ou-based filtering before you make these changes. Some OUs are essential for
the functionality and should not be unselected.
If you use OU-based filtering with Azure AD Connect version before 1.1.524.0, new OUs added later are
synchronized by default. If you want the behavior that new OUs should not be synchronized, then you can
configure it after the wizard has completed with ou-based filtering. For Azure AD Connect version 1.1.524.0 or
after, you can indicate whether you want new OUs to be synchronized or not.
If you plan to use group-based filtering, then make sure the OU with the group is included and not filtered with
OU-filtering. OU filtering is evaluated before group-based filtering.
It is also possible that some domains are not reachable due to firewall restrictions. These domains are unselected
by default and have a warning.

If you see this warning, make sure that these domains are indeed unreachable and the warning is expected.
Uniquely identifying your users
Select how users should be identified in your on-premises directories
The Matching across forests feature allows you to define how users from your AD DS forests are represented in
Azure AD. A user might either be represented only once across all forests or have a combination of enabled and
disabled accounts. The user might also be represented as a contact in some forests.

SETTING DESCRIPTION

Users are only represented once across all forests All users are created as individual objects in Azure AD. The
objects are not joined in the metaverse.

Mail attribute This option joins users and contacts if the mail attribute has
the same value in different forests. Use this option when your
contacts have been created using GALSync. If this option is
chosen, User objects whose Mail attribute aren't populated
will not be synchronized to Azure AD.
SETTING DESCRIPTION

ObjectSID and msExchangeMasterAccountSID/ msRTCSIP- This option joins an enabled user in an account forest with a
OriginatorSid disabled user in a resource forest. In Exchange, this
configuration is known as a linked mailbox. This option can
also be used if you only use Lync and Exchange is not
present in the resource forest.

sAMAccountName and MailNickName This option joins on attributes where it is expected the sign-
in ID for the user can be found.

A specific attribute This option allows you to select your own attribute. If this
option is chosen, User objects whose (selected) attribute
aren't populated will not be synchronized to Azure AD.
Limitation: Make sure to pick an attribute that already can
be found in the metaverse. If you pick a custom attribute
(not in the metaverse), the wizard cannot complete.

Select how users should be identified with Azure AD - Source Anchor


The attribute sourceAnchor is an attribute that is immutable during the lifetime of a user object. It is the primary
key linking the on-premises user with the user in Azure AD.

SETTING DESCRIPTION

Let Azure manage the source anchor for me Select this option if you want Azure AD to pick the attribute
for you. If you select this option, Azure AD Connect wizard
applies the sourceAnchor attribute selection logic described
in article section Azure AD Connect: Design concepts - Using
msDS-ConsistencyGuid as sourceAnchor. The wizard informs
you which attribute has been picked as the Source Anchor
attribute after Custom installation completes.

A specific attribute Select this option if you wish to specify an existing AD


attribute as the sourceAnchor attribute.

Since the attribute cannot be changed, you must plan for a good attribute to use. A good candidate is objectGUID.
This attribute is not changed, unless the user account is moved between forests/domains. In a multi-forest
environment where you move accounts between forests, another attribute must be used, such as an attribute
with the employeeID. Avoid attributes that would change when a person marries or change assignments. You
cannot use attributes with an @-sign, so email and userPrincipalName cannot be used. The attribute is also case-
sensitive so when you move an object between forests, make sure to preserve the upper/lower case. Binary
attributes are base64-encoded, but other attribute types remain in its unencoded state. In federation scenarios
and some Azure AD interfaces, this attribute is also known as immutableID. More information about the source
anchor can be found in the design concepts.
Sync filtering based on groups
The filtering on groups feature allows you to sync only a small subset of objects for a pilot. To use this feature,
create a group for this purpose in your on-premises Active Directory. Then add users and groups that should be
synchronized to Azure AD as direct members. You can later add and remove users to this group to maintain the
list of objects that should be present in Azure AD. All objects you want to synchronize must be a direct member of
the group. Users, groups, contacts, and computers/devices must all be direct members. Nested group
membership is not resolved. When you add a group as a member, only the group itself is added and not its
members.
WARNING
This feature is only intended to support a pilot deployment. Do not use it in a full-blown production deployment.

In a full-blown production deployment, it is going to be hard to maintain a single group with all objects to
synchronize. Instead you should use one of the methods in Configure filtering.
Optional Features
This screen allows you to select the optional features for your specific scenarios.
WARNING
If you currently have DirSync or Azure AD Sync active, do not activate any of the writeback features in Azure AD Connect.

OPTIONAL FEATURES DESCRIPTION

Exchange Hybrid Deployment The Exchange Hybrid Deployment feature allows for the co-
existence of Exchange mailboxes both on-premises and in
Office 365. Azure AD Connect is synchronizing a specific set
of attributes from Azure AD back into your on-premises
directory.

Exchange Mail Public Folders The Exchange Mail Public Folders feature allows you to
synchronize mail-enabled Public Folder objects from your on-
premises Active Directory to Azure AD.

Azure AD app and attribute filtering By enabling Azure AD app and attribute filtering, the set of
synchronized attributes can be tailored. This option adds two
more configuration pages to the wizard. For more
information, see Azure AD app and attribute filtering.

Password synchronization If you selected federation as the sign-in solution, then you
can enable this option. Password synchronization can then be
used as a backup option. For additional information, see
Password synchronization.
If you selected Pass-through Authentication this option can
also be enabled to ensure support for legacy clients and as a
backup option. For additional information, see Password
synchronization.
OPTIONAL FEATURES DESCRIPTION

Password writeback By enabling password writeback, password changes that


originate in Azure AD is written back to your on-premises
directory. For more information, see Getting started with
password management.

Group writeback If you use the Office 365 Groups feature, then you can have
these groups represented in your on-premises Active
Directory. This option is only available if you have Exchange
present in your on-premises Active Directory. For more
information, see Group writeback.

Device writeback Allows you to writeback device objects in Azure AD to your


on-premises Active Directory for conditional access scenarios.
For more information, see Enabling device writeback in Azure
AD Connect.

Directory extension attribute sync By enabling directory extensions attribute sync, attributes
specified are synced to Azure AD. For more information, see
Directory extensions.

Azure AD app and attribute filtering


If you want to limit which attributes to synchronize to Azure AD, then start by selecting which services you are
using. If you make configuration changes on this page, a new service has to be selected explicitly by rerunning
the installation wizard.

Based on the services selected in the previous step, this page shows all attributes that are synchronized. This list is
a combination of all object types being synchronized. If there are some particular attributes you need to not
synchronize, you can unselect those attributes.
WARNING
Removing attributes can impact functionality. For best practices and recommendations, see attributes synchronized.

Directory Extension attribute sync


You can extend the schema in Azure AD with custom attributes added by your organization or other attributes in
Active Directory. To use this feature, select Directory Extension attribute sync on the Optional Features page.
You can select more attributes to sync on this page.
For more information, see Directory extensions.
Enabling Single sign on (SSO )
Configuring single sign-on for use with Password Synchronization or Pass-through authentication is a simple
process that you only need to complete once for each forest that is being synchronized to Azure AD.
Configuration involves two steps as follows:
1. Create the necessary computer account in your on-premises Active Directory.
2. Configure the intranet zone of the client machines to support single sign on.
Create the computer account in Active Directory
For each forest that has been added in Azure AD Connect, you will need to supply Domain Administrator
credentials so that the computer account can be created in each forest. The credentials are only used to create the
account and are not stored or used for any other operation. Simply add the credentials on the Enable Single
sign on page of the Azure AD Connect wizard as shown:
NOTE
You can skip a particular forest if you do not wish to use Single sign on with that forest.

Configure the Intranet Zone for client machines


To ensure that the client sign-ins automatically in the intranet zone you need to ensure that two URLs are part of
the intranet zone. This ensures that the domain joined computer automatically sends a Kerberos ticket to Azure
AD when it is connected to the corporate network. On a computer that has the Group Policy management tools.
1. Open the Group Policy Management tools
2. Edit the Group policy that will be applied to all users. For example, the Default Domain Policy.
3. Navigate to User Configuration\Administrative Templates\Windows Components\Internet
Explorer\Internet Control Panel\Security Page and select Site to Zone Assignment List per the image
below.
4. Enable the policy, and enter the following two items in the dialog box.

Value: `https://autologon.microsoftazuread-sso.com`
Data: 1
Value: `https://aadg.windows.net.nsatc.net`
Data: 1

5. It should look similar to the following:


6. Click Ok twice.

Configuring federation with AD FS


Configuring AD FS with Azure AD Connect is simple with just a few clicks. The following is required before the
configuration.
A Windows Server 2012 R2 or later server for the federation server with remote management enabled
A Windows Server 2012 R2 or later server for the Web Application Proxy server with remote management
enabled
An SSL certificate for the federation service name you intend to use (for example sts.contoso.com)

NOTE
You can update SSL certificate for your AD FS farm using Azure AD Connect even if you do not use it to manage your
federation trust.

AD FS configuration pre -requisites


To configure your AD FS farm using Azure AD Connect, ensure WinRM is enabled on the remote servers. Make
sure you have completed the other tasks in federation prerequisites. In addition, go through the ports
requirement listed in Table 3 - Azure AD Connect and Federation Servers/WAP.
Create a new AD FS farm or use an existing AD FS farm
You can use an existing AD FS farm or you can choose to create a new AD FS farm. If you choose to create a new
one, you are required to provide the SSL certificate. If the SSL certificate is protected by a password, you are
prompted for the password.
If you choose to use an existing AD FS farm, you are taken directly to the configuring the trust relationship
between AD FS and Azure AD screen.

NOTE
Azure AD Connect can be used to manage only one AD FS farm. If you have existing federation trust with Azure AD
configured on the selected AD FS farm, the trust will be re-created again from scratch by Azure AD Connect.

Specify the AD FS servers


Enter the servers that you want to install AD FS on. You can add one or more servers based on your capacity
planning needs. Join all AD FS servers (not required for the WAP servers) to Active Directory before you perform
this configuration. Microsoft recommends installing a single AD FS server for test and pilot deployments. Then
add and deploy more servers to meet your scaling needs by running Azure AD Connect again after initial
configuration.

NOTE
Ensure that all your servers are joined to an AD domain before you do this configuration.
Specify the Web Application Proxy servers
Enter the servers that you want as your Web Application proxy servers. The web application proxy server is
deployed in your DMZ (extranet facing) and supports authentication requests from the extranet. You can add one
or more servers based on your capacity planning needs. Microsoft recommends installing a single Web
application proxy server for test and pilot deployments. Then add and deploy more servers to meet your scaling
needs by running Azure AD Connect again after initial configuration. We recommend having an equivalent
number of proxy servers to satisfy authentication from the intranet.

NOTE
If the account you use is not a local admin on the WAP servers, then you are prompted for admin credentials.
Ensure that there is HTTP/HTTPS connectivity between the Azure AD Connect server and the Web Application Proxy server
before you run this step.
Ensure that there is HTTP/HTTPS connectivity between the Web Application Server and the AD FS server to allow
authentication requests to flow through.
You are prompted to enter credentials so that the web application server can establish a secure connection to the
AD FS server. These credentials need to be a local administrator on the AD FS server.

Specify the service account for the AD FS service


The AD FS service requires a domain service account to authenticate users and lookup user information in Active
Directory. It can support two types of service accounts:
Group Managed Service Account - Introduced in Active Directory Domain Services with Windows Server
2012. This type of account provides services, such as AD FS, a single account without needing to update the
account password regularly. Use this option if you already have Windows Server 2012 domain controllers in
the domain that your AD FS servers belong to.
Domain User Account - This type of account requires you to provide a password and regularly update the
password when the password changes or expires. Use this option only when you do not have Windows Server
2012 domain controllers in the domain that your AD FS servers belong to.
If you selected Group Managed Service Account and this feature has never been used in Active Directory, you are
prompted for Enterprise Admin credentials. These credentials are used to initiate the key store and enable the
feature in Active Directory.

NOTE
Azure AD Connect performs a check to detect if the AD FS service is already registered as a SPN in the domain. AD DS will
not allow duplicate SPN’s to be registered at once. If a duplicate SPN is found, you will not be able to proceed further until
the SPN is removed.

Select the Azure AD domain that you wish to federate


This configuration is used to setup the federation relationship between AD FS and Azure AD. It configures AD FS
to issue security tokens to Azure AD and configures Azure AD to trust the tokens from this specific AD FS
instance. This page only allows you to configure a single domain in the initial installation. You can configure more
domains later by running Azure AD Connect again.
Verify the Azure AD domain selected for federation
When you select the domain to be federated, Azure AD Connect provides you with necessary information to
verify an unverified domain. See Add and verify the domain for how to use this information.
NOTE
AD Connect tries to verify the domain during the configure stage. If you continue to configure without adding the
necessary DNS records, the wizard is not able to complete the configuration.

Configure and verify pages


The configuration happens on this page.

NOTE
Before you continue installation and if you configured federation, make sure that you have configured Name resolution for
federation servers.

Staging mode
It is possible to setup a new sync server in parallel with staging mode. It is only supported to have one sync
server exporting to one directory in the cloud. But if you want to move from another server, for example one
running DirSync, then you can enable Azure AD Connect in staging mode. When enabled, the sync engine import
and synchronize data as normal, but it does not export anything to Azure AD or AD. The features password sync
and password writeback are disabled while in staging mode.

While in staging mode, it is possible to make required changes to the sync engine and review what is about to be
exported. When the configuration looks good, run the installation wizard again and disable staging mode. Data is
now exported to Azure AD from this server. Make sure to disable the other server at the same time so only one
server is actively exporting.
For more information, see Staging mode.
Verify your federation configuration
Azure AD Connect verifies the DNS settings for you when you click the Verify button.
Intranet connectivity checks
Resolve federation FQDN: Azure AD Connect checks if the federation FQDN can be resolved by DNS to ensure
connectivity. If Azure AD Connect cannot resolve the FQDN, the verification will fail. Ensure that a DNS record
is present for the federation service FQDN in order to successfully complete the verification.
DNS A record: Azure AD Connect checks if there is an A record for your federation service. In the absence of
an A record, the verification will fail. Create an A record and not CNAME record for your federation FQDN in
order to successfully complete the verification.
Extranet connectivity checks
Resolve federation FQDN: Azure AD Connect checks if the federation FQDN can be resolved by DNS to ensure
connectivity.
In addition, perform the following verification steps:
Validate that you can sign in from a browser from a domain joined machine on the intranet: Connect to
https://myapps.microsoft.com and verify the sign-in with your logged in account. The built-in AD DS
administrator account is not synchronized and cannot be used for verification.
Validate that you can sign in from a device from the extranet. On a home machine or a mobile device, connect
to https://myapps.microsoft.com and supply your credentials.
Validate rich client sign-in. Connect to https://testconnectivity.microsoft.com, choose the Office 365 tab and
chose the Office 365 Single Sign-On Test.

Next steps
After the installation has completed, sign out and sign in again to Windows before you use Synchronization
Service Manager or Synchronization Rule Editor.
Now that you have Azure AD Connect installed you can verify the installation and assign licenses.
Learn more about these features, which were enabled with the installation: Prevent accidental deletes and Azure
AD Connect Health.
Learn more about these common topics: scheduler and how to trigger sync.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect: Upgrade from DirSync
1/17/2018 • 10 min to read • Edit Online

Azure AD Connect is the successor to DirSync. You find the ways you can upgrade from DirSync in this topic.
These steps do not work for upgrading from another release of Azure AD Connect or from Azure AD Sync.
Before you start installing Azure AD Connect, make sure to download Azure AD Connect and complete the pre-
requisite steps in Azure AD Connect: Hardware and prerequisites. In particular, you want to read about the
following, since these areas are different from DirSync:
The required version of .Net and PowerShell. Newer versions are required to be on the server than what
DirSync needed.
The proxy server configuration. If you use a proxy server to reach the internet, this setting must be configured
before you upgrade. DirSync always used the proxy server configured for the user installing it, but Azure AD
Connect uses machine settings instead.
The URLs required to be open in the proxy server. For basic scenarios, those scenarios also supported by
DirSync, the requirements are the same. If you want to use any of the new features included with Azure AD
Connect, some new URLs must be opened.

NOTE
Once you have enabled your new Azure AD Connect server to start synchronizing changes to Azure AD, you must not roll
back to using DirSync or Azure AD Sync. Downgrading from Azure AD Connect to legacy clients including DirSync and Azure
AD Sync is not supported and can lead to issues such as data loss in Azure AD.

If you are not upgrading from DirSync, see related documentation for other scenarios.

Upgrade from DirSync


Depending on your current DirSync deployment, there are different options for the upgrade. If the expected
upgrade time is less than three hours, then the recommendation is to do an in-place upgrade. If the expected
upgrade time is more than three hours, then the recommendation is to do a parallel deployment on another
server. It is estimated that if you have more than 50,000 objects it takes more than three hours to do the upgrade.

SCENARIO

In-place upgrade

Parallel deployment

NOTE
When you plan to upgrade from DirSync to Azure AD Connect, do not uninstall DirSync yourself before the upgrade. Azure
AD Connect will read and migrate the configuration from DirSync and uninstall after inspecting the server.

In-place upgrade
The expected time to complete the upgrade is displayed by the wizard. This estimate is based on the assumption
that it takes three hours to complete an upgrade for a database with 50,000 objects (users, contacts, and groups).
If the number of objects in your database is less than 50,000, then Azure AD Connect recommends an in-place
upgrade. If you decide to continue, your current settings are automatically applied during upgrade and your server
automatically resumes active synchronization.
If you want to do a configuration migration and do a parallel deployment, then you can override the in-place
upgrade recommendation. You might for example take the opportunity to refresh the hardware and operating
system. For more information, see the parallel deployment section.
Parallel deployment
If you have more than 50,000 objects, then a parallel deployment is recommended. This deployment avoids any
operational delays experienced by your users. The Azure AD Connect installation attempts to estimate the
downtime for the upgrade, but if you've upgraded DirSync in the past, your own experience is likely to be the best
guide.
Supported DirSync configurations to be upgraded
The following configuration changes are supported with upgraded DirSync:
Domain and OU filtering
Alternate ID (UPN)
Password sync and Exchange hybrid settings
Your forest/domain and Azure AD settings
Filtering based on user attributes
The following change cannot be upgraded. If you have this configuration, the upgrade is blocked:
Unsupported DirSync changes, for example removed attributes and using a custom extension DLL

In those cases, the recommendation is to install a new Azure AD Connect server in staging mode and verify the old
DirSync and new Azure AD Connect configuration. Reapply any changes using custom configuration, as described
in Azure AD Connect Sync custom configuration.
The passwords used by DirSync for the service accounts cannot be retrieved and are not migrated. These
passwords are reset during the upgrade.
High-level steps for upgrading from DirSync to Azure AD Connect
1. Welcome to Azure AD Connect
2. Analysis of current DirSync configuration
3. Collect Azure AD global admin password
4. Collect credentials for an enterprise admin account (only used during the installation of Azure AD Connect)
5. Installation of Azure AD Connect
Uninstall DirSync (or temporarily disable it)
Install Azure AD Connect
Optionally begin synchronization
Additional steps are required when:
You're currently using Full SQL Server - local or remote
You have more than 50,000 objects in scope for synchronization

In-place upgrade
1. Launch the Azure AD Connect installer (MSI).
2. Review and agree to license terms and privacy notice.

3. Click next to begin analysis of your existing DirSync installation.


4. When the analysis completes, you see the recommendations on how to proceed.
If you use SQL Server Express and have less than 50,000 objects, the following screen is shown:

If you use a full SQL Server for DirSync, you see this page instead:
The information regarding the existing SQL Server database server being used by DirSync is displayed.
Make appropriate adjustments if needed. Click Next to continue the installation.
If you have more than 50,000 objects, you see this screen instead:

To proceed with an in-place upgrade, click the checkbox next to this message: Continue upgrading
DirSync on this computer. To do a parallel deployment instead, you export the DirSync configuration
settings and move the configuration to the new server.
5. Provide the password for the account you currently use to connect to Azure AD. This must be the account
currently used by DirSync.
If you receive an error and have problems with connectivity, see Troubleshoot connectivity problems.
6. Provide an enterprise admin account for Active Directory.

7. You're now ready to configure. When you click Upgrade, DirSync is uninstalled and Azure AD Connect is
configured and begins synchronizing.
8. After the installation has completed, sign out and sign in again to Windows before you use Synchronization
Service Manager, Synchronization Rule Editor, or try to make any other configuration changes.

Parallel deployment
Export the DirSync configuration
Parallel deployment with more than 50,000 objects
If you have more than 50,000 objects, then the Azure AD Connect installation recommends a parallel deployment.
A screen similar to the following is displayed:
If you want to proceed with parallel deployment, you need to perform the following steps:
Click the Export settings button. When you install Azure AD Connect on a separate server, these settings are
migrated from your current DirSync to your new Azure AD Connect installation.
Once your settings have been successfully exported, you can exit the Azure AD Connect wizard on the DirSync
server. Continue with the next step to install Azure AD Connect on a separate server
Parallel deployment with less than 50,000 objects
If you have less than 50,000 objects but still want to do a parallel deployment, then do the following:
1. Run the Azure AD Connect installer (MSI).
2. When you see the Welcome to Azure AD Connect screen, exit the installation wizard by clicking the "X" in
the top right corner of the window.
3. Open a command prompt.
4. From the install location of Azure AD Connect (Default: C:\Program Files\Microsoft Azure Active Directory
Connect) execute the following command: AzureADConnect.exe /ForceExport .
5. Click the Export settings button. When you install Azure AD Connect on a separate server, these settings are
migrated from your current DirSync to your new Azure AD Connect installation.
Once your settings have been successfully exported, you can exit the Azure AD Connect wizard on the DirSync
server. Continue with the next step to install Azure AD Connect on a separate server.
Install Azure AD Connect on separate server
When you install Azure AD Connect on a new server, the assumption is that you want to perform a clean install of
Azure AD Connect. Since you want to use the DirSync configuration, there are some extra steps to take:
1. Run the Azure AD Connect installer (MSI).
2. When you see the Welcome to Azure AD Connect screen, exit the installation wizard by clicking the "X" in
the top right corner of the window.
3. Open a command prompt.
4. From the install location of Azure AD Connect (Default: C:\Program Files\Microsoft Azure Active Directory
Connect) execute the following command: AzureADConnect.exe /migrate . The Azure AD Connect installation
wizard starts and presents you with the following screen:
5. Select the settings file that exported from your DirSync installation.
6. Configure any advanced options including:
A custom installation location for Azure AD Connect.
An existing instance of SQL Server (Default: Azure AD Connect installs SQL Server 2012 Express). Do not
use the same database instance as your DirSync server.
A service account used to connect to SQL Server (If your SQL Server database is remote then this
account must be a domain service account). These options can be seen on this screen:

7. Click Next.
8. On the Ready to configure page, leave the Start the synchronization process as soon as the
configuration completes checked. The server is now in staging mode so changes are not exported to Azure
AD.
9. Click Install.
10. After the installation has completed, sign out and sign in again to Windows before you use Synchronization
Service Manager, Synchronization Rule Editor, or try to make any other configuration changes.

NOTE
Synchronization between Windows Server Active Directory and Azure Active Directory begins, but no changes are exported
to Azure AD. Only one synchronization tool can be actively exporting changes at a time. This state is called staging mode.

Verify that Azure AD Connect is ready to begin synchronization


To verify that Azure AD Connect is ready to take over from DirSync, you need to open Synchronization Service
Manager in the group Azure AD Connect from the start menu.
In the application, go to the Operations tab. On this tab, confirm that the following operations have completed:
Import on the AD Connector
Import on the Azure AD Connector
Full Sync on the AD Connector
Full Sync on the Azure AD Connector

Review the result from these operations and ensure there are no errors.
If you want to see and inspect the changes that are about to be exported to Azure AD, then read how to verify the
configuration under staging mode. Make required configuration changes until you do not see anything
unexpected.
You are ready to switch from DirSync to Azure AD when you have completed these steps and are happy with the
result.
Uninstall DirSync (old server)
In Programs and features find Windows Azure Active Directory sync tool
Uninstall Windows Azure Active Directory sync tool
The uninstallation might take up to 15 minutes to complete.
If you prefer to uninstall DirSync later, you can also temporarily shut down the server or disable the service. If
something goes wrong, this method allows you to re-enable it. However, it is not expected that the next step will
fail so this should not be needed.
With DirSync uninstalled or disabled, there is no active server exporting to Azure AD. The next step to enable
Azure AD Connect must be completed before any changes in your on-premises Active Directory will continue to
be synchronized to Azure AD.
Enable Azure AD Connect (new server)
After installation, reopening Azure AD connect will allow you to make additional configuration changes. Start
Azure AD Connect from the start menu or from the shortcut on the desktop. Make sure you do not try to run the
installation MSI again.
You should see the following:

Select Configure staging mode.


Turn off staging by unchecking the Enabled staging mode checkbox.

Click the Next button


On the confirmation page, click the install button.
Azure AD Connect is now your active server and you must not switch back to using your existing DirSync server.

Next steps
Now that you have Azure AD Connect installed you can verify the installation and assign licenses.
Learn more about these new features, which were enabled with the installation: Automatic upgrade, Prevent
accidental deletes, and Azure AD Connect Health.
Learn more about these common topics: scheduler and how to trigger sync.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect: Upgrade from a previous version
to the latest
1/17/2018 • 9 min to read • Edit Online

This topic describes the different methods that you can use to upgrade your Azure Active Directory (Azure AD)
Connect installation to the latest release. We recommend that you keep yourself current with the releases of Azure
AD Connect. You also use the steps in the Swing migration section when you make a substantial configuration
change.
If you want to upgrade from DirSync, see Upgrade from Azure AD sync tool (DirSync) instead.
There are a few different strategies that you can use to upgrade Azure AD Connect.

METHOD DESCRIPTION

Automatic upgrade This is the easiest method for customers with an express
installation.

In-place upgrade If you have a single server, you can upgrade the installation
in-place on the same server.

Swing migration With two servers, you can prepare one of the servers with the
new release or configuration, and change the active server
when you're ready.

For permissions information, see the permissions required for an upgrade.

NOTE
After you've enabled your new Azure AD Connect server to start synchronizing changes to Azure AD, you must not roll back
to using DirSync or Azure AD Sync. Downgrading from Azure AD Connect to legacy clients, including DirSync and Azure AD
Sync, isn't supported and can lead to issues such as data loss in Azure AD.

In-place upgrade
An in-place upgrade works for moving from Azure AD Sync or Azure AD Connect. It doesn't work for moving from
DirSync or for a solution with Forefront Identity Manager (FIM) + Azure AD Connector.
This method is preferred when you have a single server and less than about 100,000 objects. If there are any
changes to the out-of-box sync rules, a full import and full synchronization occur after the upgrade. This method
ensures that the new configuration is applied to all existing objects in the system. This run might take a few hours,
depending on the number of objects that are in scope of the sync engine. The normal delta synchronization
scheduler (which synchronizes every 30 minutes by default) is suspended, but password synchronization
continues. You might consider doing the in-place upgrade during a weekend. If there are no changes to the out-of-
box configuration with the new Azure AD Connect release, then a normal delta import/sync starts instead.
If you've made changes to the out-of-box synchronization rules, then these rules are set back to the default
configuration on upgrade. To make sure that your configuration is kept between upgrades, make sure that you
make changes as they're described in Best practices for changing the default configuration.
During in-place upgrade, there may be changes introduced that require specific synchronization activities
(including Full Import step and Full Synchronization step) to be executed after upgrade completes. To defer such
activities, refer to section How to defer full synchronization after upgrade.
If you are using Azure AD Connect with non-standard connector (for example, Generic LDAP Connector and
Generic SQL Connector), you must refresh the corresponding connector configuration in the Synchronization
Service Manager after in-place upgrade. For details on how to refresh the connector configuration, refer to article
section Connector Version Release History - Troubleshooting. If you do not refresh the configuration, import and
export run steps will not work correctly for the connector. You will receive the following error in the application
event log with message "Assembly version in AAD Connector configuration ("X.X.XXX.X") is earlier than the actual
version ("X.X.XXX.X") of "C:\Program Files\Microsoft Azure AD
Sync\Extensions\Microsoft.IAM.Connector.GenericLdap.dll".

Swing migration
If you have a complex deployment or many objects, it might be impractical to do an in-place upgrade on the live
system. For some customers, this process might take multiple days--and during this time, no delta changes are
processed. You can also use this method when you plan to make substantial changes to your configuration and
you want to try them out before they're pushed to the cloud.
The recommended method for these scenarios is to use a swing migration. You need (at least) two servers--one
active server and one staging server. The active server (shown with solid blue lines in the following picture) is
responsible for the active production load. The staging server (shown with dashed purple lines) is prepared with
the new release or configuration. When it's fully ready, this server is made active. The previous active server, which
now has the old version or configuration installed, is made into the staging server and is upgraded.
The two servers can use different versions. For example, the active server that you plan to decommission can use
Azure AD Sync, and the new staging server can use Azure AD Connect. If you use swing migration to develop a
new configuration, it's a good idea to have the same versions on the two servers.

NOTE
Some customers prefer to have three or four servers for this scenario. When the staging server is upgraded, you don't have
a backup server for disaster recovery. With three or four servers, you can prepare one set of primary/standby servers with
the new version, which ensures that there is always a staging server that's ready to take over.

These steps also work to move from Azure AD Sync or a solution with FIM + Azure AD Connector. These steps
don't work for DirSync, but the same swing migration method (also called parallel deployment) with steps for
DirSync is in Upgrade Azure Active Directory sync (DirSync).
Use a swing migration to upgrade
1. If you use Azure AD Connect on both servers and plan to only make a configuration change, make sure that
your active server and staging server are both using the same version. That makes it easier to compare
differences later. If you're upgrading from Azure AD Sync, then these servers have different versions. If you're
upgrading from an older version of Azure AD Connect, it's a good idea to start with the two servers that are
using the same version, but it's not required.
2. If you've made a custom configuration and your staging server doesn't have it, follow the steps under Move a
custom configuration from the active server to the staging server.
3. If you're upgrading from an earlier release of Azure AD Connect, upgrade the staging server to the latest
version. If you're moving from Azure AD Sync, then install Azure AD Connect on your staging server.
4. Let the sync engine run full import and full synchronization on your staging server.
5. Verify that the new configuration didn't cause any unexpected changes by using the steps under "Verify" in
Verify the configuration of a server. If something isn't as expected, correct it, run the import and sync, and verify
the data until it looks good, by following the steps.
6. Switch the staging server to be the active server. This is the final step "Switch active server" in Verify the
configuration of a server.
7. If you're upgrading Azure AD Connect, upgrade the server that's now in staging mode to the latest release.
Follow the same steps as before to get the data and configuration upgraded. If you upgraded from Azure AD
Sync, you can now turn off and decommission your old server.
Move a custom configuration from the active server to the staging server
If you've made configuration changes to the active server, you need to make sure that the same changes are
applied to the staging server. To help with this move, you can use the Azure AD Connect configuration
documenter.
You can move the custom sync rules that you've created by using PowerShell. You must apply other changes the
same way on both systems, and you can't migrate the changes. The configuration documenter can help you
comparing the two systems to make sure they are identical. The tool can also help in automating the steps found
in this section.
You need to configure the following things the same way on both servers:
Connection to the same forests
Any domain and OU filtering
The same optional features, such as password sync and password writeback
Move custom synchronization rules
To move custom synchronization rules, do the following:
1. Open Synchronization Rules Editor on your active server.
2. Select a custom rule. Click Export. This brings up a Notepad window. Save the temporary file with a PS1
extension. This makes it a PowerShell script. Copy the PS1 file to the staging server.

3. The Connector GUID is different on the staging server, and you must change it. To get the GUID, start
Synchronization Rules Editor, select one of the out-of-box rules that represent the same connected system,
and click Export. Replace the GUID in your PS1 file with the GUID from the staging server.
4. In a PowerShell prompt, run the PS1 file. This creates the custom synchronization rule on the staging server.
5. Repeat this for all your custom rules.

How to defer full synchronization after upgrade


During in-place upgrade, there may be changes introduced that require specific synchronization activities
(including Full Import step and Full Synchronization step) to be executed. For example, connector schema changes
require full import step and out-of-box synchronization rule changes require full synchronization step to be
executed on affected connectors. During upgrade, Azure AD Connect determines what synchronization activities
are required and records them as overrides. In the following synchronization cycle, the synchronization scheduler
picks up these overrides and executes them. Once an override is successfully executed, it is removed.
There may be situations where you do not want these overrides to take place immediately after upgrade. For
example, you have numerous synchronized objects and you would like these synchronization steps to occur after
business hours. To remove these overrides:
1. During upgrade, uncheck the option Start the synchronization process when configuration
completes. This disables the synchronization scheduler and prevents synchronization cycle from taking
place automatically before the overrides are removed.

2. After upgrade completes, run the following cmdlet to find out what overrides have been added:
Get-ADSyncSchedulerConnectorOverride | fl

NOTE
The overrides are connector-specific. In the following example, Full Import step and Full Synchronization step have
been added to both the on-premises AD Connector and Azure AD Connector.

3. Note down the existing overrides that have been added.


4. To remove the overrides for both full import and full synchronization on an arbitrary connector, run the
following cmdlet:
Set-ADSyncSchedulerConnectorOverride -ConnectorIdentifier <Guid-of-ConnectorIdentifier> -
FullImportRequired $false -FullSyncRequired $false

To remove the overrides on all connectors, execute the following PowerShell script:
foreach ($connectorOverride in Get-ADSyncSchedulerConnectorOverride)
{
Set-ADSyncSchedulerConnectorOverride -ConnectorIdentifier
$connectorOverride.ConnectorIdentifier.Guid -FullSyncRequired $false -FullImportRequired $false
}

5. To resume the scheduler, run the following cmdlet: Set-ADSyncScheduler -SyncCycleEnabled $true

IMPORTANT
Remember to execute the required synchronization steps at your earliest convenience. You can either manually
execute these steps using the Synchronization Service Manager or add the overrides back using the Set-
ADSyncSchedulerConnectorOverride cmdlet.

To add the overrides for both full import and full synchronization on an arbitrary connector, run the following
cmdlet:
Set-ADSyncSchedulerConnectorOverride -ConnectorIdentifier <Guid> -FullImportRequired $true -FullSyncRequired
$true

Next steps
Learn more about integrating your on-premises identities with Azure Active Directory.
Install Azure AD Connect using an existing ADSync
database
12/11/2017 • 6 min to read • Edit Online

Azure AD Connect requires a SQL Server database to store data. You can either use the default SQL Server 2012
Express LocalDB installed with Azure AD Connect or use your own full version of SQL. Previously, when you
installed Azure AD Connect, a new database named ADSync was always created. With Azure AD Connect version
1.1.613.0 (or after), you have the option to install Azure AD Connect by pointing it to an existing ADSync database.

Benefits of using an existing ADSync database


By pointing to an existing ADSync database:
Except for credentials information, synchronization configuration stored in the ADSync database (including
custom synchronization rules, connectors, filtering, and optional features configuration) is automatically
recovered and used during installation. Credentials used by Azure AD Connect to synchronize changes with on-
premises AD and Azure AD are encrypted and can only be accessed by the previous Azure AD Connect server.
All the identity data (associated with connector spaces and metaverse) and synchronization cookies stored in
the ADSync database are also recovered. The newly installed Azure AD Connect server can continue to
synchronize from where the previous Azure AD Connect server left off, instead of having the need to perform a
full sync.

Scenarios where using an existing ADSync database is beneficial


These benefits are useful in the following scenarios:
You have an existing Azure AD Connect deployment. Your existing Azure AD Connect server is no longer
working but the SQL server containing the ADSync database is still functioning. You can install a new Azure AD
Connect server and point it to the existing ADSync database.
You have an existing Azure AD Connect deployment. Your SQL server containing the ADSync database is no
longer functioning. However, you have a recent back up of the database. You can restore the ADSync database
to a new SQL server first. After which, you can install a new Azure AD Connect server and point it to the
restored ADSync database.
You have an existing Azure AD Connect deployment that is using LocalDB. Due to the 10-GB limit imposed by
LocalDB, you would like to migrate to full SQL. You can back up the ADSync database from LocalDB and restore
it to a SQL server. After which, you can reinstall a new Azure AD Connect server and point it to the restored
ADSync database.
You are trying to set up a staging server and wants to make sure its configuration matches that of the current
active server. You can back up the ADSync database and restore it to another SQL server. After which, you can
reinstall a new Azure AD Connect server and point it to the restored ADSync database.

Prerequisite information
Important notes to take note of before you proceed:
Make sure to review the pre-requisites for installing Azure AD Connect at Hardware and prerequisites, and
account and permissions required for installing Azure AD Connect. The permissions required for installing
Azure AD Connect using “use existing database” mode is the same as “custom” installation.
Deploying Azure AD Connect against an existing ADSync database is only supported with full SQL. It is not
supported with SQL Express LocalDB. If you have an existing ADSync database in LocalDB that you wish to use,
you must first backup the ADSync database (LocalDB) and restore it to full SQL. After which, you can deploy
Azure AD Connect against the restored database using this method.
The version of the Azure AD Connect used for installation must satisfy the following criteria:
1.1.613.0 or above, AND
Same or higher than the version of the Azure AD Connect last used with the ADSync database. If the
Azure AD Connect version used for installation is higher than the version last used with the ADSync
database, then a full sync may be required. Full sync is required if there are schema or sync rule changes
between the two versions.
The ADSync database used should contain a synchronization state that is relatively recent. The last
synchronization activity with the existing ADSync database should be within the last three weeks.
When installing Azure AD Connect using “use existing database” method, sign-in method configured on the
previous Azure AD Connect server is not preserved. Further, you cannot configure sign-in method during
installation. You can only configure sign-in method after installation is complete.
You cannot have multiple Azure AD Connect servers share the same ADSync database. The “use existing
database” method allows you to reuse an existing ADSync database with a new Azure AD Connect server. It
does not support sharing.

Steps to install Azure AD Connect with “use existing database” mode


1. Download Azure AD Connect installer (AzureADConnect.MSI) to the Windows server. Double-click the Azure AD
Connect installer to start installing Azure AD Connect.
2. Once the MSI installation completes, the Azure AD Connect wizard starts with the Express mode setup. Close the
screen by clicking the Exit icon.

3. Start a new command prompt or PowerShell session. Navigate to folder \program files\Microsoft Azure AD
Connect. Run command .\AzureADConnect.exe /useexistingdatabase to start the Azure AD Connect wizard in
“Use existing database” setup mode.
4. You are greeted with the Welcome to Azure AD Connect screen. Once you agree to the license terms and
privacy notice, click Continue.

5. On the Install required components screen, the Use an existing SQL Server option is enabled. Specify
the name of the SQL server that is hosting the ADSync database. If the SQL engine instance used to host the
ADSync database is not the default instance on the SQL server, you must specify the SQL engine instance
name. Further, if SQL browsing is not enabled, you must also specify the SQL engine instance port number.
For example:
6. On the Connect to Azure AD screen, you must provide the credentials of a global admin of your Azure AD
directory. The recommendation is to use an account in the default onmicrosoft.com domain. This account is
only used to create a service account in Azure AD and is not used after the wizard has completed.

7. On the Connect your directories screen, the existing AD forest configured for directory synchronization is
listed with a red cross icon beside it. To synchronize changes from an on-premises AD forest, an AD DS
account is required. The Azure AD Connect wizard is unable to retrieve the credentials of the AD DS account
stored in the ADSync database because the credentials are encrypted and can only be decrypted by the
previous Azure AD Connect server. Click Change Credentials to specify the AD DS account for the AD
forest.


8. In the pop-up dialog, you can either (i) provide an Enterprise Admin credential and let Azure AD Connect create
the AD DS account for you, or (ii) create the AD DS account yourself and provide its credential to Azure AD
Connect. Once you have selected an option and provide the necessary credentials, click OK to close the pop-up
dialog.


9. Once the credentials are provided, the red cross icon is replaced with a green tick icon. Click Next.

10. On the Ready to configure screen, click Install.


11. Once installation completes, the Azure AD Connect server is automatically enabled for Staging Mode. It is
recommended that you review the server configuration and pending exports for unexpected changes before
disabling Staging Mode.
Next steps
Now that you have Azure AD Connect installed you can verify the installation and assign licenses.
Learn more about these features, which were enabled with the installation: Prevent accidental deletes and Azure
AD Connect Health.
Learn more about these common topics: scheduler and how to trigger sync.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Install Azure AD Connect using SQL delegated
administrator permissions
2/16/2018 • 2 min to read • Edit Online

Prior to the latest Azure AD Connect build, administrative delegation, when deploying configurations that required
SQL, was not supported. Users who wanted to install Azure AD Connect needed to have server administrator (SA)
permissions on the SQL server.
With the latest release of Azure AD Connect, provisioning the database can now be performed out of band by the
SQL administrator and then installed by the Azure AD Connect administrator with database owner rights.

Before you begin


To use this feature, you need to realize that there are several moving parts and each one may involve a different
administrator in your organization. The following table summarizes the individual roles and their respective duties
in deploying Azure AD Connect with this feature.

ROLE DESCRIPTION

Domain or Forest AD administrator Creates the domain level service account that is used by Azure
AD Connect to run the sync service. For more information on
service accounts, see Accounts and permissions.

SQL administrator Creates the ADSync database and grants login + dbo access
to the Azure AD Connect administrator and the service
account created by the domain/forest admin.

Azure AD Connect administrator Installs Azure AD Connect and specifies the service account
during custom installation.

Steps for installing Azure AD Connect using SQL delegated


permissions
To provision the database out of band and install Azure AD Connect with database owner permissions, use the
following steps.

NOTE
Although it is not required, it is highly recommended that the Latin1_General_CI_AS collation is selected when creating the
database.

1. Have the SQL Administrator create the ADSync database with a case insensitive collation sequence
(Latin1_General_CI_AS). The database must be named ADSync. The recovery model, compatibility level, and
containment type are updated to the correct values when Azure AD Connect is installed. However the collation
sequence must be set correctly by the SQL administrator otherwise Azure AD Connect will block the installation.
To recover the SA must delete and recreate the database.
2. Grant the Azure AD Connect administrator and the domain service account the following permissions:
SQL Login
database owner(dbo) rights.
3. Send an email to the Azure AD Connect administrator indicating the SQL server and instance name that should
be used when installing Azure AD Connect.

Additional information
Once the database is provisioned, the Azure AD Connect administrator can install and configure on-premises
synchronization at their convenience.
In addition to supporting new installations of Azure AD Connect, this feature also enables delegation for any
scenario related to the /UseExistingDatabase flag. For more information on installing Azure AD Connect with an
existing database, see Install Azure AD Connect using an existing ADSync database

Next steps
Getting started with Azure AD Connect using express settings
Custom installation of Azure AD Connect
Install Azure AD Connect using an existing ADSync database
Azure AD Connect: Design concepts
3/8/2018 • 12 min to read • Edit Online

The purpose of this topic is to describe areas that must be thought through during the implementation design of
Azure AD Connect. This topic is a deep dive on certain areas and these concepts are briefly described in other topics
as well.

sourceAnchor
The sourceAnchor attribute is defined as an attribute immutable during the lifetime of an object. It uniquely
identifies an object as being the same object on-premises and in Azure AD. The attribute is also called
immutableId and the two names are used interchangeable.
The word immutable, that is "cannot be changed", is important to this topic. Since this attribute’s value cannot be
changed after it has been set, it is important to pick a design that supports your scenario.
The attribute is used for the following scenarios:
When a new sync engine server is built, or rebuilt after a disaster recovery scenario, this attribute links existing
objects in Azure AD with objects on-premises.
If you move from a cloud-only identity to a synchronized identity model, then this attribute allows objects to
"hard match" existing objects in Azure AD with on-premises objects.
If you use federation, then this attribute together with the userPrincipalName is used in the claim to uniquely
identify a user.
This topic only talks about sourceAnchor as it relates to users. The same rules apply to all object types, but it is only
for users this problem usually is a concern.
Selecting a good sourceAnchor attribute
The attribute value must follow the following rules:
Be less than 60 characters in length
Characters not being a-z, A-Z, or 0-9 are encoded and counted as 3 characters
Not contain a special character: \ ! # $ % & * + / = ? ^ ` { } | ~ < > ( ) ' ; : , [ ] " @ _
Must be globally unique
Must be either a string, integer, or binary
Should not be based on user's name, these change
Should not be case-sensitive and avoid values that may vary by case
Should be assigned when the object is created
If the selected sourceAnchor is not of type string, then Azure AD Connect Base64Encode the attribute value to
ensure no special characters appear. If you use another federation server than ADFS, make sure your server can
also Base64Encode the attribute.
The sourceAnchor attribute is case-sensitive. A value of “JohnDoe” is not the same as “johndoe”. But you should not
have two different objects with only a difference in case.
If you have a single forest on-premises, then the attribute you should use is objectGUID. This is also the attribute
used when you use express settings in Azure AD Connect and also the attribute used by DirSync.
If you have multiple forests and do not move users between forests and domains, then objectGUID is a good
attribute to use even in this case.
If you move users between forests and domains, then you must find an attribute that does not change or can be
moved with the users during the move. A recommended approach is to introduce a synthetic attribute. An attribute
that could hold something that looks like a GUID would be suitable. During object creation, a new GUID is created
and stamped on the user. A custom sync rule can be created in the sync engine server to create this value based on
the objectGUID and update the selected attribute in ADDS. When you move the object, make sure to also copy the
content of this value.
Another solution is to pick an existing attribute you know does not change. Commonly used attributes include
employeeID. If you consider an attribute that contains letters, make sure there is no chance the case (upper case
vs. lower case) can change for the attribute's value. Bad attributes that should not be used include those attributes
with the name of the user. In a marriage or divorce, the name is expected to change, which is not allowed for this
attribute. This is also one reason why attributes such as userPrincipalName, mail, and targetAddress are not
even possible to select in the Azure AD Connect installation wizard. Those attributes also contain the "@" character,
which is not allowed in the sourceAnchor.
Changing the sourceAnchor attribute
The sourceAnchor attribute value cannot be changed after the object has been created in Azure AD and the identity
is synchronized.
For this reason, the following restrictions apply to Azure AD Connect:
The sourceAnchor attribute can only be set during initial installation. If you rerun the installation wizard, this
option is read-only. If you need to change this setting, then you must uninstall and reinstall.
If you install another Azure AD Connect server, then you must select the same sourceAnchor attribute as
previously used. If you have earlier been using DirSync and move to Azure AD Connect, then you must use
objectGUID since that is the attribute used by DirSync.
If the value for sourceAnchor is changed after the object has been exported to Azure AD, then Azure AD Connect
sync throws an error and does not allow any more changes on that object before the issue has been fixed and
the sourceAnchor is changed back in the source directory.

Using msDS-ConsistencyGuid as sourceAnchor


By default, Azure AD Connect (version 1.1.486.0 and older) uses objectGUID as the sourceAnchor attribute.
ObjectGUID is system-generated. You cannot specify its value when creating on-premises AD objects. As explained
in section sourceAnchor, there are scenarios where you need to specify the sourceAnchor value. If the scenarios are
applicable to you, you must use a configurable AD attribute (for example, msDS-ConsistencyGuid) as the
sourceAnchor attribute.
Azure AD Connect (version 1.1.524.0 and after) now facilitates the use of msDS-ConsistencyGuid as sourceAnchor
attribute. When using this feature, Azure AD Connect automatically configures the synchronization rules to:
1. Use msDS-ConsistencyGuid as the sourceAnchor attribute for User objects. ObjectGUID is used for other
object types.
2. For any given on-premises AD User object whose msDS-ConsistencyGuid attribute isn't populated, Azure
AD Connect writes its objectGUID value back to the msDS-ConsistencyGuid attribute in on-premises Active
Directory. After the msDS-ConsistencyGuid attribute is populated, Azure AD Connect then exports the object
to Azure AD.

NOTE
Once an on-premises AD object is imported into Azure AD Connect (that is, imported into the AD Connector Space and
projected into the Metaverse), you cannot change its sourceAnchor value anymore. To specify the sourceAnchor value for a
given on-premises AD object, configure its msDS-ConsistencyGuid attribute before it is imported into Azure AD Connect.
Permission required
For this feature to work, the AD DS account used to synchronize with on-premises Active Directory must be
granted write permission to the msDS-ConsistencyGuid attribute in on-premises Active Directory.
How to enable the ConsistencyGuid feature - New installation
You can enable the use of ConsistencyGuid as sourceAnchor during new installation. This section covers both
Express and Custom installation in details.

NOTE
Only newer versions of Azure AD Connect (1.1.524.0 and after) supports the use of ConsistencyGuid as sourceAnchor during
new installation.

How to enable the ConsistencyGuid feature


Currently, the feature can only be enabled during new Azure AD Connect installation only.
Express Installation
When installing Azure AD Connect with Express mode, the Azure AD Connect wizard automatically determines the
most appropriate AD attribute to use as the sourceAnchor attribute using the following logic:
First, the Azure AD Connect wizard queries your Azure AD tenant to retrieve the AD attribute used as the
sourceAnchor attribute in the previous Azure AD Connect installation (if any). If this information is available,
Azure AD Connect uses the same AD attribute.

NOTE
Only newer versions of Azure AD Connect (1.1.524.0 and after) stores information in your Azure AD tenant about the
sourceAnchor attribute used during installation. Older versions of Azure AD Connect do not.

If information about the sourceAnchor attribute used isn't available, the wizard checks the state of the
msDS-ConsistencyGuid attribute in your on-premises Active Directory. If the attribute isn't configured on
any object in the directory, the wizard uses the msDS-ConsistencyGuid as the sourceAnchor attribute. If the
attribute is configured on one or more objects in the directory, the wizard concludes the attribute is being
used by other applications and is not suitable as sourceAnchor attribute...
In which case, the wizard falls back to using objectGUID as the sourceAnchor attribute.
Once the sourceAnchor attribute is decided, the wizard stores the information in your Azure AD tenant. The
information will be used by future installation of Azure AD Connect.
Once Express installation completes, the wizard informs you which attribute has been picked as the Source Anchor
attribute.
Custom installation
When installing Azure AD Connect with Custom mode, the Azure AD Connect wizard provides two options when
configuring sourceAnchor attribute:
SETTING DESCRIPTION

Let Azure manage the source anchor for me Select this option if you want Azure AD to pick the attribute
for you. If you select this option, Azure AD Connect wizard
applies the same sourceAnchor attribute selection logic used
during Express installation. Similar to Express installation, the
wizard informs you which attribute has been picked as the
Source Anchor attribute after Custom installation completes.

A specific attribute Select this option if you wish to specify an existing AD


attribute as the sourceAnchor attribute.

How to enable the ConsistencyGuid feature - Existing deployment


If you have an existing Azure AD Connect deployment which is using objectGUID as the Source Anchor attribute,
you can switch it to using ConsistencyGuid instead.

NOTE
Only newer versions of Azure AD Connect (1.1.552.0 and after) supports switching from ObjectGuid to ConsistencyGuid as
the Source Anchor attribute.

To switch from objectGUID to ConsistencyGuid as the Source Anchor attribute:


1. Start the Azure AD Connect wizard and click Configure to go to the Tasks screen.
2. Select the Configure Source Anchor task option and click Next.

3. Enter your Azure AD Administrator credentials and click Next.


4. Azure AD Connect wizard analyzes the state of the msDS-ConsistencyGuid attribute in your on-premises
Active Directory. If the attribute isn't configured on any object in the directory, Azure AD Connect concludes
that no other application is currently using the attribute and is safe to use it as the Source Anchor attribute.
Click Next to continue.

5. In the Ready to Configure screen, click Configure to make the configuration change.

6. Once the configuration completes, the wizard indicates that msDS-ConsistencyGuid is now being used as
the Source Anchor attribute.
During the analysis (step 4), if the attribute is configured on one or more objects in the directory, the wizard
concludes the attribute is being used by another application and returns an error as illustrated in the diagram
below. This error can also occur if you have previously enabled the ConsistencyGuid feature on your primary Azure
AD Connect server and you are trying to do the same on your staging server.

If you are certain that the attribute isn't used by other existing applications, you can suppress the error by
restarting the Azure AD Connect wizard with the /SkipLdapSearchcontact specified. To do so, run the following
command in command prompt:

"c:\Program Files\Microsoft Azure Active Directory Connect\AzureADConnect.exe" /SkipLdapSearch

Impact on AD FS or third-party federation configuration


If you are using Azure AD Connect to manage on-premises AD FS deployment, the Azure AD Connect automatically
updates the claim rules to use the same AD attribute as sourceAnchor. This ensures that the ImmutableID claim
generated by ADFS is consistent with the sourceAnchor values exported to Azure AD.
If you are managing AD FS outside of Azure AD Connect or you are using third-party federation servers for
authentication, you must manually update the claim rules for ImmutableID claim to be consistent with the
sourceAnchor values exported to Azure AD as described in article section Modify AD FS claim rules. The wizard
returns the following warning after installation completes:

Adding new directories to existing deployment


Suppose you have deployed Azure AD Connect with the ConsistencyGuid feature enabled, and now you would like
to add another directory to the deployment. When you try to add the directory, Azure AD Connect wizard checks
the state of the mSDS-ConsistencyGuid attribute in the directory. If the attribute is configured on one or more
objects in the directory, the wizard concludes the attribute is being used by other applications and returns an error
as illustrated in the diagram below. If you are certain that the attribute isn't used by existing applications, you need
to contact Support for information on how to suppress the error.
Azure AD sign-in
While integrating your on-premises directory with Azure AD, it is important to understand how the synchronization
settings can affect the way user authenticates. Azure AD uses userPrincipalName (UPN) to authenticate the user.
However, when you synchronize your users, you must choose the attribute to be used for value of
userPrincipalName carefully.
Choosing the attribute for userPrincipalName
When you are selecting the attribute for providing the value of UPN to be used in Azure one should ensure
The attribute values conform to the UPN syntax (RFC 822), that is it should be of the format username@domain
The suffix in the values matches to one of the verified custom domains in Azure AD
In express settings, the assumed choice for the attribute is userPrincipalName. If the userPrincipalName attribute
does not contain the value you want your users to sign in to Azure, then you must choose Custom Installation.
Custom domain state and UPN
It is important to ensure that there is a verified domain for the UPN suffix.
John is a user in contoso.com. You want John to use the on-premises UPN john@contoso.com to sign in to Azure
after you have synced users to your Azure AD directory contoso.onmicrosoft.com. To do so, you need to add and
verify contoso.com as a custom domain in Azure AD before you can start syncing the users. If the UPN suffix of
John, for example contoso.com, does not match a verified domain in Azure AD, then Azure AD replaces the UPN
suffix with contoso.onmicrosoft.com.
Non-routable on-premises domains and UPN for Azure AD
Some organizations have non-routable domains, like contoso.local, or simple single label domains like contoso.
You are not able to verify a non-routable domain in Azure AD. Azure AD Connect can sync to only a verified
domain in Azure AD. When you create an Azure AD directory, it creates a routable domain that becomes default
domain for your Azure AD for example, contoso.onmicrosoft.com. Therefore, it becomes necessary to verify any
other routable domain in such a scenario in case you don't want to sync to the default onmicrosoft.com domain.
Read Add your custom domain name to Azure Active Directory for more info on adding and verifying domains.
Azure AD Connect detects if you are running in a non-routable domain environment and would appropriately warn
you from going ahead with express settings. If you are operating in a non-routable domain, then it is likely that the
UPN of the users have non-routable suffixes too. For example, if you are running under contoso.local, Azure AD
Connect suggests you to use custom settings rather than using express settings. Using custom settings, you are
able to specify the attribute that should be used as UPN to sign in to Azure after the users are synced to Azure AD.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Topologies for Azure AD Connect
2/27/2018 • 9 min to read • Edit Online

This article describes various on-premises and Azure Active Directory (Azure AD) topologies that use Azure AD
Connect sync as the key integration solution. This article includes both supported and unsupported configurations.
Here's the legend for pictures in the article:

DESCRIPTION SYMBOL

On-premises Active Directory forest

On-premises Active Directory with filtered import

Azure AD Connect sync server

Azure AD Connect sync server “staging mode”

GALSync with Forefront Identity Manager (FIM) 2010 or


Microsoft Identity Manager (MIM) 2016

Azure AD Connect sync server, detailed

Azure AD

Unsupported scenario

Single forest, single Azure AD tenant

The most common topology is a single on-premises forest, with one or multiple domains, and a single Azure AD
tenant. For Azure AD authentication, password synchronization is used. The express installation of Azure AD
Connect supports only this topology.
Single forest, multiple sync servers to one Azure AD tenant
Having multiple Azure AD Connect sync servers connected to the same Azure AD tenant is not supported, except
for a staging server. It's unsupported even if these servers are configured to synchronize with a mutually exclusive
set of objects. You might have considered this topology if you can't reach all domains in the forest from a single
server, or if you want to distribute load across several servers.

Multiple forests, single Azure AD tenant

Many organizations have environments with multiple on-premises Active Directory forests. There are various
reasons for having more than one on-premises Active Directory forest. Typical examples are designs with account-
resource forests and the result of a merger or acquisition.
When you have multiple forests, all forests must be reachable by a single Azure AD Connect sync server. You don't
have to join the server to a domain. If necessary to reach all forests, you can place the server in a perimeter
network (also known as DMZ, demilitarized zone, and screened subnet).
The Azure AD Connect installation wizard offers several options to consolidate users who are represented in
multiple forests. The goal is that a user is represented only once in Azure AD. There are some common topologies
that you can configure in the custom installation path in the installation wizard. On the Uniquely identifying
your users page, select the corresponding option that represents your topology. The consolidation is configured
only for users. Duplicated groups are not consolidated with the default configuration.
Common topologies are discussed in the sections about separate topologies, full mesh, and the account-resource
topology.
The default configuration in Azure AD Connect sync assumes:
Each user has only one enabled account, and the forest where this account is located is used to authenticate the
user. This assumption is for both password sync and federation. UserPrincipalName and
sourceAnchor/immutableID come from this forest.
Each user has only one mailbox.
The forest that hosts the mailbox for a user has the best data quality for attributes visible in the Exchange Global
Address List (GAL). If there's no mailbox for the user, any forest can be used to contribute these attribute values.
If you have a linked mailbox, there's also an account in a different forest used for sign-in.
If your environment does not match these assumptions, the following things happen:
If you have more than one active account or more than one mailbox, the sync engine picks one and ignores the
other.
A linked mailbox with no other active account is not exported to Azure AD. The user account is not represented
as a member in any group. A linked mailbox in DirSync is always represented as a normal mailbox. This change
is intentionally a different behavior to better support multiple-forest scenarios.
You can find more details in Understanding the default configuration.
Multiple forests, multiple sync servers to one Azure AD tenant

Having more than one Azure AD Connect sync server connected to a single Azure AD tenant is not supported. The
exception is the use of a staging server.
Multiple forests, separate topologies

In this environment, all on-premises forests are treated as separate entities. No user is present in any other forest.
Each forest has its own Exchange organization, and there's no GALSync between the forests. This topology might
be the situation after a merger/acquisition or in an organization where each business unit operates independently.
These forests are in the same organization in Azure AD and appear with a unified GAL. In the preceding picture,
each object in every forest is represented once in the metaverse and aggregated in the target Azure AD tenant.
Multiple forests: match users
Common to all these scenarios is that distribution and security groups can contain a mix of users, contacts, and
Foreign Security Principals (FSPs). FSPs are used in Active Directory Domain Services (AD DS) to represent
members from other forests in a security group. All FSPs are resolved to the real object in Azure AD.
Multiple forests: full mesh with optional GALSync
A full mesh topology allows users and resources to be located in any forest. Commonly, there are two-way trusts
between the forests.
If Exchange is present in more than one forest, there might be (optionally) an on-premises GALSync solution. Every
user is then represented as a contact in all other forests. GALSync is commonly implemented through FIM 2010 or
MIM 2016. Azure AD Connect cannot be used for on-premises GALSync.
In this scenario, identity objects are joined via the mail attribute. A user who has a mailbox in one forest is joined
with the contacts in the other forests.
Multiple forests: account-resource forest

In an account-resource forest topology, you have one or more account forests with active user accounts. You also
have one or more resource forests with disabled accounts.
In this scenario, one (or more) resource forest trusts all account forests. The resource forest typically has an
extended Active Directory schema with Exchange and Lync. All Exchange and Lync services, along with other shared
services, are located in this forest. Users have a disabled user account in this forest, and the mailbox is linked to the
account forest.

Office 365 and topology considerations


Some Office 365 workloads have certain restrictions on supported topologies:

WORKLOAD RESTRICTIONS
WORKLOAD RESTRICTIONS

Exchange Online For more information about hybrid topologies supported by


Exchange Online, see Hybrid deployments with multiple Active
Directory forests.

Skype for Business When you're using multiple on-premises forests, only the
account-resource forest topology is supported. For more
information, see Environmental requirements for Skype for
Business Server 2015.

If you are a larger organization, then you should consider to use the Office 365 PreferredDataLocation feature. It
allows you to define in which datacenter region the user's resources are located.

Staging server

Azure AD Connect supports installing a second server in staging mode. A server in this mode reads data from all
connected directories but does not write anything to connected directories. It uses the normal synchronization
cycle and therefore has an updated copy of the identity data.
In a disaster where the primary server fails, you can fail over to the staging server. You do this in the Azure AD
Connect wizard. This second server can be located in a different datacenter because no infrastructure is shared with
the primary server. You must manually copy any configuration change made on the primary server to the second
server.
You can use a staging server to test a new custom configuration and the effect that it has on your data. You can
preview the changes and adjust the configuration. When you're happy with the new configuration, you can make
the staging server the active server and set the old active server to staging mode.
You can also use this method to replace the active sync server. Prepare the new server and set it to staging mode.
Make sure it's in a good state, disable staging mode (making it active), and shut down the currently active server.
It's possible to have more than one staging server when you want to have multiple backups in different
datacenters.

Multiple Azure AD tenants


We recommend having a single tenant in Azure AD for an organization. Before you plan to use multiple Azure AD
tenants, see the article Administrative units management in Azure AD. It covers common scenarios where you can
use a single tenant.
There's a 1:1 relationship between an Azure AD Connect sync server and an Azure AD tenant. For each Azure AD
tenant, you need one Azure AD Connect sync server installation. The Azure AD tenant instances are isolated by
design. That is, users in one tenant can't see users in the other tenant. If you want this separation, this is a
supported configuration. Otherwise, you should use the single Azure AD tenant model.
Each object only once in an Azure AD tenant

In this topology, one Azure AD Connect sync server is connected to each Azure AD tenant. The Azure AD Connect
sync servers must be configured for filtering so that each has a mutually exclusive set of objects to operate on. You
can, for example, scope each server to a particular domain or organizational unit.
A DNS domain can be registered in only a single Azure AD tenant. The UPNs of the users in the on-premises Active
Directory instance must also use separate namespaces. For example, in the preceding picture, three separate UPN
suffixes are registered in the on-premises Active Directory instance: contoso.com, fabrikam.com, and
wingtiptoys.com. The users in each on-premises Active Directory domain use a different namespace.

NOTE
Global Address List Synchronization (GalSync) is not done automatically in this topology and requires an additional custom
MIM implementation to ensure each tenant has a complete Global Address List (GAL) in Exchange Online and Skype for
Business Online.

This topology has the following restrictions on otherwise supported scenarios:


Only one of the Azure AD tenants can enable an Exchange hybrid with the on-premises Active Directory
instance.
Windows 10 devices can be associated with only one Azure AD tenant.
The single sign-on (SSO) option for password synchronization and pass-through authentication can be used
with only one Azure AD tenant.
The requirement for a mutually exclusive set of objects also applies to writeback. Some writeback features are not
supported with this topology because they assume a single on-premises configuration. These features include:
Group writeback with default configuration.
Device writeback.
Each object multiple times in an Azure AD tenant

These tasks are unsupported:


Sync the same user to multiple Azure AD tenants.
Make a configuration change so that users in one Azure AD tenant appear as contacts in another Azure AD
tenant.
Modify Azure AD Connect sync to connect to multiple Azure AD tenants.
GALSync by using writeback

Azure AD tenants are isolated by design. These tasks are unsupported:


Change the configuration of Azure AD Connect sync to read data from another Azure AD tenant.
Export users as contacts to another on-premises Active Directory instance by using Azure AD Connect sync.
GALSync with on-premises sync server

You can use FIM 2010 or MIM 2016 on-premises to sync users (via GALSync) between two Exchange
organizations. The users in one organization appear as foreign users/contacts in the other organization. These
different on-premises Active Directory instances can then be synchronized with their own Azure AD tenants.

Next steps
To learn how to install Azure AD Connect for these scenarios, see Custom installation of Azure AD Connect.
Learn more about the Azure AD Connect sync configuration.
Learn more about integrating your on-premises identities with Azure Active Directory.
Deploying Active Directory Federation Services in
Azure
2/21/2018 • 16 min to read • Edit Online

AD FS provides simplified, secured identity federation and Web single sign-on (SSO) capabilities. Federation with
Azure AD or O365 enables users to authenticate using on-premises credentials and access all resources in cloud.
As a result, it becomes important to have a highly available AD FS infrastructure to ensure access to resources both
on-premises and in the cloud. Deploying AD FS in Azure can help achieve the high availability required with
minimal efforts. There are several advantages of deploying AD FS in Azure, a few of them are listed below:
High Availability - With the power of Azure Availability Sets, you ensure a highly available infrastructure.
Easy to Scale – Need more performance? Easily migrate to more powerful machines by just a few clicks in
Azure
Cross-Geo Redundancy – With Azure Geo Redundancy you can be assured that your infrastructure is highly
available across the globe
Easy to Manage – With highly simplified management options in Azure portal, managing your infrastructure is
very easy and hassle-free

Design principles

The diagram above shows the recommended basic topology to start deploying your AD FS infrastructure in Azure.
The principles behind the various components of the topology are listed below:
DC / ADFS Servers: If you have fewer than 1,000 users you can simply install AD FS role on your domain
controllers. If you do not want any performance impact on the domain controllers or if you have more than
1,000 users, then deploy AD FS on separate servers.
WAP Server – it is necessary to deploy Web Application Proxy servers, so that users can reach the AD FS when
they are not on the company network also.
DMZ: The Web Application Proxy servers will be placed in the DMZ and ONLY TCP/443 access is allowed
between the DMZ and the internal subnet.
Load Balancers: To ensure high availability of AD FS and Web Application Proxy servers, we recommend using
an internal load balancer for AD FS servers and Azure Load Balancer for Web Application Proxy servers.
Availability Sets: To provide redundancy to your AD FS deployment, it is recommended that you group two or
more virtual machines in an Availability Set for similar workloads. This configuration ensures that during either
a planned or unplanned maintenance event, at least one virtual machine will be available
Storage Accounts: It is recommended to have two storage accounts. Having a single storage account can lead
to creation of a single point of failure and can cause the deployment to become unavailable in an unlikely
scenario where the storage account goes down. Two storage accounts will help associate one storage account
for each fault line.
Network segregation: Web Application Proxy servers should be deployed in a separate DMZ network. You can
divide one virtual network into two subnets and then deploy the Web Application Proxy server(s) in an isolated
subnet. You can simply configure the network security group settings for each subnet and allow only required
communication between the two subnets. More details are given per deployment scenario below

Steps to deploy AD FS in Azure


The steps mentioned in this section outline the guide to deploy the below depicted AD FS infrastructure in Azure.
1. Deploying the network
As outlined above, you can either create two subnets in a single virtual network or else create two completely
different virtual networks (VNet). This article will focus on deploying a single virtual network and divide it into two
subnets. This is currently an easier approach as two separate VNets would require a VNet to VNet gateway for
communications.
1.1 Create virtual network

In the Azure portal, select virtual network and you can deploy the virtual network and one subnet immediately with
just one click. INT subnet is also defined and is ready now for VMs to be added. The next step is to add another
subnet to the network, i.e. the DMZ subnet. To create the DMZ subnet, simply
Select the newly created network
In the properties select subnet
In the subnet panel click on the add button
Provide the subnet name and address space information to create the subnet

1.2. Creating the network security groups


A Network security group (NSG) contains a list of Access Control List (ACL) rules that allow or deny network traffic
to your VM instances in a Virtual Network. NSGs can be associated with either subnets or individual VM instances
within that subnet. When an NSG is associated with a subnet, the ACL rules apply to all the VM instances in that
subnet. For the purpose of this guidance, we will create two NSGs: one each for an internal network and a DMZ.
They will be labeled NSG_INT and NSG_DMZ respectively.
After the NSG is created, there will be 0 inbound and 0 outbound rules. Once the roles on the respective servers are
installed and functional, then the inbound and outbound rules can be made according to the desired level of
security.

After the NSGs are created, associate NSG_INT with subnet INT and NSG_DMZ with subnet DMZ. An example
screenshot is given below:
Click on Subnets to open the panel for subnets
Select the subnet to associate with the NSG
After configuration, the panel for Subnets should look like below:

1.3. Create Connection to on-premises


We will need a connection to on-premises in order to deploy the domain controller (DC) in azure. Azure offers
various connectivity options to connect your on-premises infrastructure to your Azure infrastructure.
Point-to-site
Virtual Network Site-to-site
ExpressRoute
It is recommended to use ExpressRoute. ExpressRoute lets you create private connections between Azure
datacenters and infrastructure that’s on your premises or in a co-location environment. ExpressRoute connections
do not go over the public Internet. They offer more reliability, faster speeds, lower latencies and higher security
than typical connections over the Internet. While it is recommended to use ExpressRoute, you may choose any
connection method best suited for your organization. To learn more about ExpressRoute and the various
connectivity options using ExpressRoute, read ExpressRoute technical overview.
2. Create storage accounts
In order to maintain high availability and avoid dependence on a single storage account, you can create two
storage accounts. Divide the machines in each availability set into two groups and then assign each group a
separate storage account.
3. Create availability sets
For each role (DC/AD FS and WAP), create availability sets that will contain 2 machines each at the minimum. This
will help achieve higher availability for each role. While creating the availability sets, it is essential to decide on the
following:
Fault Domains: Virtual machines in the same fault domain share the same power source and physical network
switch. A minimum of 2 fault domains are recommended. The default value is 3 and you can leave it as is for the
purpose of this deployment
Update domains: Machines belonging to the same update domain are restarted together during an update.
You want to have minimum of 2 update domains. The default value is 5 and you can leave it as is for the
purpose of this deployment
Create the following availability sets

AVAILABILITY SET ROLE FAULT DOMAINS UPDATE DOMAINS

contosodcset DC/ADFS 3 5

contosowapset WAP 3 5

4. Deploy virtual machines


The next step is to deploy virtual machines that will host the different roles in your infrastructure. A minimum of
two machines are recommended in each availability set. Create four virtual machines for the basic deployment.

STORAGE
MACHINE ROLE SUBNET AVAILABILITY SET ACCOUNT IP ADDRESS

contosodc1 DC/ADFS INT contosodcset contososac1 Static

contosodc2 DC/ADFS INT contosodcset contososac2 Static


STORAGE
MACHINE ROLE SUBNET AVAILABILITY SET ACCOUNT IP ADDRESS

contosowap1 WAP DMZ contosowapset contososac1 Static

contosowap2 WAP DMZ contosowapset contososac2 Static

As you might have noticed, no NSG has been specified. This is because azure lets you use NSG at the subnet level.
Then, you can control machine network traffic by using the individual NSG associated with either the subnet or else
the NIC object. Read more on What is a Network Security Group (NSG). Static IP address is recommended if you
are managing the DNS. You can use Azure DNS and instead in the DNS records for your domain, refer to the new
machines by their Azure FQDNs. Your virtual machine pane should look like below after the deployment is
completed:

5. Configuring the domain controller / AD FS servers


In order to authenticate any incoming request, AD FS will need to contact the domain controller. To save the costly
trip from Azure to on-premises DC for authentication, it is recommended to deploy a replica of the domain
controller in Azure. In order to attain high availability, it is recommended to create an availability set of at-least 2
domain controllers.

DOMAIN CONTROLLER ROLE STORAGE ACCOUNT

contosodc1 Replica contososac1

contosodc2 Replica contososac2

Promote the two servers as replica domain controllers with DNS


Configure the AD FS servers by installing the AD FS role using the server manager.
6. Deploying Internal Load Balancer (ILB )
6.1. Create the ILB
To deploy an ILB, select Load Balancers in the Azure portal and click on add (+).

NOTE
if you do not see Load Balancers in your menu, click Browse in the lower left of the portal and scroll until you see Load
Balancers. Then click the yellow star to add it to your menu. Now select the new load balancer icon to open the panel to
begin configuration of the load balancer.
Name: Give any suitable name to the load balancer
Scheme: Since this load balancer will be placed in front of the AD FS servers and is meant for internal network
connections ONLY, select “Internal”
Virtual Network: Choose the virtual network where you are deploying your AD FS
Subnet: Choose the internal subnet here
IP Address assignment: Static
After you click create and the ILB is deployed, you should see it in the list of load balancers:

Next step is to configure the backend pool and the backend probe.
6.2. Configure ILB backend pool
Select the newly created ILB in the Load Balancers panel. It will open the settings panel.
1. Select backend pools from the settings panel
2. In the add backend pool panel, click on add virtual machine
3. You will be presented with a panel where you can choose availability set
4. Choose the AD FS availability set
6.3. Configuring probe
In the ILB settings panel, select Probes.
1. Click on add
2. Provide details for probe a. Name: Probe name b. Protocol: TCP c. Port: 443 (HTTPS) d. Interval: 5 (default
value) – this is the interval at which ILB will probe the machines in the backend pool e. Unhealthy threshold
limit: 2 (default val ue) – this is the threshold of consecutive probe failures after which ILB will declare a
machine in the backend pool non-responsive and stop sending traffic to it.

6.4. Create load balancing rules


In order to effectively balance the traffic, the ILB should be configured with load balancing rules. In order to create a
load balancing rule,
1. Select Load balancing rule from the settings panel of the ILB
2. Click on Add in the Load balancing rule panel
3. In the Add load balancing rule panel a. Name: Provide a name for the rule b. Protocol: Select TCP c. Port: 443
d. Backend port: 443 e. Backend pool: Select the pool you created for the AD FS cluster earlier f. Probe: Select
the probe created for AD FS servers earlier
6.5. Update DNS with ILB
Go to your DNS server and create a CNAME for the ILB. The CNAME should be for the federation service with the IP
address pointing to the IP address of the ILB. For example if the ILB DIP address is 10.3.0.8, and the federation
service installed is fs.contoso.com, then create a CNAME for fs.contoso.com pointing to 10.3.0.8. This will ensure
that all communication regarding fs.contoso.com end up at the ILB and are appropriately routed.
7. Configuring the Web Application Proxy server
7.1. Configuring the Web Application Proxy servers to reach AD FS servers
In order to ensure that Web Application Proxy servers are able to reach the AD FS servers behind the ILB, create a
record in the %systemroot%\system32\drivers\etc\hosts for the ILB. Note that the distinguished name (DN) should
be the federation service name, for example fs.contoso.com. And the IP entry should be that of the ILB’s IP address
(10.3.0.8 as in the example).
7.2. Installing the Web Application Proxy role
After you ensure that Web Application Proxy servers are able to reach the AD FS servers behind ILB, you can next
install the Web Application Proxy servers. Web Application Proxy servers do not be joined to the domain. Install the
Web Application Proxy roles on the two Web Application Proxy servers by selecting the Remote Access role. The
server manager will guide you to complete the WAP installation. For more information on how to deploy WAP,
read Install and Configure the Web Application Proxy Server.
8. Deploying the Internet Facing (Public) Load Balancer
8.1. Create Internet Facing (Public) Load Balancer
In the Azure portal, select Load balancers and then click on Add. In the Create load balancer panel, enter the
following information
1. Name: Name for the load balancer
2. Scheme: Public – this option tells Azure that this load balancer will need a public address.
3. IP Address: Create a new IP address (dynamic)
After deployment, the load balancer will appear in the Load balancers list.

8.2. Assign a DNS label to the public IP


Click on the newly created load balancer entry in the Load balancers panel to bring up the panel for configuration.
Follow below steps to configure the DNS label for the public IP:
1. Click on the public IP address. This will open the panel for the public IP and its settings
2. Click on Configuration
3. Provide a DNS label. This will become the public DNS label that you can access from anywhere, for example
contosofs.westus.cloudapp.azure.com. You can add an entry in the external DNS for the federation service (like
fs.contoso.com) that resolves to the DNS label of the external load balancer
(contosofs.westus.cloudapp.azure.com).

8.3. Configure backend pool for Internet Facing (Public) Load Balancer
Follow the same steps as in creating the internal load balancer, to configure the backend pool for Internet Facing
(Public) Load Balancer as the availability set for the WAP servers. For example, contosowapset.
8.4. Configure probe
Follow the same steps as in configuring the internal load balancer to configure the probe for the backend pool of
WAP servers.

8.5. Create load balancing rule(s)


Follow the same steps as in ILB to configure the load balancing rule for TCP 443.
9. Securing the network
9.1. Securing the internal subnet
Overall, you need the following rules to efficiently secure your internal subnet (in the order as listed below)

RULE DESCRIPTION FLOW

AllowHTTPSFromDMZ Allow the HTTPS communication from Inbound


DMZ

DenyInternetOutbound No access to internet Outbound

9.2. Securing the DMZ subnet

RULE DESCRIPTION FLOW

AllowHTTPSFromInternet Allow HTTPS from internet to the DMZ Inbound

DenyInternetOutbound Anything except HTTPS to internet is Outbound


blocked
NOTE
If client user certificate authentication (clientTLS authentication using X509 user certificates) is required, then AD FS requires
TCP port 49443 be enabled for inbound access.

10. Test the AD FS sign-in


The easiest way is to test AD FS is by using the IdpInitiatedSignon.aspx page. In order to be able to do that, it is
required to enable the IdpInitiatedSignOn on the AD FS properties. Follow the steps below to verify your AD FS
setup
1. Run the below cmdlet on the AD FS server, using PowerShell, to set it to enabled. Set-AdfsProperties -
EnableIdPInitiatedSignonPage $true
2. From any external machine access https://adfs.thecloudadvocate.com/adfs/ls/IdpInitiatedSignon.aspx
3. You should see the AD FS page like below:
On successful sign-in, it will provide you with a success message as shown below:

Template for deploying AD FS in Azure


The template deploys a 6 machine setup, 2 each for Domain Controllers, AD FS and WAP.
AD FS in Azure Deployment Template
You can use an existing virtual network or create a new VNET while deploying this template. The various
parameters available for customizing the deployment are listed below with the description of usage of the
parameter in the deployment process.

PARAMETER DESCRIPTION

Location The region to deploy the resources into, e.g. East US.

StorageAccountType The type of the Storage Account created

VirtualNetworkUsage Indicates if a new virtual network will be created or use an


existing one

VirtualNetworkName The name of the Virtual Network to Create, mandatory on


both existing or new virtual network usage

VirtualNetworkResourceGroupName Specifies the name of the resource group where the existing
virtual network resides. When using an existing virtual
network, this becomes a mandatory parameter so the
deployment can find the ID of the existing virtual network

VirtualNetworkAddressRange The address range of the new VNET, mandatory if creating a


new virtual network

InternalSubnetName The name of the internal subnet, mandatory on both virtual


network usage options (new or existing)
PARAMETER DESCRIPTION

InternalSubnetAddressRange The address range of the internal subnet, which contains the
Domain Controllers and ADFS servers, mandatory if creating a
new virtual network.

DMZSubnetAddressRange The address range of the dmz subnet, which contains the
Windows application proxy servers, mandatory if creating a
new virtual network.

DMZSubnetName The name of the internal subnet, mandatory on both virtual


network usage options (new or existing).

ADDC01NICIPAddress The internal IP address of the first Domain Controller, this IP


address will be statically assigned to the DC and must be a
valid ip address within the Internal subnet

ADDC02NICIPAddress The internal IP address of the second Domain Controller, this


IP address will be statically assigned to the DC and must be a
valid ip address within the Internal subnet

ADFS01NICIPAddress The internal IP address of the first ADFS server, this IP address
will be statically assigned to the ADFS server and must be a
valid ip address within the Internal subnet

ADFS02NICIPAddress The internal IP address of the second ADFS server, this IP


address will be statically assigned to the ADFS server and
must be a valid ip address within the Internal subnet

WAP01NICIPAddress The internal IP address of the first WAP server, this IP address
will be statically assigned to the WAP server and must be a
valid ip address within the DMZ subnet

WAP02NICIPAddress The internal IP address of the second WAP server, this IP


address will be statically assigned to the WAP server and must
be a valid ip address within the DMZ subnet

ADFSLoadBalancerPrivateIPAddress The internal IP address of the ADFS load balancer, this IP


address will be statically assigned to the load balancer and
must be a valid ip address within the Internal subnet

ADDCVMNamePrefix Virtual Machine name prefix for Domain Controllers

ADFSVMNamePrefix Virtual Machine name prefix for ADFS servers

WAPVMNamePrefix Virtual Machine name prefix for WAP servers

ADDCVMSize The vm size of the Domain Controllers

ADFSVMSize The vm size of the ADFS servers

WAPVMSize The vm size of the WAP servers

AdminUserName The name of the local Administrator of the virtual machines


PARAMETER DESCRIPTION

AdminPassword The password for the local Administrator account of the virtual
machines

Additional resources
Availability Sets
Azure Load Balancer
Internal Load Balancer
Internet Facing Load Balancer
Storage Accounts
Azure Virtual Networks
AD FS and Web Application Proxy Links

Next steps
Integrating your on-premises identities with Azure Active Directory
Configuring and managing your AD FS using Azure AD Connect
High availability cross-geographic AD FS deployment in Azure with Azure Traffic Manager
Azure AD Connect: Special considerations for
instances
1/17/2018 • 1 min to read • Edit Online

Azure AD Connect is most commonly used with the world-wide instance of Azure AD and Office 365. But there are
also other instances and these have different requirements for URLs and other special considerations.

Microsoft Cloud Germany


The Microsoft Cloud Germany is a sovereign cloud operated by a German data trustee.

URLS TO OPEN IN PROXY SERVER

*.microsoftonline.de

*.windows.net

+Certificate Revocation Lists

When you sign in to your Azure AD tenant, you must use an account in the onmicrosoft.de domain.
Features currently not present in the Microsoft Cloud Germany:
Azure AD Connect Health is not available.
Automatic updates is not available.
Password writeback is available for preview with Azure AD Connect version 1.1.570.0 and after.
Other Azure AD Premium services are not available.

Microsoft Azure Government cloud


The Microsoft Azure Government cloud is a cloud for US government.
This cloud has been supported by earlier releases of DirSync. From build 1.1.180 of Azure AD Connect, the next
generation of the cloud is supported. This generation is using US-only based endpoints and have a different list of
URLs to open in your proxy server.

URLS TO OPEN IN PROXY SERVER

*.microsoftonline.com

*.microsoftonline.us

*.windows.net (Required for automatic Azure AD government tenant detection)

*.gov.us.microsoftonline.com

+Certificate Revocation Lists


NOTE
As of AAD Connect version 1.1.647.0, setting the AzureInstance value in the registry is no longer required provided that
*.windows.net is open on your proxy server(s).

Features currently not present in the Microsoft Azure Government cloud:


Azure AD Connect Health is not available.
Automatic updates is not available.
Password writeback is available for preview with Azure AD Connect version 1.1.570.0 and after.
Other Azure AD Premium services are not available.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect: When you have an existent
tenant
1/17/2018 • 4 min to read • Edit Online

Most of the topics for how to use Azure AD Connect assumes you start with a new Azure AD tenant and that there
are no users or other objects there. But if you have started with an Azure AD tenant, populated it with users and
other objects, and now want to use Connect, then this topic is for you.

The basics
An object in Azure AD is either mastered in the cloud (Azure AD) or on-premises. For one single object, you cannot
manage some attributes on-premises and some other attributes in Azure AD. Each object has a flag indicating
where the object is managed.
You can manage some users on-premises and other in the cloud. A common scenario for this configuration is an
organization with a mix of accounting workers and sales workers. The accounting workers have an on-premises AD
account, but the sales workers do not, they have an account in Azure AD. You would manage some users on-
premises and some in Azure AD.
If you started to manage users in Azure AD that are also in on-premises AD and later want to use Connect, then
there are some additional concerns you need to consider.

Sync with existing users in Azure AD


When you install Azure AD Connect and you start synchronizing, the Azure AD sync service (in Azure AD) does a
check on every new object and try to find an existing object to match. There are three attributes used for this
process: userPrincipalName, proxyAddresses, and sourceAnchor/immutableID. A match on
userPrincipalName and proxyAddresses is known as a soft match. A match on sourceAnchor is known as
hard match. For the proxyAddresses attribute only the value with SMTP:, that is the primary email address, is
used for the evaluation.
The match is only evaluated for new objects coming from Connect. If you change an existing object so it is
matching any of these attributes, then you see an error instead.
If Azure AD finds an object where the attribute values are the same for an object coming from Connect and that it is
already present in Azure AD, then the object in Azure AD is taken over by Connect. The previously cloud-managed
object is flagged as on-premises managed. All attributes in Azure AD with a value in on-premises AD are
overwritten with the on-premises value. The exception is when an attribute has a NULL value on-premises. In this
case, the value in Azure AD remains, but you can still only change it on-premises to something else.

WARNING
Since all attributes in Azure AD are going to be overwritten by the on-premises value, make sure you have good data on-
premises. For example, if you only have managed email address in Office 365 and not kept it updated in on-premises AD DS,
then you lose any values in Azure AD/Office 365 not present in AD DS.
IMPORTANT
If you use password sync, which is always used by express settings, then the password in Azure AD is overwritten with the
password in on-premises AD. If your users are used to manage different passwords, then you need to inform them that they
should use the on-premises password when you have installed Connect.

The previous section and warning must be considered in your planning. If you have made many changes in Azure
AD not reflected in on-premises AD DS, then you need to plan for how to populate AD DS with the updated values
before you sync your objects with Azure AD Connect.
If you matched your objects with a soft-match, then the sourceAnchor is added to the object in Azure AD so a hard
match can be used later.
Hard-match vs Soft-match
For a new installation of Connect, there is no practical difference between a soft- and a hard-match. The difference
is in a disaster recovery situation. If you have lost your server with Azure AD Connect, you can reinstall a new
instance without losing any data. An object with a sourceAnchor is sent to Connect during initial install. The match
can then be evaluated by the client (Azure AD Connect), which is a lot faster than doing the same in Azure AD. A
hard match is evaluated both by Connect and by Azure AD. A soft match is only evaluated by Azure AD.
Other objects than users
For mail-enabled groups and contacts, you can soft-match based on proxyAddresses. Hard-match is not applicable
since you can only update the sourceAnchor/immutableID (using PowerShell) on Users only. For groups that aren't
mail-enabled, there is currently no support for soft-match or hard-match.

Create a new on-premises Active Directory from data in Azure AD


Some customers start with a cloud-only solution with Azure AD and they do not have an on-premises AD. Later
they want to consume on-premises resources and want to build an on-premises AD based on Azure AD data. Azure
AD Connect cannot help you for this scenario. It does not create users on-premises and it does not have any ability
to set the password on-premises to the same as in Azure AD.
If the only reason why you plan to add on-premises AD is to support LOBs (Line-of-Business apps), then maybe you
should consider to use Azure AD domain services instead.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Next steps and how to manage Azure AD Connect
12/11/2017 • 2 min to read • Edit Online

Use the operational procedures in this article to customize Azure Active Directory (Azure AD) Connect to meet
your organization's needs and requirements.

Add additional sync admins


By default, only the user who did the installation and local admins are able to manage the installed sync engine.
For additional people to be able to access and manage the sync engine, locate the group named ADSyncAdmins
on the local server and add them to this group.

Assign licenses to Azure AD Premium and Enterprise Mobility Suite


users
Now that your users have been synchronized to the cloud, you need to assign them a license so they can get
going with cloud apps such as Office 365.
To assign an Azure AD Premium or Enterprise Mobility Suite License
1. Sign in to the Azure portal as an admin.
2. On the left, select Active Directory.
3. On the Active Directory page, double-click the directory that has the users you want to set up.
4. At the top of the directory page, select Licenses.
5. On the Licenses page, select Active Directory Premium or Enterprise Mobility Suite, and then click
Assign.
6. In the dialog box, select the users you want to assign licenses to, and then click the check mark icon to save the
changes.

Verify the scheduled synchronization task


Use the Azure portal to check the status of a synchronization.
To verify the scheduled synchronization task
1. Sign in to the Azure portal as an admin.
2. On the left, select Active Directory.
3. On the Active Directory page, double-click the directory that has the users you want to set up.
4. At the top of the directory page, select Directory Integration.
5. Under integration with local active directory, note the last sync time.
Start a scheduled synchronization task
If you need to run a synchronization task, you can do this by running through the Azure AD Connect wizard again.
You need to provide your Azure AD credentials. In the wizard, select the Customize synchronization options
task, and click Next to move through the wizard. At the end, ensure that the Start the synchronization process
as soon as the initial configuration completes box is selected.

For more information on the Azure AD Connect sync Scheduler, see Azure AD Connect Scheduler.

Additional tasks available in Azure AD Connect


After your initial installation of Azure AD Connect, you can always start the wizard again from the Azure AD
Connect start page or desktop shortcut. You will notice that going through the wizard again provides some new
options in the form of additional tasks.
The following table provides a summary of these tasks and a brief description of each task.

ADDITIONAL TASK DESCRIPTION

View the selected scenario View your current Azure AD Connect solution. This includes
general settings, synchronized directories, and sync settings.

Customize synchronization options Change the current configuration like adding additional Active
Directory forests to the configuration, or enabling sync
options such as user, group, device, or password write-back.

Enable Staging Mode Stage information that is not immediately synchronized and is
not exported to Azure AD or on-premises Active Directory.
With this feature, you can preview the synchronizations
before they occur.

Next steps
Learn more about integrating your on-premises identities with Azure Active Directory.
Renew federation certificates for Office 365 and
Azure Active Directory
12/11/2017 • 8 min to read • Edit Online

Overview
For successful federation between Azure Active Directory (Azure AD) and Active Directory Federation Services (AD
FS), the certificates used by AD FS to sign security tokens to Azure AD should match what is configured in Azure
AD. Any mismatch can lead to broken trust. Azure AD ensures that this information is kept in sync when you
deploy AD FS and Web Application Proxy (for extranet access).
This article provides you additional information to manage your token signing certificates and keep them in sync
with Azure AD, in the following cases:
You are not deploying the Web Application Proxy, and therefore the federation metadata is not available in the
extranet.
You are not using the default configuration of AD FS for token signing certificates.
You are using a third-party identity provider.

Default configuration of AD FS for token signing certificates


The token signing and token decrypting certificates are usually self-signed certificates, and are good for one year.
By default, AD FS includes an auto-renewal process called AutoCertificateRollover. If you are using AD FS 2.0 or
later, Office 365 and Azure AD automatically update your certificate before it expires.
Renewal notification from the Office 365 portal or an email

NOTE
If you received an email or a portal notification asking you to renew your certificate for Office, see Managing changes to
token signing certificates to check if you need to take any action. Microsoft is aware of a possible issue that can lead to
notifications for certificate renewal being sent, even when no action is required.

Azure AD attempts to monitor the federation metadata, and update the token signing certificates as indicated by
this metadata. 30 days before the expiration of the token signing certificates, Azure AD checks if new certificates
are available by polling the federation metadata.
If it can successfully poll the federation metadata and retrieve the new certificates, no email notification or
warning in the Office 365 portal is issued to the user.
If it cannot retrieve the new token signing certificates, either because the federation metadata is not reachable
or automatic certificate rollover is not enabled, Azure AD issues an email notification and a warning in the
Office 365 portal.
IMPORTANT
If you are using AD FS, to ensure business continuity, please verify that your servers have the following updates so that
authentication failures for known issues do not occur. This mitigates known AD FS proxy server issues for this renewal and
future renewal periods:
Server 2012 R2 - Windows Server May 2014 rollup
Server 2008 R2 and 2012 - Authentication through proxy fails in Windows Server 2012 or Windows 2008 R2 SP1

Check if the certificates need to be updated


Step 1: Check the AutoCertificateRollover state
On your AD FS server, open PowerShell. Check that the AutoCertificateRollover value is set to True.

Get-Adfsproperties

NOTE
If you are using AD FS 2.0, first run Add-Pssnapin Microsoft.Adfs.Powershell.

Step 2: Confirm that AD FS and Azure AD are in sync


On your AD FS server, open the Azure AD PowerShell prompt, and connect to Azure AD.

NOTE
You can download Azure AD PowerShell here.

Connect-MsolService

Check the certificates configured in AD FS and Azure AD trust properties for the specified domain.

Get-MsolFederationProperty -DomainName <domain.name> | FL Source, TokenSigningCertificate


If the thumbprints in both the outputs match, your certificates are in sync with Azure AD.
Step 3: Check if your certificate is about to expire
In the output of either Get-MsolFederationProperty or Get-AdfsCertificate, check for the date under "Not After." If
the date is less than 30 days away, you should take action.

FEDERATION
AUTOCERTIFICATEROLL CERTIFICATES IN SYNC METADATA IS PUBLICLY
OVER WITH AZURE AD ACCESSIBLE VALIDITY ACTION

Yes Yes Yes - No action needed. See


Renew token signing
certificate
automatically.

Yes No - Less than 15 days Renew immediately.


See Renew token
signing certificate
manually.

No - - Less than 30 days Renew immediately.


See Renew token
signing certificate
manually.

[-] Does not matter

Renew the token signing certificate automatically (recommended)


You don't need to perform any manual steps if both of the following are true:
You have deployed Web Application Proxy, which can enable access to the federation metadata from the
extranet.
You are using the AD FS default configuration (AutoCertificateRollover is enabled).
Check the following to confirm that the certificate can be automatically updated.
1. The AD FS property AutoCertificateRollover must be set to True. This indicates that AD FS will
automatically generate new token signing and token decryption certificates, before the old ones expire.
2. The AD FS federation metadata is publicly accessible. Check that your federation metadata is publicly
accessible by navigating to the following URL from a computer on the public internet (off of the corporate
network):
https://(your_FS_name)/federationmetadata/2007-06/federationmetadata.xml
where (your_FS_name) is replaced with the federation service host name your organization uses, such as
fs.contoso.com. If you are able to verify both of these settings successfully, you do not have to do anything else.
Example: https://fs.contoso.com/federationmetadata/2007-06/federationmetadata.xml

Renew the token signing certificate manually


You may choose to renew the token signing certificates manually. For example, the following scenarios might work
better for manual renewal:
Token signing certificates are not self-signed certificates. The most common reason for this is that your
organization manages AD FS certificates enrolled from an organizational certificate authority.
Network security does not allow the federation metadata to be publicly available.
In these scenarios, every time you update the token signing certificates, you must also update your Office 365
domain by using the PowerShell command, Update-MsolFederatedDomain.
Step 1: Ensure that AD FS has new token signing certificates
Non-default configuration
If you are using a non-default configuration of AD FS (where AutoCertificateRollover is set to False), you are
probably using custom certificates (not self-signed). For more information about how to renew the AD FS token
signing certificates, see Guidance for customers not using AD FS self-signed certificates.
Federation metadata is not publicly available
On the other hand, if AutoCertificateRollover is set to True, but your federation metadata is not publicly
accessible, first make sure that new token signing certificates have been generated by AD FS. Confirm you have
new token signing certificates by taking the following steps:
1. Verify that you are logged on to the primary AD FS server.
2. Check the current signing certificates in AD FS by opening a PowerShell command window, and running the
following command:
PS C:>Get-ADFSCertificate –CertificateType token-signing

NOTE
If you are using AD FS 2.0, you should run Add-Pssnapin Microsoft.Adfs.Powershell first.

3. Look at the command output at any certificates listed. If AD FS has generated a new certificate, you should see
two certificates in the output: one for which the IsPrimary value is True and the NotAfter date is within 5 days,
and one for which IsPrimary is False and NotAfter is about a year in the future.
4. If you only see one certificate, and the NotAfter date is within 5 days, you need to generate a new certificate.
5. To generate a new certificate, execute the following command at a PowerShell command prompt:
PS C:\>Update-ADFSCertificate –CertificateType token-signing .
6. Verify the update by running the following command again: PS C:>Get-ADFSCertificate –CertificateType token-
signing
Two certificates should be listed now, one of which has a NotAfter date of approximately one year in the future,
and for which the IsPrimary value is False.
Step 2: Update the new token signing certificates for the Office 365 trust
Update Office 365 with the new token signing certificates to be used for the trust, as follows.
1. Open the Microsoft Azure Active Directory Module for Windows PowerShell.
2. Run $cred=Get-Credential. When this cmdlet prompts you for credentials, type your cloud service
administrator account credentials.
3. Run Connect-MsolService –Credential $cred. This cmdlet connects you to the cloud service. Creating a context
that connects you to the cloud service is required before running any of the additional cmdlets installed by the
tool.
4. If you are running these commands on a computer that is not the AD FS primary federation server, run Set-
MSOLAdfscontext -Computer , where is the internal FQDN name of the primary AD FS server. This cmdlet
creates a context that connects you to AD FS.
5. Run Update-MSOLFederatedDomain –DomainName . This cmdlet updates the settings from AD FS into the
cloud service, and configures the trust relationship between the two.

NOTE
If you need to support multiple top-level domains, such as contoso.com and fabrikam.com, you must use the
SupportMultipleDomain switch with any cmdlets. For more information, see Support for Multiple Top Level Domains.

Repair Azure AD trust by using Azure AD Connect


If you configured your AD FS farm and Azure AD trust by using Azure AD Connect, you can use Azure AD Connect
to detect if you need to take any action for your token signing certificates. If you need to renew the certificates, you
can use Azure AD Connect to do so.
For more information, see Repairing the trust.

AD FS and Azure AD certificate update steps


Token signing certificates are standard X509 certificates that are used to securely sign all tokens that the federation
server issues. Token decryption certificates are standard X509 certificates that are used to decrypt any incoming
tokens.
By default, AD FS is configured to generate token signing and token decryption certificates automatically, both at
the initial configuration time and when the certificates are approaching their expiration date.
Azure AD tries to retrieve a new certificate from your federation service metadata 30 days before the expiry of the
current certificate. In case a new certificate is not available at that time, Azure AD will continue to monitor the
metadata on regular daily intervals. As soon as the new certificate is available in the metadata, the federation
settings for the domain are updated with the new certificate information. You can use
Get-MsolDomainFederationSettings to verify if you see the new certificate in the NextSigningCertificate /
SigningCertificate.
For more information on Token Signing certificates in AD FS see Obtain and Configure Token Signing and Token
Decryption Certificates for AD FS
Update the SSL certificate for an Active Directory
Federation Services (AD FS) farm
1/17/2018 • 4 min to read • Edit Online

Overview
This article describes how you can use Azure AD Connect to update the SSL certificate for an Active Directory
Federation Services (AD FS) farm. You can use the Azure AD Connect tool to easily update the SSL certificate for
the AD FS farm even if the user sign-in method selected is not AD FS.
You can perform the whole operation of updating SSL certificate for the AD FS farm across all federation and Web
Application Proxy (WAP) servers in three simple steps:

NOTE
To learn more about certificates that are used by AD FS, see Understanding certificates used by AD FS.

Prerequisites
AD FS Farm: Make sure that your AD FS farm is Windows Server 2012 R2-based or later.
Azure AD Connect: Ensure that the version of Azure AD Connect is 1.1.553.0 or higher. You'll use the task
Update AD FS SSL certificate.
Step 1: Provide AD FS farm information
Azure AD Connect attempts to obtain information about the AD FS farm automatically by:
1. Querying the farm information from AD FS (Windows Server 2016 or later).
2. Referencing the information from previous runs, which are stored locally with Azure AD Connect.
You can modify the list of servers that are displayed by adding or removing the servers to reflect the current
configuration of the AD FS farm. As soon as the server information is provided, Azure AD Connect displays the
connectivity and current SSL certificate status.
If the list contains a server that's no longer part of the AD FS farm, click Remove to delete the server from the list
of servers in your AD FS farm.
NOTE
Removing a server from the list of servers for an AD FS farm in Azure AD Connect is a local operation and updates the
information for the AD FS farm that Azure AD Connect maintains locally. Azure AD Connect doesn't modify the configuration
on AD FS to reflect the change.

Step 2: Provide a new SSL certificate


After you've confirmed the information about AD FS farm servers, Azure AD Connect asks for the new SSL
certificate. Provide a password-protected PFX certificate to continue the installation.

After you provide the certificate, Azure AD Connect goes through a series of prerequisites. Verify the certificate to
ensure that the certificate is correct for the AD FS farm:
The subject name/alternate subject name for the certificate is either the same as the federation service name, or
it's a wildcard certificate.
The certificate is valid for more than 30 days.
The certificate trust chain is valid.
The certificate is password protected.

Step 3: Select servers for the update


In the next step, select the servers that need to have the SSL certificate updated. Servers that are offline can't be
selected for the update.
After you complete the configuration, Azure AD Connect displays the message that indicates the status of the
update and provides an option to verify the AD FS sign-in.

FAQs
What should be the subject name of the certificate for the new AD FS SSL certificate?
Azure AD Connect checks if the subject name/alternate subject name of the certificate contains the
federation service name. For example, if your federation service name is fs.contoso.com, the subject
name/alternate subject name must be fs.contoso.com. Wildcard certificates are also accepted.
Why am I asked for credentials again on the WAP server page?
If the credentials you provide for connecting to AD FS servers don't also have the privilege to manage the
WAP servers, then Azure AD Connect asks for credentials that have administrative privilege on the WAP
servers.
The server is shown as offline. What should I do?
Azure AD Connect can't perform any operation if the server is offline. If the server is part of the AD FS farm,
then check the connectivity to the server. After you've resolved the issue, press the refresh icon to update
the status in the wizard. If the server was part of the farm earlier but now no longer exists, click Remove to
delete it from the list of servers that Azure AD Connect maintains. Removing the server from the list in
Azure AD Connect doesn't alter the AD FS configuration itself. If you're using AD FS in Windows Server
2016 or later, the server remains in the configuration settings and will be shown again the next time the task
is run.
Can I update a subset of my farm servers with the new SSL certificate?
Yes. You can always run the task Update SSL Certificate again to update the remaining servers. On the
Select servers for SSL certificate update page, you can sort the list of servers on SSL Expiry date to
easily access the servers that aren't updated yet.
I removed the server in the previous run, but it's still being shown as offline and listed on the AD
FS Servers page. Why is the offline server still there even after I removed it?
Removing the server from the list in Azure AD Connect doesn't remove it in the AD FS configuration. Azure
AD Connect references AD FS (Windows Server 2016 or higher) for any information about the farm. If the
server is still present in the AD FS configuration, it will be listed back in the list.

Next steps
Azure AD Connect and federation
Active Directory Federation Services management and customization with Azure AD Connect
Azure AD Connect: Enabling device writeback
1/4/2018 • 5 min to read • Edit Online

NOTE
A subscription to Azure AD Premium is required for device writeback.

The following documentation provides information on how to enable the device writeback feature in Azure AD
Connect. Device writeback is used in the following scenarios:
Enable conditional access based on devices to ADFS (2012 R2 or higher) protected applications (relying party
trusts).
This provides additional security and assurance that access to applications is granted only to trusted devices. For
more information on conditional access, see Managing Risk with Conditional Access and Setting up On-premises
Conditional Access using Azure Active Directory Device Registration.

IMPORTANT
Devices must be located in the same forest as the users. Since devices must be written back to a single forest, this feature
does not currently support a deployment with multiple user forests.
Only one device registration configuration object can be added to the on-premises Active Directory forest. This feature is not
compatible with a topology where the on-premises Active Directory is synchronized to multiple Azure AD tenants.

Part 1: Install Azure AD Connect


1. Install Azure AD Connect using Custom or Express settings. Microsoft recommends to start with all users and
groups successfully synchronized before you enable device writeback.

Part 2: Prepare Active Directory


Use the following steps to prepare for using device writeback.
1. From the machine where Azure AD Connect is installed, launch PowerShell in elevated mode.
2. If the Active Directory PowerShell module is NOT installed, install the Remote Server Administration Tools,
which contains the AD PowerShell module and dsacls.exe, which is required to run the script. Run the
following command:

Add-WindowsFeature RSAT-AD-Tools

3. If the Azure Active Directory PowerShell module is NOT installed, then download and install it from Azure
Active Directory Module for Windows PowerShell (64-bit version). This component has a dependency on
the sign-in assistant, which is installed with Azure AD Connect.
4. With enterprise admin credentials, run the following commands and then exit PowerShell.

Import-Module 'C:\Program Files\Microsoft Azure Active Directory Connect\AdPrep\AdSyncPrep.psm1'


Initialize-ADSyncDeviceWriteback {Optional:–DomainName [name] Optional:-AdConnectorAccount [account]}

Enterprise admin credentials are required since changes to the configuration namespace are needed. A domain
admin will not have enough permissions.

Description:
If they do not exist already, creates and configures new containers and objects under CN=Device Registration
Configuration,CN=Services,CN=Configuration,[forest-dn].
If they do not exist already, creates and configures new containers and objects under CN=RegisteredDevices,
[domain-dn]. Device objects will be created in this container.
Sets necessary permissions on the Azure AD Connector account, to manage devices on your Active Directory.
Only needs to run on one forest, even if Azure AD Connect is being installed on multiple forests.
Parameters:
DomainName: Active Directory Domain where device objects will be created. Note: All devices for a given
Active Directory forest will be created in a single domain.
AdConnectorAccount: Active Directory account that will be used by Azure AD Connect to manage objects in the
directory. This is the account used by Azure AD Connect sync to connect to AD. If you installed using express
settings, it is the account prefixed with MSOL_.

Part 3: Enable device writeback in Azure AD Connect


Use the following procedure to enable device writeback in Azure AD Connect.
1. Run the installation wizard again. Select customize synchronization options from the Additional Tasks page
and click Next.
2. In the Optional Features page, device writeback will no longer be grayed out. Please note that if the Azure AD
Connect prep steps are not completed device writeback will be grayed out in the Optional features page. Check
the box for device writeback and click next. If the checkbox is still disabled, see the troubleshooting section.

3. On the writeback page, you will see the supplied domain as the default Device writeback forest.
4. Complete the installation of the Wizard with no additional configuration changes. If needed, refer to Custom
installation of Azure AD Connect.
5. If you have enabled filtering in Azure AD Connect, then make sure the newly created container
CN=RegisteredDevices is included in your scope.

Part 4: Verify Devices are synchronized to Active Directory


Device writeback should now be working properly. Be aware that it can take up to 3 hours for device objects to be
written-back to AD. To verify that your devices are being synced properly, do the following after the sync
completes:
1. Launch Active Directory Administrative Center.
2. Expand RegisteredDevices, within the domain that was configured in Part 2.
3. Current registered devices will be listed there.

Enable conditional access


Detailed instructions to enable this scenario are available within Setting up On-premises Conditional Access using
Azure Active Directory Device Registration.

Troubleshooting
The writeback checkbox is still disabled
If the checkbox for device writeback is not enabled even though you have followed the steps above, the following
steps will guide you through what the installation wizard is verifying before the box is enabled.
First things first:
Make sure at least one forest has Windows Server 2012R2. The device object type must be present.
If the installation wizard is already running, then any changes will not be detected. In this case, complete the
installation wizard and run it again.
Make sure the account you provide in the initialization script is actually the correct user used by the Active
Directory Connector. To verify this, follow these steps:
From the start menu, open Synchronization Service.
Open the Connectors tab.
Find the Connector with type Active Directory Domain Services and select it.
Under Actions, select Properties.
Go to Connect to Active Directory Forest. Verify that the domain and user name specified on this
screen match the account provided to the script.

Verify configuration in Active Directory:


Verify that the Device Registration Service is located in the location below
(CN=DeviceRegistrationService,CN=Device Registration Services,CN=Device Registration
Configuration,CN=Services,CN=Configuration) under the configuration naming context.

Verify there is only one configuration object by searching the configuration namespace. If there is more than
one, delete the duplicate.

On the Device Registration Service object, make sure the attribute msDS-DeviceLocation is present and has a
value. Lookup this location and make sure it is present with the objectType msDS-DeviceContainer.
Verify the account used by the Active Directory Connector has required permissions on the Registered Devices
container found by the previous step. This is the expected permissions on this container:

Verify the Active Directory account has permissions on the CN=Device Registration
Configuration,CN=Services,CN=Configuration object.
Additional Information
Managing Risk With Conditional Access
Setting up On-premises Conditional Access using Azure Active Directory Device Registration

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect user sign-in options
12/11/2017 • 11 min to read • Edit Online

Azure Active Directory (Azure AD) Connect allows your users to sign in to both cloud and on-premises resources
by using the same passwords. This article describes key concepts for each identity model to help you choose the
identity that you want to use for signing in to Azure AD.
If you’re already familiar with the Azure AD identity model and want to learn more about a specific method, see
the appropriate link:
Password hash synchronization with Seamless Single Sign-on (SSO)
Pass-through authentication with Seamless Single Sign-on (SSO)
Federated SSO (with Active Directory Federation Services (AD FS))

NOTE
It is important to remember that by configuring federation for Azure AD, you establish trust between your Azure AD tenant
and your federated domains. With this trust federated domain users will have access to Azure AD cloud resources within the
tenant.

Choosing the user sign-in method for your organization


For most organizations that just want to enable user sign-in to Office 365, SaaS applications, and other Azure AD-
based resources, we recommend the default password hash synchronization option. Some organizations, however,
have a particular reason that they aren't able to use this option. They can choose either a federated sign-in option,
such as AD FS, or pass-through authentication. You can use the following table to help you make the right choice.

I NEED TO PHS WITH SSO PTA WITH SSO AD FS

Sync new user, contact, and x x x


group accounts in on-
premises Active Directory to
the cloud automatically.

Set up my tenant for Office x x x


365 hybrid scenarios.

Enable my users to sign in x x x


and access cloud services by
using their on-premises
password.

Implement single sign-on by x x x


using corporate credentials.

Ensure that no passwords x* x


are stored in the cloud.

Enable on-premises multi- x


factor authentication
solutions.
*Through a lightweight agent.
Password hash synchronization
With password hash synchronization, hashes of user passwords are synchronized from on-premises Active
Directory to Azure AD. When passwords are changed or reset on-premises, the new password hashes are
synchronized to Azure AD immediately so that your users can always use the same password for cloud resources
and on-premises resources. The passwords are never sent to Azure AD or stored in Azure AD in clear text. You can
use password hash synchronization together with password write-back to enable self-service password reset in
Azure AD.
In addition, you can enable Seamless SSO for users on domain-joined machines that are on the corporate network.
With single sign-on, enabled users only need to enter a username to help them securely access cloud resources.

For more information, see the password hash synchronization article.


Pass-through authentication
With pass-through authentication, the user’s password is validated against the on-premises Active Directory
controller. The password doesn't need to be present in Azure AD in any form. This allows for on-premises policies,
such as sign-in hour restrictions, to be evaluated during authentication to cloud services.
Pass-through authentication uses a simple agent on a Windows Server 2012 R2 domain-joined machine in the on-
premises environment. This agent listens for password validation requests. It doesn't require any inbound ports to
be open to the Internet.
In addition, you can also enable single sign-on for users on domain-joined machines that are on the corporate
network. With single sign-on, enabled users only need to enter a username to help them securely access cloud
resources.

For more information, see:


Pass-through authentication
Single sign-on
Federation that uses a new or existing farm with AD FS in Windows Server 2012 R2
With federated sign-in, your users can sign in to Azure AD-based services with their on-premises passwords.
While they're on the corporate network, they don't even have to enter their passwords. By using the federation
option with AD FS, you can deploy a new or existing farm with AD FS in Windows Server 2012 R2. If you choose to
specify an existing farm, Azure AD Connect configures the trust between your farm and Azure AD so that your
users can sign in.
Deploy federation with AD FS in Windows Server 2012 R2
If you're deploying a new farm, you need:
A Windows Server 2012 R2 server for the federation server.
A Windows Server 2012 R2 server for the Web Application Proxy.
A .pfx file with one SSL certificate for your intended federation service name. For example: fs.contoso.com.
If you're deploying a new farm or using an existing farm, you need:
Local administrator credentials on your federation servers.
Local administrator credentials on any workgroup servers (not domain-joined) that you intend to deploy the
Web Application Proxy role on.
The machine that you run the wizard on to be able to connect to any other machines that you want to install AD
FS or Web Application Proxy on by using Windows Remote Management.
For more information, see Configuring SSO with AD FS.
Sign in by using an earlier version of AD FS or a third-party solution
If you've already configured cloud sign-in by using an earlier version of AD FS (such as AD FS 2.0) or a third-party
federation provider, you can choose to skip user sign-in configuration through Azure AD Connect. This will enable
you to get the latest synchronization and other capabilities of Azure AD Connect while still using your existing
solution for sign-in.
For more information, see the Azure AD third-party federation compatibility list.

User sign-in and user principal name


Understanding user principal name
In Active Directory, the default user principal name (UPN) suffix is the DNS name of the domain where the user
account was created. In most cases, this is the domain name that's registered as the enterprise domain on the
Internet. However, you can add more UPN suffixes by using Active Directory Domains and Trusts.
The UPN of the user has the format username@domain. For example, for an Active Directory domain named
"contoso.com", a user named John might have the UPN "john@contoso.com". The UPN of the user is based on
RFC 822. Although the UPN and email share the same format, the value of the UPN for a user might or might not
be the same as the email address of the user.
User principal name in Azure AD
The Azure AD Connect wizard uses the userPrincipalName attribute or lets you specify the attribute (in a custom
installation) to be used from on-premises as the user principal name in Azure AD. This is the value that is used for
signing in to Azure AD. If the value of the userPrincipalName attribute doesn't correspond to a verified domain in
Azure AD, then Azure AD replaces it with a default .onmicrosoft.com value.
Every directory in Azure Active Directory comes with a built-in domain name, with the format
contoso.onmicrosoft.com, that lets you get started using Azure or other Microsoft services. You can improve and
simplify the sign-in experience by using custom domains. For information on custom domain names in Azure AD
and how to verify a domain, see Add your custom domain name to Azure Active Directory.

Azure AD sign-in configuration


Azure AD sign-in configuration with Azure AD Connect
The Azure AD sign-in experience depends on whether Azure AD can match the user principal name suffix of a user
that's being synced to one of the custom domains that are verified in the Azure AD directory. Azure AD Connect
provides help while you configure Azure AD sign-in settings, so that the user sign-in experience in the cloud is
similar to the on-premises experience.
Azure AD Connect lists the UPN suffixes that are defined for the domains and tries to match them with a custom
domain in Azure AD. Then it helps you with the appropriate action that needs to be taken. The Azure AD sign-in
page lists the UPN suffixes that are defined for on-premises Active Directory and displays the corresponding status
against each suffix. The status values can be one of the following:

STATE DESCRIPTION ACTION NEEDED

Verified Azure AD Connect found a matching No action is needed.


verified domain in Azure AD. All users
for this domain can sign in by using
their on-premises credentials.

Not verified Azure AD Connect found a matching Verify the custom domain in Azure AD.
custom domain in Azure AD, but it isn't
verified. The UPN suffix of the users of
this domain will be changed to the
default .onmicrosoft.com suffix after
synchronization if the domain isn't
verified.

Not added Azure AD Connect didn't find a custom Add and verify a custom domain that
domain that corresponded to the UPN corresponds to the UPN suffix.
suffix. The UPN suffix of the users of
this domain will be changed to the
default .onmicrosoft.com suffix if the
domain isn't added and verified in
Azure.

The Azure AD sign-in page lists the UPN suffixes that are defined for on-premises Active Directory and the
corresponding custom domain in Azure AD with the current verification status. In a custom installation, you can
now select the attribute for the user principal name on the Azure AD sign-in page.
You can click the refresh button to re-fetch the latest status of the custom domains from Azure AD.
Selecting the attribute for the user principal name in Azure AD
The attribute userPrincipalName is the attribute that users use when they sign in to Azure AD and Office 365. You
should verify the domains (also known as UPN suffixes) that are used in Azure AD before the users are
synchronized.
We strongly recommend that you keep the default attribute userPrincipalName. If this attribute is nonroutable and
can't be verified, then it's possible to select another attribute (email, for example) as the attribute that holds the
sign-in ID. This is known as the Alternate ID. The Alternate ID attribute value must follow the RFC 822 standard.
You can use an Alternate ID with both password SSO and federation SSO as the sign-in solution.

NOTE
Using an Alternate ID isn't compatible with all Office 365 workloads. For more information, see Configuring Alternate Login
ID.

Different custom domain states and their effect on the Azure sign-in experience
It's very important to understand the relationship between the custom domain states in your Azure AD directory
and the UPN suffixes that are defined on-premises. Let's go through the different possible Azure sign-in
experiences when you're setting up synchronization by using Azure AD Connect.
For the following information, let's assume that we're concerned with the UPN suffix contoso.com, which is used in
the on-premises directory as part of UPN--for example user@contoso.com.
E x p re s s s e t t i n g s /P a s s w o rd h a s h s y n c h ro n i z a t i o n

STATE EFFECT ON USER AZURE SIGN-IN EXPERIENCE


STATE EFFECT ON USER AZURE SIGN-IN EXPERIENCE

Not added In this case, no custom domain for contoso.com has been
added in the Azure AD directory. Users who have UPN on-
premises with the suffix @contoso.com won't be able to use
their on-premises UPN to sign in to Azure. They'll instead
have to use a new UPN that's provided to them by Azure AD
by adding the suffix for the default Azure AD directory. For
example, if you're syncing users to the Azure AD directory
azurecontoso.onmicrosoft.com, then the on-premises user
user@contoso.com will be given a UPN of
user@azurecontoso.onmicrosoft.com.

Not verified In this case, we have a custom domain contoso.com that's


added in the Azure AD directory. However, it's not yet
verified. If you go ahead with syncing users without verifying
the domain, then the users will be assigned a new UPN by
Azure AD, just like in the "Not added" scenario.

Verified In this case, we have a custom domain contoso.com that's


already added and verified in Azure AD for the UPN suffix.
Users will be able to use their on-premises user principal
name, for example user@contoso.com, to sign in to Azure
after they're synced to Azure AD.
A D F S f e d e ra t i o n

You can't create a federation with the default .onmicrosoft.com domain in Azure AD or an unverified custom
domain in Azure AD. When you're running the Azure AD Connect wizard, if you select an unverified domain to
create a federation with, then Azure AD Connect prompts you with the necessary records to be created where your
DNS is hosted for the domain. For more information, see Verify the Azure AD domain selected for federation.
If you selected the user sign-in option Federation with AD FS, then you must have a custom domain to continue
creating a federation in Azure AD. For our discussion, this means that we should have a custom domain
contoso.com added in the Azure AD directory.

STATE EFFECT ON THE USER AZURE SIGN-IN EXPERIENCE

Not added In this case, Azure AD Connect didn't find a matching custom
domain for the UPN suffix contoso.com in the Azure AD
directory. You need to add a custom domain contoso.com if
you need users to sign in by using AD FS with their on-
premises UPN (like user@contoso.com).

Not verified In this case, Azure AD Connect prompts you with appropriate
details on how you can verify your domain at a later stage.

Verified In this case, you can go ahead with the configuration without
any further action.

Changing the user sign-in method


You can change the user sign-in method from federation, password hash synchronization, or pass-through
authentication by using the tasks that are available in Azure AD Connect after the initial configuration of Azure AD
Connect with the wizard. Run the Azure AD Connect wizard again, and you'll see a list of tasks that you can
perform. Select Change user sign-in from the list of tasks.
On the next page, you're asked to provide the credentials for Azure AD.

On the User sign-in page, select the desired user sign-in.


NOTE
If you're only making a temporary switch to password hash synchronization, then select the Do not convert user accounts
check box. Not checking the option will convert each user to federated, and it can take several hours.

Next steps
Learn more about integrating your on-premises identities with Azure Active Directory.
Learn more about Azure AD Connect design concepts.
Azure Active Directory Seamless Single Sign-On
3/7/2018 • 2 min to read • Edit Online

What is Azure Active Directory Seamless Single Sign-On?


Azure Active Directory Seamless Single Sign-On (Azure AD Seamless SSO) automatically signs users in when
they are on their corporate devices connected to your corporate network. When enabled, users don't need to
type in their passwords to sign in to Azure AD, and usually, even type in their usernames. This feature provides
your users easy access to your cloud-based applications without needing any additional on-premises
components.

Seamless SSO can be combined with either the Password Hash Synchronization or Pass-through Authentication
sign-in methods.

IMPORTANT
Seamless SSO is not applicable to Active Directory Federation Services (ADFS).

Key benefits
Great user experience
Users are automatically signed into both on-premises and cloud-based applications.
Users don't have to enter their passwords repeatedly.
Easy to deploy & administer
No additional components needed on-premises to make this work.
Works with any method of cloud authentication - Password Hash Synchronization or Pass-through
Authentication.
Can be rolled out to some or all your users using Group Policy.
Register non-Windows 10 devices with Azure AD without the need for any AD FS infrastructure. This
capability needs you to use version 2.1 or later of the workplace-join client.

Feature highlights
Sign-in username can be either the on-premises default username ( userPrincipalName ) or another attribute
configured in Azure AD Connect ( Alternate ID ). Both use cases work because Seamless SSO uses the
securityIdentifier claim in the Kerberos ticket to look up the corresponding user object in Azure AD.
Seamless SSO is an opportunistic feature. If it fails for any reason, the user sign-in experience goes back to its
regular behavior - i.e, the user needs to enter their password on the sign-in page.
If an application forwards a domain_hint (OpenID Connect) or whr (SAML) parameter - identifying your
tenant, or login_hint parameter - identifying the user, in its Azure AD sign-in request, users are
automatically signed in without them entering usernames or passwords.
Sign out is supported. This allows users to choose another Azure AD account to sign in with, instead of being
automatically signed in using Seamless SSO automatically.
Office 365 clients (16.0.8730.xxxx and above) are supported using a non-interactive flow.
It can be enabled via Azure AD Connect.
It is a free feature, and you don't need any paid editions of Azure AD to use it.
It is supported on web browser-based clients and Office clients that support modern authentication on
platforms and browsers capable of Kerberos authentication:

INTERNET
OS\BROWSER EXPLORER EDGE GOOGLE CHROME MOZILLA FIREFOX SAFARI

Windows 10 Yes No Yes Yes* N/A

Windows 8.1 Yes N/A Yes Yes* N/A

Windows 8 Yes N/A Yes Yes* N/A

Windows 7 Yes N/A Yes Yes* N/A

Mac OS X N/A N/A Yes* Yes* Yes*

*Requires additional configuration

NOTE
For Windows 10, the recommendation is to use Azure AD Join for the optimal single sign-on experience with Azure AD.

Next steps
Quick Start - Get up and running Azure AD Seamless SSO.
Technical Deep Dive - Understand how this feature works.
Frequently Asked Questions - Answers to frequently asked questions.
Troubleshoot - Learn how to resolve common issues with the feature.
UserVoice - For filing new feature requests.
Azure Active Directory Seamless Single Sign-On:
Quick start
3/13/2018 • 6 min to read • Edit Online

Deploy Seamless Single Sign-On


Azure Active Directory (Azure AD) Seamless Single Sign-On (Seamless SSO) automatically signs in users when
they are on their corporate desktops that are connected to your corporate network. Seamless SSO provides your
users with easy access to your cloud-based applications without needing any additional on-premises components.
To deploy Seamless SSO, follow these steps.

Step 1: Check the prerequisites


Ensure that the following prerequisites are in place:
Set up your Azure AD Connect server: If you use Pass-through Authentication as your sign-in method, no
additional prerequisite check is required. If you use password hash synchronization as your sign-in method,
and if there is a firewall between Azure AD Connect and Azure AD, ensure that:
You use version 1.1.644.0 or later of Azure AD Connect.
If your firewall or proxy allows DNS whitelisting, whitelist the connections to the *.msappproxy.net
URLs over port 443. If not, allow access to the Azure datacenter IP ranges, which are updated weekly.
This prerequisite is applicable only when you enable the feature. It is not required for actual user
sign-ins.

NOTE
Azure AD Connect versions 1.1.557.0, 1.1.558.0, 1.1.561.0, and 1.1.614.0 have a problem related to
password hash synchronization. If you don't intend to use password hash synchronization in conjunction with
Pass-through Authentication, read the Azure AD Connect release notes to learn more.

Set up domain administrator credentials: You need to have domain administrator credentials for each
Active Directory forest that:
You synchronize to Azure AD through Azure AD Connect.
Contains users you want to enable for Seamless SSO.

Step 2: Enable the feature


Enable Seamless SSO through Azure AD Connect.
If you're doing a fresh installation of Azure AD Connect, choose the custom installation path. At the User sign-in
page, select the Enable single sign on option.
If you already have an installation of Azure AD Connect, select the Change user sign-in page in Azure AD
Connect, and then select Next.

Continue through the wizard until you get to the Enable single sign on page. Provide domain administrator
credentials for each Active Directory forest that:
You synchronize to Azure AD through Azure AD Connect.
Contains users you want to enable for Seamless SSO.
After completion of the wizard, Seamless SSO is enabled on your tenant.

NOTE
The domain administrator credentials are not stored in Azure AD Connect or in Azure AD. They're used only to enable the
feature.

Follow these instructions to verify that you have enabled Seamless SSO correctly:
1. Sign in to the Azure Active Directory administrative center with the global administrator credentials for your
tenant.
2. Select Azure Active Directory in the left pane.
3. Select Azure AD Connect.
4. Verify that the Seamless single sign-on feature appears as Enabled.

Step 3: Roll out the feature


To roll out the feature to your users, you need to add the following Azure AD URL to the users' Intranet zone
settings by using Group Policy in Active Directory:
https://autologon.microsoftazuread-sso.com
In addition, you need to enable an Intranet zone policy setting called Allow updates to status bar via script
through Group Policy.

NOTE
The following instructions work only for Internet Explorer and Google Chrome on Windows (if it shares a set of trusted site
URLs with Internet Explorer). Read the next section for instructions on how to set up Mozilla Firefox and Google Chrome on
Mac.
Why do you need to modify users' Intranet zone settings?
By default, the browser automatically calculates the correct zone, either Internet or Intranet, from a specific URL.
For example, "http://contoso/" maps to the Intranet zone, whereas "http://intranet.contoso.com/" maps to the
Internet zone (because the URL contains a period). Browsers will not send Kerberos tickets to a cloud endpoint, like
the Azure AD URL, unless you explicitly add the URL to the browser's Intranet zone.
Detailed steps
1. Open the Group Policy Management Editor tool.
2. Edit the group policy that's applied to some or all your users. This example uses Default Domain Policy.
3. Browse to User Configuration > Administrative Templates > Windows Components > Internet Explorer
> Internet Control Panel > Security Page. Then select Site to Zone Assignment List.

4. Enable the policy, and then enter the following values in the dialog box:
Value name: The Azure AD URL where the Kerberos tickets are forwarded.
Value (Data): 1 indicates the Intranet zone.
The result looks like this:
Value: https://autologon.microsoftazuread-sso.com
Data: 1

NOTE
If you want to disallow some users from using Seamless SSO (for instance, if these users sign in on shared kiosks), set
the preceding values to 4. This action adds the Azure AD URL to the Restricted zone, and fails Seamless SSO all the
time.

5. Select OK, and then select OK again.


6. Browse to User Configuration > Administrative Templates > Windows Components > Internet
Explorer > Internet Control Panel > Security Page > Intranet Zone. Then select Allow updates to
status bar via script.

7. Enable the policy setting, and then select OK.


Browser considerations
Mozilla Firefox (all platforms )
Mozilla Firefox doesn't automatically use Kerberos authentication. Each user must manually add the Azure AD URL
to their Firefox settings by using the following steps:
1. Run Firefox and enter about:config in the address bar. Dismiss any notifications that you see.
2. Search for the network.negotiate-auth.trusted-uris preference. This preference lists Firefox's trusted sites for
Kerberos authentication.
3. Right-click and select Modify.
4. Enter https://autologon.microsoftazuread-sso.com in the field.
5. Select OK and then reopen the browser.
Safari (Mac OS)
Ensure that the machine running the Mac OS is joined to AD. For instructions on joining AD, see Best Practices for
Integrating OS X with Active Directory.
Google Chrome (all platforms )
If you have overriden the AuthNegotiateDelegateWhitelist or the AuthServerWhitelist policy settings in your
environment, ensure that you add Azure AD's URL (https://autologon.microsoftazuread-sso.com) to them as well.
Google Chrome (Mac OS only )
For Google Chrome on Mac OS and other non-Windows platforms, refer to The Chromium Project Policy List for
information on how to whitelist the Azure AD URL for integrated authentication.
The use of third-party Active Directory Group Policy extensions to roll out the Azure AD URL to Firefox and Google
Chrome on Mac users is outside the scope of this article.
Known browser limitations
Seamless SSO doesn't work in private browsing mode on Firefox and Edge browsers. It also doesn't work on
Internet Explorer if the browser is running in Enhanced Protected mode.

Step 4: Test the feature


To test the feature for a specific user, ensure that all the following conditions are in place:
The user signs in on a corporate device.
The device is joined to your Active Directory domain.
The device has a direct connection to your domain controller (DC), either on the corporate wired or wireless
network or via a remote access connection, such as a VPN connection.
You have rolled out the feature to this user through Group Policy.
To test the scenario where the user enters only the username, but not the password:
Sign in to https://myapps.microsoft.com/ in a new private browser session.
To test the scenario where the user doesn't have to enter the username or the password, use one of these steps:
Sign in to https://myapps.microsoft.com/contoso.onmicrosoft.com in a new private browser session. Replace
contoso with your tenant's name.
Sign in to https://myapps.microsoft.com/contoso.com in a new private browser session. Replace contoso.com
with a verified domain (not a federated domain) on your tenant.

Step 5: Roll over keys


In Step 2, Azure AD Connect creates computer accounts (representing Azure AD) in all the Active Directory forests
on which you have enabled Seamless SSO. To learn more, see Azure Active Directory Seamless Single Sign-On:
Technical deep dive. For improved security, we recommend that you periodically roll over the Kerberos decryption
keys of these computer accounts. For instructions on how to roll over keys, see Azure Active Directory Seamless
Single Sign-On: Frequently asked questions.

IMPORTANT
You don't need to do this step immediately after you have enabled the feature. Roll over the Kerberos decryption keys at
least once every 30 days.

Next steps
Technical deep dive: Understand how the Seamless Single Sign-On feature works.
Frequently asked questions: Get answers to frequently asked questions about Seamless Single Sign-On.
Troubleshoot: Learn how to resolve common problems with the Seamless Single Sign-On feature.
UserVoice: Use the Azure Active Directory Forum to file new feature requests.
Azure Active Directory Seamless Single Sign-On:
Technical deep dive
3/7/2018 • 3 min to read • Edit Online

This article gives you technical details into how the Azure Active Directory Seamless Single Sign-On (Seamless
SSO) feature works.

How does Seamless SSO work?


This section has three parts to it:
1. The setup of the Seamless SSO feature.
2. How a single user sign-in transaction on a web browser works with Seamless SSO.
3. How a single user sign-in transaction on a native client works with Seamless SSO.
How does set up work?
Seamless SSO is enabled using Azure AD Connect as shown here. While enabling the feature, the following steps
occur:
A computer account named AZUREADSSOACC (which represents Azure AD) is created in your on-premises Active
Directory (AD).
The computer account's Kerberos decryption key is shared securely with Azure AD.
In addition, two Kerberos service principal names (SPNs) are created to represent two URLs that are used
during Azure AD sign-in.

NOTE
The computer account and the Kerberos SPNs are created in each AD forest you synchronize to Azure AD (using Azure AD
Connect) and for whose users you want Seamless SSO. Move the AZUREADSSOACC computer account to an Organization
Unit (OU) where other computer accounts are stored to ensure that it is managed in the same way and is not deleted.

IMPORTANT
We highly recommend that you roll over the Kerberos decryption key of the AZUREADSSOACC computer account at least
every 30 days.

Once the set-up is complete, Seamless SSO works the same way as any other sign-in that uses Integrated
Windows Authentication (IWA).
How does sign-in on a web browser with Seamless SSO work?
The sign-in flow on a web browser is as follows:
1. The user tries to access a web application (for example, the Outlook Web App -
https://outlook.office365.com/owa/) from a domain-joined corporate device inside your corporate network.
2. If the user is not already signed in, the user is redirected to the Azure AD sign-in page.
3. The user types in their user name into the Azure AD sign-in page.
NOTE
For certain applications, steps 2 & 3 are skipped.

4. Using JavaScript in the background, Azure AD challenges the browser, via a 401 Unauthorized response, to
provide a Kerberos ticket.
5. The browser, in turn, requests a ticket from Active Directory for the AZUREADSSOACC computer account (which
represents Azure AD).
6. Active Directory locates the computer account and returns a Kerberos ticket to the browser encrypted with the
computer account's secret.
7. The browser forwards the Kerberos ticket it acquired from Active Directory to Azure AD.
8. Azure AD decrypts the Kerberos ticket, which includes the identity of the user signed into the corporate device,
using the previously shared key.
9. After evaluation, Azure AD either returns a token back to the application or asks the user to perform additional
proofs, such as Multi-Factor Authentication.
10. If the user sign-in is successful, the user is able to access the application.
The following diagram illustrates all the components and the steps involved.

Seamless SSO is opportunistic, which means if it fails, the sign-in experience falls back to its regular behavior - i.e,
the user needs to enter their password to sign in.
How does sign-in on a native client with Seamless SSO work?
The sign-in flow on a native client is as follows:
1. The user tries to access a native application (for example, the Outlook client) from a domain-joined corporate
device inside your corporate network.
2. If the user is not already signed in, the native application retrieves the username of the user from the device's
Windows session.
3. The app sends the username to Azure AD, and retrieves your tenant's WS-Trust MEX endpoint.
4. The app then queries the WS-Trust MEX endpoint to see if integrated authentication endpoint is available.
5. If step 4 succeeds, a Kerberos challenge is issued.
6. If the app is able to retrieve the Kerberos ticket, it forwards it up to Azure AD's integrated authentication
endpoint.
7. Azure AD decrypts the Kerberos ticket and validates it.
8. Azure AD signs the user in, and issues a SAML token to the app.
9. The app then submits the SAML token to Azure AD's OAuth2 token endpoint.
10. Azure AD validates the SAML token, and issues to the app an access token and a refresh token for the specified
resource, and an id token.
11. The user gets access to the app's resource.
The following diagram illustrates all the components and the steps involved.

Next steps
Quick Start - Get up and running Azure AD Seamless SSO.
Frequently Asked Questions - Answers to frequently asked questions.
Troubleshoot - Learn how to resolve common issues with the feature.
UserVoice - For filing new feature requests.
Azure Active Directory Seamless Single Sign-On:
Frequently asked questions
3/14/2018 • 4 min to read • Edit Online

In this article, we address frequently asked questions about Azure Active Directory Seamless Single Sign-On
(Seamless SSO). Keep checking back for new content.

What sign-in methods do Seamless SSO work with?


Seamless SSO can be combined with either the Password Hash Synchronization or Pass-through Authentication
sign-in methods. However this feature cannot be used with Active Directory Federation Services (ADFS).

Is Seamless SSO a free feature?


Seamless SSO is a free feature and you don't need any paid editions of Azure AD to use it.

Is Seamless SSO available in the Microsoft Azure Germany cloud and


the Microsoft Azure Government cloud?
No. Seamless SSO is only available in the worldwide instance of Azure AD.

What applications take advantage of domain_hint or login_hint


parameter capability of Seamless SSO?
Listed below is a non-exhaustive list of applications that send these parameters to Azure AD, and therefore
provides users a silent sign-on experience using Seamless SSO:

APPLICATION NAME APPLICATION URL TO BE USED

Access panel myapps.microsoft.com/contoso.com

Outlook on Web outlook.office365.com/contoso.com

In the above table, replace "contoso.com" with your domain name to get to the right application URLs for your
tenant.
If you have other applications that you are interested in, let us know in the comments section.

Does Seamless SSO support Alternate ID as the username, instead of


userPrincipalName ?
Yes. Seamless SSO supports Alternate ID as the username when configured in Azure AD Connect as shown here.
Not all Office 365 applications support Alternate ID . Refer to the specific application's documentation for the
support statement.

What is the difference between the single sign-on experience provided


by Azure AD Join and Seamless SSO?
Azure AD Join provides SSO to users if their devices are registered with Azure AD. These devices don't necessarily
have to be domain-joined. SSO is provided using primary refresh tokens or PRTs, and not Kerberos. The user
experience is most optimal on Windows 10 devices. SSO happens automatically on the Edge browser. It also works
on Chrome with the use of a browser extension.
You can use both Azure AD Join and Seamless SSO on your tenant. These two features are complementary. If both
features are turned on, then SSO from Azure AD Join takes precedence over Seamless SSO.

I want to register non-Windows 10 devices with Azure AD, without


using AD FS. Can I use Seamless SSO instead?
Yes, this scenario needs version 2.1 or later of the workplace-join client.

How can I roll over the Kerberos decryption key of the AZUREADSSOACC
computer account?
It is important to frequently roll over the Kerberos decryption key of the AZUREADSSOACC computer account (which
represents Azure AD) created in your on-premises AD forest.

IMPORTANT
We highly recommend that you roll over the Kerberos decryption key at least every 30 days.

Follow these steps on the on-premises server where you are running Azure AD Connect:
Step 1. Get list of AD forests where Seamless SSO has been enabled
1. First, download, and install the Microsoft Online Services Sign-In Assistant.
2. Then download and install the 64-bit Azure Active Directory module for Windows PowerShell.
3. Navigate to the %programfiles%\Microsoft Azure Active Directory Connect folder.
4. Import the Seamless SSO PowerShell module using this command: Import-Module .\AzureADSSO.psd1 .
5. Run PowerShell as an Administrator. In PowerShell, call New-AzureADSSOAuthenticationContext . This command
should give you a popup to enter your tenant's Global Administrator credentials.
6. Call Get-AzureADSSOStatus . This command provides you the list of AD forests (look at the "Domains" list) on
which this feature has been enabled.
Step 2. Update the Kerberos decryption key on each AD forest that it was set it up on
1. Call $creds = Get-Credential . When prompted, enter the Domain Administrator credentials for the intended AD
forest.
2. Call Update-AzureADSSOForest -OnPremCredentials $creds . This command updates the Kerberos decryption key
for the AZUREADSSOACC computer account in this specific AD forest and updates it in Azure AD.
3. Repeat the preceding steps for each AD forest that you’ve set up the feature on.

IMPORTANT
Ensure that you don't run the Update-AzureADSSOForest command more than once. Otherwise, the feature stops working
until the time your users' Kerberos tickets expire and are reissued by your on-premises Active Directory.

How can I disable Seamless SSO?


Seamless SSO can be disabled using Azure AD Connect.
Run Azure AD Connect, choose "Change user sign-in page" and click "Next". Then uncheck the "Enable single sign
on" option. Continue through the wizard. After completion of the wizard, Seamless SSO is disabled on your tenant.
However, you see a message on screen that reads as follows:
"Single sign-on is now disabled, but there are additional manual steps to perform in order to complete clean-up.
Learn more"
To complete the process, follow these manual steps on the on-premises server where you are running Azure AD
Connect:
Step 1. Get list of AD forests where Seamless SSO has been enabled
1. First, download, and install the Microsoft Online Services Sign-In Assistant.
2. Then download and install the 64-bit Azure Active Directory module for Windows PowerShell.
3. Navigate to the %programfiles%\Microsoft Azure Active Directory Connect folder.
4. Import the Seamless SSO PowerShell module using this command: Import-Module .\AzureADSSO.psd1 .
5. Run PowerShell as an Administrator. In PowerShell, call New-AzureADSSOAuthenticationContext . This command
should give you a popup to enter your tenant's Global Administrator credentials.
6. Call Get-AzureADSSOStatus . This command provides you the list of AD forests (look at the "Domains" list) on
which this feature has been enabled.
Step 2. Manually delete the AZUREADSSOACCT computer account from each AD forest that you see listed.

Next steps
Quick Start - Get up and running Azure AD Seamless SSO.
Technical Deep Dive - Understand how this feature works.
Troubleshoot - Learn how to resolve common issues with the feature.
UserVoice - For filing new feature requests.
Troubleshoot Azure Active Directory Seamless Single
Sign-On
3/13/2018 • 6 min to read • Edit Online

This article helps you find troubleshooting information about common problems regarding Azure Active Directory
(Azure AD) Seamless Single Sign-On (Seamless SSO).

Known issues
In a few cases, enabling Seamless SSO can take up to 30 minutes.
If you disable and re-enable Seamless SSO on your tenant, users will not get the single sign-on experience till
their cached Kerberos tickets, typically valid for 10 hours, have expired.
Edge browser support is not available.
If Seamless SSO succeeds, the user does not have the opportunity to select Keep me signed in. Due to this
behavior, SharePoint and OneDrive mapping scenarios don't work.
Office clients below version 16.0.8730.xxxx don't support non-interactive sign-in with Seamless SSO. On those
clients, users must enter their usernames, but not passwords, to sign-in.
Seamless SSO doesn't work in private browsing mode on Firefox.
Seamless SSO doesn't work in Internet Explorer when Enhanced Protected mode is turned on.
Seamless SSO doesn't work on mobile browsers on iOS and Android.
If a user is part of too many groups in Active Directory, the user's Kerberos ticket will likely be too large to
process, and this will cause Seamless SSO to fail. Azure AD HTTPS requests can have headers with a maximum
size of 16 KB; Kerberos tickets need to be much smaller than that number to accommodate other Azure AD
artifacts such as cookies. Our recommendation is to reduce user's group memberships and try again.
If you're synchronizing 30 or more Active Directory forests, you can't enable Seamless SSO through Azure AD
Connect. As a workaround, you can manually enable the feature on your tenant.
Adding the Azure AD service URL (https://autologon.microsoftazuread-sso.com) to the Trusted sites zone
instead of the Local intranet zone blocks users from signing in.
Disabling the use of the RC4_HMAC_MD5 encryption type for Kerberos in your Active Directory settings will
break Seamless SSO. In your Group Policy Management Editor tool ensure that the policy value for
RC4_HMAC_MD5 under Computer Configuration -> Windows Settings -> Security Settings -> Local
Policies -> Security Options -> "Network Security: Configure encryption types allowed for Kerberos"
is "Enabled".

Check status of feature


Ensure that the Seamless SSO feature is still Enabled on your tenant. You can check the status by going to the
Azure AD Connect pane in the Azure Active Directory admin center.
Click through to see all the AD forests that have been enabled for Seamless SSO.

Sign-in failure reasons in the Azure Active Directory admin center


(needs a Premium license)
If your tenant has an Azure AD Premium license associated with it, you can also look at the sign-in activity report
in the Azure Active Directory admin center.
Browse to Azure Active Directory > Sign-ins in the Azure Active Directory admin center, and then select a
specific user's sign-in activity. Look for the SIGN-IN ERROR CODE field. Map the value of that field to a failure
reason and resolution by using the following table:

SIGN-IN ERROR CODE SIGN-IN FAILURE REASON RESOLUTION

81001 User's Kerberos ticket is too large. Reduce the user's group memberships
and try again.

81002 Unable to validate the user's Kerberos See the troubleshooting checklist.
ticket.

81003 Unable to validate the user's Kerberos See the troubleshooting checklist.
ticket.

81004 Kerberos authentication attempt failed. See the troubleshooting checklist.

81008 Unable to validate the user's Kerberos See the troubleshooting checklist.
ticket.

81009 Unable to validate the user's Kerberos See the troubleshooting checklist.
ticket.

81010 Seamless SSO failed because the user's The user needs to sign in from a
Kerberos ticket has expired or is invalid. domain-joined device inside your
corporate network.

81011 Unable to find the user object based on Use Azure AD Connect to synchronize
the information in the user's Kerberos the user's information into Azure AD.
ticket.

81012 The user trying to sign in to Azure AD The user needs to sign in from a
is different from the user that is signed different device.
in to the device.
SIGN-IN ERROR CODE SIGN-IN FAILURE REASON RESOLUTION

81013 Unable to find the user object based on Use Azure AD Connect to synchronize
the information in the user's Kerberos the user's information into Azure AD.
ticket.

Troubleshooting checklist
Use the following checklist to troubleshoot Seamless SSO problems:
Ensure that the Seamless SSO feature is enabled in Azure AD Connect. If you can't enable the feature (for
example, due to a blocked port), ensure that you have all the prerequisites in place.
If you have enabled both Azure AD Join and Seamless SSO on your tenant, ensure that the issue is not with
Azure AD Join. SSO from Azure AD Join takes precedence over Seamless SSO if the device is both registered
with Azure AD and domain-joined. With SSO from Azure AD Join the user sees a sign-in tile that says
"Connected to Windows".
Ensure that the Azure AD URL (https://autologon.microsoftazuread-sso.com) is part of the user's Intranet zone
settings.
Ensure that the corporate device is joined to the Active Directory domain.
Ensure that the user is logged on to the device through an Active Directory domain account.
Ensure that the user's account is from an Active Directory forest where Seamless SSO has been set up.
Ensure that the device is connected to the corporate network.
Ensure that the device's time is synchronized with the time in both Active Directory and the domain controllers,
and that they are within five minutes of each other.
List the existing Kerberos tickets on the device by using the klist command from a command prompt. Ensure
that the tickets issued for the AZUREADSSOACCT computer account are present. Users' Kerberos tickets are
typically valid for 10 hours. You might have different settings in Active Directory.
If you disabled and re-enabled Seamless SSO on your tenant, users will not get the single sign-on experience
till their cached Kerberos tickets have expired.
Purge existing Kerberos tickets from the device by using the klist purge command, and try again.
To determine if there are JavaScript-related problems, review the console logs of the browser (under
Developer Tools).
Review the domain controller logs.
Domain controller logs
If you enable success auditing on your domain controller, then every time a user signs in through Seamless SSO, a
security entry is recorded in the event log. You can find these security events by using the following query. (Look
for event 4769 associated with the computer account AzureADSSOAcc$.)

<QueryList>
<Query Id="0" Path="Security">
<Select Path="Security">*[EventData[Data[@Name='ServiceName'] and (Data='AZUREADSSOACC$')]]</Select>
</Query>
</QueryList>

Manual reset of the feature


If troubleshooting didn't help, you can manually reset the feature on your tenant. Follow these steps on the on-
premises server where you're running Azure AD Connect.
Step 1: Import the Seamless SSO PowerShell module
1. Download and install the Microsoft Online Services Sign-In Assistant.
2. Download and install the 64-bit Azure Active Directory module for Windows PowerShell.
3. Browse to the %programfiles%\Microsoft Azure Active Directory Connect folder.
4. Import the Seamless SSO PowerShell module by using this command: Import-Module .\AzureADSSO.psd1 .
Step 2: Get the list of Active Directory forests on which Seamless SSO has been enabled
1. Run PowerShell as an administrator. In PowerShell, call New-AzureADSSOAuthenticationContext . When prompted,
enter your tenant's global administrator credentials.
2. Call Get-AzureADSSOStatus . This command provides you with the list of Active Directory forests (look at the
"Domains" list) on which this feature has been enabled.
Step 3: Disable Seamless SSO for each Active Directory forest where you've set up the feature
1. Call $creds = Get-Credential . When prompted, enter the domain administrator credentials for the intended
Active Directory forest.
2. Call Disable-AzureADSSOForest -OnPremCredentials $creds . This command removes the AZUREADSSOACCT
computer account from the on-premises domain controller for this specific Active Directory forest.
3. Repeat the preceding steps for each Active Directory forest where you’ve set up the feature.
Step 4: Enable Seamless SSO for each Active Directory forest
1. Call Enable-AzureADSSOForest . When prompted, enter the domain administrator credentials for the intended
Active Directory forest.
2. Repeat the preceding step for each Active Directory forest where you want to set up the feature.
Step 5. Enable the feature on your tenant
To turn on the feature on your tenant, call Enable-AzureADSSO and enter true at the Enable: prompt.
Azure AD Seamless Single Sign-On: GDPR
compliance
3/13/2018 • 1 min to read • Edit Online

Overview
In May 2018, a European privacy law, the General Data Protection Regulation (GDPR), is due to take effect. The
GDPR imposes new rules on companies, government agencies, non-profits, and other organizations that offer
goods and services to people in the European Union (EU), or that collect and analyze data tied to EU residents. The
GDPR applies no matter where you are located.
Microsoft products and services are available today to help you meet the GDPR requirements. Read more about
Microsoft Privacy policy at Trust Center.
Azure AD Seamless SSO creates the following log type, which can contain EUII:
Azure AD Connect trace log files.
GDPR compliance for Seamless SSO can be reached in two ways:
1. Upon request, extract data for a person and remove data from that person from the installations.
2. Ensure no data is retained beyond 48 hours.
We strongly recommend the second option as it is easier to implement and maintain. See following instructions for
each log type:
Delete Azure AD Connect trace log files
Check the contents of %ProgramData%\AADConnect folder and delete the trace log contents (trace-*.log files)
of this folder within 48 hours of installing or upgrading Azure AD Connect or modifying Seamless SSO
configuration, as this action may create data covered by GDPR.

IMPORTANT
Don’t delete the PersistedState.xml file in this folder, as this file is used to maintain the state of the previous installation of
Azure AD Connect and is used when an upgrade installation is done. This file will never contain any data about a person and
should never be deleted.

You can either review and delete these trace log files using Windows Explorer or you can use the following
PowerShell script to perform the necessary actions:

$Files = ((Get-Item -Path "$env:programdata\aadconnect\trace-*.log").VersionInfo).FileName

Foreach ($file in $Files) {


{Remove-Item -Path $File -Force}
}

Save the script in a file with the ".PS1" extension. Run this script as needed.
To learn more about related Azure AD Connect GDPR requirements, see this article.
Note about Domain controller logs
If audit logging is enabled, this product may generate security logs for your Domain Controllers. To learn more
about configuring audit policies, read this article.

Next steps
Troubleshoot - Learn how to resolve common issues with the feature.
UserVoice - For filing new feature requests.
User sign-in with Azure Active Directory Pass-
through Authentication
1/9/2018 • 2 min to read • Edit Online

What is Azure Active Directory Pass-through Authentication?


Azure Active Directory (Azure AD) Pass-through Authentication allows your users to sign in to both on-premises
and cloud-based applications using the same passwords. This feature provides your users a better experience -
one less password to remember, and reduces IT helpdesk costs because your users are less likely to forget how to
sign in. When users sign in using Azure AD, this feature validates users' passwords directly against your on-
premises Active Directory.

This feature is an alternative to Azure AD Password Hash Synchronization, which provides the same benefit of
cloud authentication to organizations. However, security and compliance policies in certain organizations don't
permit these organizations to send users' passwords, even in a hashed form, outside their internal boundaries.
Pass-through Authentication is the right solution for such organizations.

You can combine Pass-through Authentication with the Seamless Single Sign-On feature. This way, when your
users are accessing applications on their corporate machines inside your corporate network, they don't need to
type in their passwords to sign in.

Key benefits of using Azure AD Pass-through Authentication


Great user experience
Users use the same passwords to sign into both on-premises and cloud-based applications.
Users spend less time talking to the IT helpdesk resolving password-related issues.
Users can complete self-service password management tasks in the cloud.
Easy to deploy & administer
No need for complex on-premises deployments or network configuration.
Needs just a lightweight agent to be installed on-premises.
No management overhead. The agent automatically receives improvements and bug fixes.
Secure
On-premises passwords are never stored in the cloud in any form.
The agent only makes outbound connections from within your network. Therefore, there is no
requirement to install the agent in a perimeter network, also known as a DMZ.
Protects your user accounts by working seamlessly with Azure AD Conditional Access policies, including
Multi-Factor Authentication (MFA), and by filtering out brute force password attacks.
Highly available
Additional agents can be installed on multiple on-premises servers to provide high availability of sign-in
requests.

Feature highlights
Supports user sign-in into all web browser-based applications and into Microsoft Office client applications that
use modern authentication.
Sign-in usernames can be either the on-premises default username ( userPrincipalName ) or another attribute
configured in Azure AD Connect (known as Alternate ID ).
The feature works seamlessly with conditional access features such as Multi-Factor Authentication (MFA) to
help secure your users.
Integrated with cloud-based self-service password management, including password writeback to on-premises
Active Directory and password protection by banning commonly used passwords.
Multi-forest environments are supported if there are forest trusts between your AD forests and if name suffix
routing is correctly configured.
It is a free feature, and you don't need any paid editions of Azure AD to use it.
It can be enabled via Azure AD Connect.
It uses a lightweight on-premises agent that listens for and responds to password validation requests.
Installing multiple agents provides high availability of sign-in requests.
It protects your on-premises accounts against brute force password attacks in the cloud.

Next steps
Quick Start - Get up and running Azure AD Pass-through Authentication.
Smart Lockout - Configure Smart Lockout capability on your tenant to protect user accounts.
Current limitations - Learn which scenarios are supported and which ones are not.
Technical Deep Dive - Understand how this feature works.
Frequently Asked Questions - Answers to frequently asked questions.
Troubleshoot - Learn how to resolve common issues with the feature.
Security Deep Dive - Additional deep technical information on the feature.
Azure AD Seamless SSO - Learn more about this complementary feature.
UserVoice - For filing new feature requests.
Azure Active Directory Pass-through Authentication:
Quick start
3/7/2018 • 7 min to read • Edit Online

Deploy Azure AD Pass-through Authentication


Azure Active Directory (Azure AD) Pass-through Authentication allows your users to sign in to both on-premises
and cloud-based applications by using the same passwords. Pass-through Authentication signs users in by
validating their passwords directly against on-premises Active Directory.

IMPORTANT
If you use this feature through a preview version, ensure that you upgrade the preview versions of the Authentication
Agents by using the instructions provided in Azure Active Directory Pass-through Authentication: Upgrade preview
Authentication Agents.

Follow these instructions to deploy Pass-through Authentication:

Step 1: Check the prerequisites


Ensure that the following prerequisites are in place.
In the Azure Active Directory admin center
1. Create a cloud-only global administrator account on your Azure AD tenant. This way, you can manage the
configuration of your tenant should your on-premises services fail or become unavailable. Learn about adding
a cloud-only global administrator account. Completing this step is critical to ensure that you don't get locked
out of your tenant.
2. Add one or more custom domain names to your Azure AD tenant. Your users can sign in with one of these
domain names.
In your on-premises environment
1. Identify a server running Windows Server 2012 R2 or later to run Azure AD Connect. Add the server to the
same Active Directory forest as the users whose passwords you need to validate.
2. Install the latest version of Azure AD Connect on the server identified in the preceding step. If you already
have Azure AD Connect running, ensure that the version is 1.1.644.0 or later.

NOTE
Azure AD Connect versions 1.1.557.0, 1.1.558.0, 1.1.561.0, and 1.1.614.0 have a problem related to password hash
synchronization. If you don't intend to use password hash synchronization in conjunction with Pass-through
Authentication, read the Azure AD Connect release notes.

3. Identify an additional server (running Windows Server 2012 R2 or later) where you can run a standalone
Authentication Agent. The Authentication Agent version needs to be 1.5.193.0 or later. This additional server
is needed to ensure the high availability of requests to sign in. Add the server to the same Active Directory
forest as the users whose passwords you need to validate.
4. If there is a firewall between your servers and Azure AD, configure the following items:
Ensure that Authentication Agents can make outbound requests to Azure AD over the following
ports:

PORT NUMBER HOW IT'S USED

80 Downloads the certificate revocation lists (CRLs) while


validating the SSL certificate

443 Handles all outbound communication with the service

If your firewall enforces rules according to the originating users, open these ports for traffic from
Windows services that run as a network service.
If your firewall or proxy allows DNS whitelisting, whitelist connections to *.msappproxy.net and
*.servicebus.windows.net. If not, allow access to the Azure datacenter IP ranges, which are updated
weekly.
Your Authentication Agents need access to login.windows.net and login.microsoftonline.com for
initial registration. Open your firewall for those URLs as well.
For certificate validation, unblock the following URLs: mscrl.microsoft.com:80, crl.microsoft.com:80,
ocsp.msocsp.com:80, and www.microsoft.com:80. These URLs are used for certificate validation with
other Microsoft products. You might already have these URLs unblocked.

Step 2: Enable Exchange ActiveSync support (optional)


Follow these instructions to enable Exchange ActiveSync support:
1. Use Exchange PowerShell to run the following command:

Get-OrganizationConfig | fl per*

2. Check the value of the PerTenantSwitchToESTSEnabled setting. If the value is true, your tenant is properly
configured. This is generally the case for most customers. If the value is false, run the following command:

Set-OrganizationConfig -PerTenantSwitchToESTSEnabled:$true

3. Verify that the value of the PerTenantSwitchToESTSEnabled setting is now set to true. Wait an hour before
moving on to the next step.
If you face any problems during this step, check the troubleshooting guide.

Step 3: Enable the feature


Enable Pass-through Authentication through Azure AD Connect.

IMPORTANT
You can enable Pass-through Authentication on the Azure AD Connect primary or staging server. You should enable it from
the primary server.

If you're installing Azure AD Connect for the first time, choose the custom installation path. At the User sign-in
page, choose Pass-through Authentication as the Sign On method. On successful completion, a Pass-through
Authentication Agent is installed on the same server as Azure AD Connect. In addition, the Pass-through
Authentication feature is enabled on your tenant.
If you have already installed Azure AD Connect by using the express installation or the custom installation path,
select the Change user sign-in task on Azure AD Connect, and then select Next. Then select Pass-through
Authentication as the sign-in method. On successful completion, a Pass-through Authentication Agent is installed
on the same server as Azure AD Connect and the feature is enabled on your tenant.
IMPORTANT
Pass-through Authentication is a tenant-level feature. Turning it on affects the sign-in for users across all the managed
domains in your tenant. If you're switching from Active Directory Federation Services (AD FS) to Pass-through
Authentication, you should wait at least 12 hours before shutting down your AD FS infrastructure. This wait time is to ensure
that users can keep signing in to Exchange ActiveSync during the transition.

Step 4: Test the feature


Follow these instructions to verify that you have enabled Pass-through Authentication correctly:
1. Sign in to the Azure Active Directory admin center with the global administrator credentials for your tenant.
2. Select Azure Active Directory in the left pane.
3. Select Azure AD Connect.
4. Verify that the Pass-through authentication feature appears as Enabled.
5. Select Pass-through authentication. The Pass-through authentication pane lists the servers where your
Authentication Agents are installed.

At this stage, users from all the managed domains in your tenant can sign in by using Pass-through Authentication.
However, users from federated domains continue to sign in by using AD FS or another federation provider that
you have previously configured. If you convert a domain from federated to managed, all users from that domain
automatically start signing in by using Pass-through Authentication. The Pass-through Authentication feature does
not affect cloud-only users.

Step 5: Ensure high availability


If you plan to deploy Pass-through Authentication in a production environment, you should install atleast one
more standalone Authentication Agent. Install these Authentication Agent(s) on server(s) other than the one
running Azure AD Connect. This setup provides you with high availability for user sign-in requests.
Follow these instructions to download the Authentication Agent software:
1. To download the latest version of the Authentication Agent (version 1.5.193.0 or later), sign in to the Azure
Active Directory admin center with your tenant's global administrator credentials.
2. Select Azure Active Directory in the left pane.
3. Select Azure AD Connect, select Pass-through authentication, and then select Download Agent.
4. Select the Accept terms & download button.

NOTE
You can also directly download the Authentication Agent software here. Review and accept the Authentication Agent's Terms
of Service before installing it.

There are two ways to deploy a standalone Authentication Agent:


First, you can do it interactively by just running the downloaded Authentication Agent executable and providing
your tenant's global administrator credentials when prompted.
Second, you can create and run an unattended deployment script. This is useful when you want to deploy multiple
Authentication Agents at once, or install Authentication Agents on Windows servers that don't have user interface
enabled, or that you can't access with Remote Desktop. Here are the instructions on how to use this approach:
1. Run the following command to install an Authentication Agent:
AADConnectAuthAgentSetup.exe REGISTERCONNECTOR="false" /q .
2. You can register the Authentication Agent with our service using Windows PowerShell. Create a PowerShell
Credentials object $cred that contains a global administrator username and password for your tenant. Run
the following command, replacing <username> and <password>:

$User = "<username>"
$PlainPassword = '<password>'
$SecurePassword = $PlainPassword | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object –TypeName System.Management.Automation.PSCredential –ArgumentList $User,
$SecurePassword

3. Go to C:\Program Files\Microsoft Azure AD Connect Authentication Agent and run the following
script using the $cred object that you created:

RegisterConnector.ps1 -modulePath "C:\Program Files\Microsoft Azure AD Connect Authentication


Agent\Modules\" -moduleName "AppProxyPSModule" -Authenticationmode Credentials -Usercredentials $cred -
Feature PassthroughAuthentication

Next steps
Smart Lockout: Learn how to configure the Smart Lockout capability on your tenant to protect user accounts.
Current limitations: Learn which scenarios are supported with the Pass-through Authentication and which ones
are not.
Technical deep dive: Understand how the Pass-through Authentication feature works.
Frequently asked questions: Find answers to frequently asked questions.
Troubleshoot: Learn how to resolve common problems with the Pass-through Authentication feature.
Security deep dive: Get technical information on the Pass-through Authentication feature.
Azure AD Seamless SSO: Learn more about this complementary feature.
UserVoice: Use the Azure Active Directory Forum to file new feature requests.
Azure Active Directory Pass-through Authentication:
Current limitations
3/13/2018 • 2 min to read • Edit Online

IMPORTANT
Azure Active Directory (Azure AD) Pass-through Authentication is a free feature, and you don't need any paid editions of
Azure AD to use it. Pass-through Authentication is only available in the world-wide instance of Azure AD, and not on the
Microsoft Azure Germany cloud or the Microsoft Azure Government cloud.

Supported scenarios
The following scenarios are fully supported:
User sign-ins to all web browser-based applications.
User sign-ins to Office applications that support modern authentication: Office 2016, and Office 2013 with
modern authentication.
User sign-ins to Outlook clients using legacy protocols such as Exchange ActiveSync, SMTP, POP and IMAP.
User sign-ins to Skype for Business that support modern authentication, including online and hybrid
topologies. Learn more about supported topologies here.
Azure AD domain joins for Windows 10 devices.
App passwords for Multi-Factor Authentication.

Unsupported scenarios
The following scenarios are not supported:
User sign-ins to legacy Office client applications, excluding Outlook (see Supported scenarios above): Office
2010, and Office 2013 without modern authentication. Organizations are encouraged to switch to modern
authentication, if possible. Modern authentication allows for Pass-through Authentication support. It also helps
you secure your user accounts by using conditional access features, such as Azure Multi-Factor Authentication.
Access to calendar sharing and free/busy information in Exchange hybrid environments on Office 2010 only.
User sign-ins to Skype for Business client applications without modern authentication.
User sign-ins to PowerShell version 1.0. We recommended that you use PowerShell version 2.0.
Detection of users with leaked credentials.
Azure AD Domain Services needs Password Hash Synchronization to be enabled on the tenant. Therefore
tenants that use Pass-through Authentication only don't work for scenarios that need Azure AD Domain
Services.
Pass-through Authentication is not integrated with Azure AD Connect Health.
The Apple Device Enrollment Program (Apple DEP) using the iOS Setup Assistant does not support modern
authentication. This will fail to enroll Apple DEP devices into Intune for managed domains using Pass-through
Authentication. Consider using the Company Portal app as an alternative.
IMPORTANT
As a workaround for unsupported scenarios only, enable Password Hash Synchronization on the Optional features page in
the Azure AD Connect wizard.

NOTE
Enabling password hash synchronization gives you the option to failover authentication if your on-premises infrastructure is
disrupted. This failover from Pass-through Authentication to Active Directory password hash synchronization is not
automatic. You'll need to switch the sign-in method manually using Azure AD Connect. If the server running Azure AD
Connect goes down, you'll require help from Microsoft Support to turn off Pass-through Authentication.

Next steps
Quick start: Get up and running with Azure AD Pass-through Authentication.
Smart Lockout: Learn how to configure the Smart Lockout capability on your tenant to protect user accounts.
Technical deep dive: Understand how the Pass-through Authentication feature works.
Frequently asked questions: Find answers to frequently asked questions about the Pass-through Authentication
feature.
Troubleshoot: Learn how to resolve common problems with the Pass-through Authentication feature.
Security deep dive: Get deep technical information on the Pass-through Authentication feature.
Azure AD Seamless SSO: Learn more about this complementary feature.
UserVoice: Use the Azure Active Directory Forum to file new feature requests.
Azure Active Directory Pass-through Authentication:
Technical deep dive
1/25/2018 • 2 min to read • Edit Online

This article is an overview of how Azure Active directory (Azure AD) Pass-through Authentication works. For deep
technical and security information, see the Security deep dive article.

How does Azure Active Directory Pass-through Authentication work?


When a user tries to sign in to an application secured by Azure AD, and if Pass-through Authentication is enabled
on the tenant, the following steps occur:
1. The user tries to access an application, for example, Outlook Web App.
2. If the user is not already signed in, the user is redirected to the Azure AD User Sign-in page.
3. The user enters their username and password into the Azure AD sign in page, and then selects the Sign in
button.
4. Azure AD, on receiving the request to sign in, places the username and password (encrypted by using a public
key) in a queue.
5. An on-premises Authentication Agent retrieves the username and encrypted password from the queue. Note
that the Agent doesn't frequently poll for requests from the queue, but retrieves requests over a pre-
established persistent connection.
6. The agent decrypts the password by using its private key.
7. The agent validates the username and password against Active Directory by using standard Windows APIs,
which is a similar mechanism to what Active Directory Federation Services (AD FS) uses. The username can be
either the on-premises default username, usually userPrincipalName , or another attribute configured in Azure
AD Connect (known as Alternate ID ).
8. The on-premises Active Directory domain controller (DC) evaluates the request and returns the appropriate
response (success, failure, password expired, or user locked out) to the agent.
9. The Authentication Agent, in turn, returns this response back to Azure AD.
10. Azure AD evaluates the response and responds to the user as appropriate. For example, Azure AD either signs
the user in immediately or requests for Azure Multi-Factor Authentication.
11. If the user sign-in is successful, the user can access the application.
The following diagram illustrates all the components and the steps involved:
Next steps
Current limitations: Learn which scenarios are supported and which ones are not.
Quick Start: Get up and running on Azure AD Pass-through Authentication.
Smart Lockout: Configure the Smart Lockout capability on your tenant to protect user accounts.
Frequently Asked Questions: Find answers to frequently asked questions.
Troubleshoot: Learn how to resolve common problems with the Pass-through Authentication feature.
Security Deep Dive: Get deep technical information on the Pass-through Authentication feature.
Azure AD Seamless SSO: Learn more about this complementary feature.
UserVoice: Use the Azure Active Directory Forum to file new feature requests.
Azure Active Directory Pass-through Authentication:
Upgrade preview Authentication Agents
1/17/2018 • 4 min to read • Edit Online

Overview
This article is for customers using Azure AD Pass-through Authentication through preview. We recently upgraded
(and rebranded) the Authentication Agent software. You need to manually upgrade preview Authentication Agents
installed on your on-premises servers. This manual upgrade is a one-time action only. All future updates to
Authentication Agents are automatic. The reasons to upgrade are as follows:
The preview versions of Authentication Agents will not receive any further security or bug fixes.
The preview versions of Authentication Agents can't be installed on additional servers, for high availability.

Check versions of your Authentication Agents


Step 1: Check where your Authentication Agents are installed
Follow these steps to check where your Authentication Agents are installed:
1. Sign in to the Azure Active Directory admin center with the Global Administrator credentials for your tenant.
2. Select Azure Active Directory on the left-hand navigation.
3. Select Azure AD Connect.
4. Select Pass-through Authentication. This blade lists the servers where your Authentication Agents are
installed.

Step 2: Check the versions of your Authentication Agents


To check the versions of your Authentication Agents, on each server identified in the preceding step, follow these
instructions:
1. Go to Control Panel -> Programs -> Programs and Features on the on-premises server.
2. If there is an entry for "Microsoft Azure AD Connect Authentication Agent", you don't need to take any
action on this server.
3. If there is an entry for "Microsoft Azure AD Application Proxy Connector", versions 1.5.132.0 or earlier, you
need to manually upgrade on this server.
Best practices to follow before starting the upgrade
Before upgrading, ensure that you have the following items in place:
1. Create cloud-only Global Administrator account: Don’t upgrade without having a cloud-only Global
Administrator account to use in emergency situations where your Pass-through Authentication Agents are not
working properly. Learn about adding a cloud-only Global Administrator account. Doing this step is critical and
ensures that you don't get locked out of your tenant.
2. Ensure high availability: If not completed previously, install a second standalone Authentication Agent to
provide high availability for sign-in requests, using these instructions.

Upgrading the Authentication Agent on your Azure AD Connect server


You need upgrade Azure AD Connect before upgrading the Authentication Agent on the same server. Follow these
steps on both your primary and staging Azure AD Connect servers:
1. Upgrade Azure AD Connect: Follow this article and upgrade to the latest Azure AD Connect version.
2. Uninstall the preview version of the Authentication Agent: Download this PowerShell script and run it as
an Administrator on the server.
3. Download the latest version of the Authentication Agent (versions 1.5.193.0 or later): Sign in to the
Azure Active Directory admin center with your tenant's Global Administrator credentials. Select Azure Active
Directory -> Azure AD Connect -> Pass-through Authentication -> Download agent. Accept the terms of
service and download the latest version of the Authentication Agent. You can also download the Authentication
Agent from here.
4. Install the latest version of the Authentication Agent: Run the executable downloaded in Step 3. Provide
your tenant's Global Administrator credentials when prompted.
5. Verify that the latest version has been installed: As shown before, go to Control Panel -> Programs ->
Programs and Features and verify that there is an entry for "Microsoft Azure AD Connect Authentication
Agent".

NOTE
If you check the Pass-through Authentication blade on the Azure Active Directory admin center after completing the
preceding steps, you'll see two Authentication Agent entries per server - one entry showing the Authentication Agent as
Active and the other as Inactive. This is expected. The Inactive entry is automatically dropped after a few days.

Upgrading the Authentication Agent on other servers


Follow these steps to upgrade Authentication Agents on other servers (where Azure AD Connect is not installed):
1. Uninstall the preview version of the Authentication Agent: Download this PowerShell script and run it as
an Administrator on the server.
2. Download the latest version of the Authentication Agent (versions 1.5.193.0 or later): Sign in to the
Azure Active Directory admin center with your tenant's Global Administrator credentials. Select Azure Active
Directory -> Azure AD Connect -> Pass-through Authentication -> Download agent. Accept the terms of
service and download the latest version.
3. Install the latest version of the Authentication Agent: Run the executable downloaded in Step 2. Provide
your tenant's Global Administrator credentials when prompted.
4. Verify that the latest version has been installed: As shown before, go to Control Panel -> Programs ->
Programs and Features and verify that there is an entry called Microsoft Azure AD Connect
Authentication Agent.

NOTE
If you check the Pass-through Authentication blade on the Azure Active Directory admin center after completing the
preceding steps, you'll see two Authentication Agent entries per server - one entry showing the Authentication Agent as
Active and the other as Inactive. This is expected. The Inactive entry is automatically dropped after a few days.

Next steps
Troubleshoot - Learn how to resolve common issues with the feature.
Azure Active Directory Pass-through Authentication:
Smart Lockout
3/7/2018 • 4 min to read • Edit Online

Overview
Azure Active Directory (Azure AD) protects against brute-force password attacks and prevents genuine users from
being locked out of their Office 365 and SaaS applications. This capability, called Smart Lockout, is supported
when you use Pass-through Authentication as your sign-in method. Smart Lockout is enabled by default for all
tenants, not just tenants using Pass-through Authentication, and it continuously protects your user accounts.
Smart Lockout keeps track of failed sign-in attempts. After a certain lockout threshold, it starts a lockout duration.
Smart Lockout rejects any attempts to sign in from the attacker during the lockout duration. If the attack
continues, subsequent failed sign-in attempts after the lockout duration ends result in longer lockout durations.

NOTE
The default lockout threshold is 10 failed attempts. The default lockout duration is 60 seconds.

Smart Lockout also distinguishes between sign-ins from genuine users and sign-ins from attackers. In most cases,
it locks out only the attackers. This functionality prevents attackers from maliciously locking out genuine users.
Smart Lockout uses past sign-in behavior, the users’ devices and browsers, and other signals to distinguish
between genuine users and attackers. The algorithms are constantly improved.
Pass-through Authentication forwards password validation requests to on-premises Active Directory, so you need
to prevent attackers from locking out your users’ Active Directory accounts. Active Directory has its own account
lockout policies, specifically, Account lockout threshold and Reset account lockout counter after policies.
Configure the Azure AD lockout threshold and lockout duration values appropriately to filter out attacks in the
cloud before they reach on-premises Active Directory.

NOTE
The Smart Lockout feature is free and is on by default for all customers. However, modifying Azure AD’s Lockout
Threshold and Lockout Duration values using Graph API needs your tenant to be activated for Azure AD Premium P2.

To ensure that your users’ on-premises Active Directory accounts are well protected, you need to ensure that:
The Azure AD lockout threshold is less than the Active Directory account lockout threshold. Set the values so
that the Active Directory account lockout threshold is at least two or three times longer than the Azure AD
lockout threshold.
The Azure AD lockout duration (represented in seconds) is longer than the Active Directory reset account
lockout counter after duration (represented in minutes).

IMPORTANT
Currently an administrator can't unlock the users' cloud accounts if they have been locked out by the Smart Lockout
capability. The administrator must wait for the lockout duration to expire.
Verify your Active Directory account lockout policies
Use the following instructions to verify your Active Directory account lockout policies:
1. Open the Group Policy Management tool.
2. Edit the group policy that's applied to all users, for example, the Default Domain Policy.
3. Browse to Computer Configuration > Policies > Windows Settings > Security Settings > Account
Policies > Account Lockout Policy.
4. Verify your Account lockout threshold and Reset account lockout counter after values.

Use the Graph API to manage your tenant’s Smart Lockout values
(requires a Premium license)
IMPORTANT
Modifying the Azure AD lockout threshold and lockout duration values by using Graph API is an Azure AD Premium P2
feature. It also needs you to be a global administrator on your tenant.

You can use Graph Explorer to read, set, and update the Azure AD Smart Lockout values. You can also do these
operations programmatically.
View Smart Lockout values
Follow these steps to view your tenant’s Smart Lockout values:
1. Sign in to Graph Explorer as a global administrator of your tenant. If you're prompted, grant access for the
requested permissions.
2. Select Modify permissions, and then select the Directory.ReadWrite.All permission.
3. Configure the Graph API request as follows: Set the version to BETA, the request type to GET, and the URL to
https://graph.microsoft.com/beta/<your-tenant-domain>/settings .
4. Select Run Query to see your tenant's Smart Lockout values. If you haven't set your tenant's values before,
you see an empty set.
Set Smart Lockout values
Follow these steps to set your tenant’s Smart Lockout values (required for the first time only):
1. Sign in to Graph Explorer as a global administrator of your tenant. If you're prompted, grant access for the
requested permissions.
2. Select Modify permissions, and then select the Directory.ReadWrite.All permission.
3. Configure the Graph API request as follows: Set the version to BETA, the request type to POST, and the URL to
https://graph.microsoft.com/beta/<your-tenant-domain>/settings .
4. Copy and paste the following JSON request into the Request Body field.
5. Select Run Query to set your tenant's Smart Lockout values.

{
"templateId": "5cf42378-d67d-4f36-ba46-e8b86229381d",
"values": [
{
"name": "LockoutDurationInSeconds",
"value": "300"
},
{
"name": "LockoutThreshold",
"value": "5"
},
{
"name" : "BannedPasswordList",
"value": ""
},
{
"name" : "EnableBannedPasswordCheck",
"value": "false"
}
]
}

NOTE
If you don't use them, you can leave the BannedPasswordList and EnableBannedPasswordCheck values as empty ("")
and false respectively.

Verify that you have set your tenant's Smart Lockout values correctly by using the steps in View Smart Lockout
values.
Update Smart Lockout values
Follow these steps to update your tenant’s Smart Lockout values (if you set them before):
1. Sign in to Graph Explorer as a global administrator of your tenant. If you're prompted, grant access for the
requested permissions.
2. Select Modify permissions, and then select the Directory.ReadWrite.All permission.
3. Follow these steps to view your tenant's Smart Lockout values. Copy the id value (a GUID) of the item with
displayName as PasswordRuleSettings.
4. Configure the Graph API request as follows: Set the version to BETA, the request type to PATCH, and the URL
to https://graph.microsoft.com/beta/<your-tenant-domain>/settings/<id> . Use the GUID from step 3 for <id> .
5. Copy and paste the following JSON request into the Request Body field. Change the Smart Lockout values as
appropriate.
6. Select Run Query to update your tenant's Smart Lockout values.
{
"values": [
{
"name": "LockoutDurationInSeconds",
"value": "30"
},
{
"name": "LockoutThreshold",
"value": "4"
},
{
"name" : "BannedPasswordList",
"value": ""
},
{
"name" : "EnableBannedPasswordCheck",
"value": "false"
}
]
}

Verify that you have updated your tenant's Smart Lockout values correctly by using the steps in View Smart
Lockout values.

Next steps
UserVoice: Use the Azure Active Directory Forum to file new feature requests.
Azure Active Directory Pass-through Authentication:
Frequently asked questions
1/5/2018 • 7 min to read • Edit Online

This article addresses frequently asked questions about Azure Active Directory (Azure AD) Pass-through
Authentication. Keep checking back for updated content.

Which of the methods to sign in to Azure AD, Pass-through


Authentication, password hash synchronization, and Active Directory
Federation Services (AD FS), should I choose?
It depends on your on-premises environment and organizational requirements. Review the Azure AD Connect user
sign-in options article for a comparison of the various Azure AD sign-in methods.

Is Pass-through Authentication a free feature?


Pass-through Authentication is a free feature. You don't need any paid editions of Azure AD to use it.

Is Pass-through Authentication available in the Microsoft Azure


Germany cloud and the Microsoft Azure Government cloud?
No. Pass-through Authentication is only available in the worldwide instance of Azure AD.

Does conditional access work with Pass-through Authentication?


Yes. All conditional access capabilities, including Azure Multi-Factor Authentication, work with Pass-through
Authentication.

Does Pass-through Authentication support "Alternate ID" as the


username, instead of "userPrincipalName"?
Yes. Pass-through Authentication supports Alternate ID as the username when configured in Azure AD Connect.
For more information, see Custom installation of Azure AD Connect. Not all Office 365 applications support
Alternate ID . Refer to the specific application's documentation support statement.

Does password hash synchronization act as a fallback to Pass-through


Authentication?
No. Pass-through Authentication does not automatically failover to password hash synchronization. It only acts as
a fallback for scenarios that Pass-through Authentication doesn't support today. To avoid user sign-in failures, you
should configure Pass-through Authentication for high availability.

Can I install an Azure AD Application Proxy connector on the same


server as a Pass-through Authentication Agent?
Yes. The rebranded versions of the Pass-through Authentication Agent, version 1.5.193.0 or later, support this
configuration.
What versions of Azure AD Connect and Pass-through Authentication
Agent do you need?
For this feature to work, you need version 1.1.486.0 or later for Azure AD Connect and 1.5.58.0 or later for the
Pass-through Authentication Agent. Install all the software on servers with Windows Server 2012 R2 or later.

What happens if my user's password has expired and they try to sign in
by using Pass-through Authentication?
If you have configured password writeback for a specific user, and if the user signs in by using Pass-through
Authentication, they can change or reset their passwords. The passwords are written back to on-premises Active
Directory as expected.
If you have not configured password writeback for a specific user or if the user doesn't have a valid Azure AD
license assigned, the user can't update their password in the cloud. They can't update their password, even if their
password has expired. The user instead sees this message: "Your organization doesn't allow you to update your
password on this site. Update it according to the method recommended by your organization, or ask your admin if
you need help." The user or the administrator must reset their password in on-premises Active Directory.

How does Pass-through Authentication protect you against brute-


force password attacks?
Read Azure Active Directory Pass-through Authentication: Smart Lockout for more information.

What do Pass-through Authentication Agents communicate over ports


80 and 443?
The Authentication Agents make HTTPS requests over port 443 for all feature operations.
The Authentication Agents make HTTP requests over port 80 to download the SSL certificate revocation lists
(CRLs).

NOTE
Recent updates reduced the number of ports that the feature requires. If you have older versions of Azure AD
Connect or the Authentication Agent, keep these ports open as well: 5671, 8080, 9090, 9091, 9350, 9352, and
10100-10120.

Can the Pass-through Authentication Agents communicate over an


outbound web proxy server?
Yes. If Web Proxy Auto-Discovery (WPAD) is enabled in your on-premises environment, Authentication Agents
automatically attempt to locate and use a web proxy server on the network.

Can I install two or more Pass-through Authentication Agents on the


same server?
No, you can only install one Pass-through Authentication Agent on a single server. If you want to configure Pass-
through Authentication for high availability, follow the instructions in Azure Active Directory Pass-through
Authentication: Quick start.

How do I remove a Pass-through Authentication Agent?


As long as a Pass-through Authentication Agent is running, it remains active and continually handles user sign-in
requests. If you want to uninstall an Authentication Agent, go to Control Panel -> Programs -> Programs and
Features and uninstall both the Microsoft Azure AD Connect Authentication Agent and the Microsoft Azure
AD Connect Agent Updater programs.
If you check the Pass-through Authentication blade on the Azure Active Directory admin center after completing
the preceding step, you'll see the Authentication Agent showing as Inactive. This is expected. The Authentication
Agent is automatically dropped from the list after a few days.

I already use AD FS to sign in to Azure AD. How do I switch it to Pass-


through Authentication?
If you have configured AD FS as your method to sign in through the Azure AD Connect wizard, change the method
that the user uses to sign in to Pass-through Authentication. This change enables Pass-through Authentication on
the tenant and converts all your federated domains into managed domains. Pass-through Authentication handles
all subsequent requests to sign in to your tenant. Currently, there is no supported way within Azure AD Connect to
use a combination of AD FS and Pass-through Authentication across different domains.
If AD FS was configured as the method to sign in outside the Azure AD Connect wizard, change the user sign-in
method to Pass-through Authentication. You can make this change from the Do not configure option. This
change enables Pass-through Authentication on the tenant, but all your federated domains will continue to use AD
FS for sign-in. Use PowerShell to manually convert some or all of these federated domains to managed domains.
After you make that change, only Pass-through Authentication handles all requests to sign in to the managed
domains.

IMPORTANT
Pass-through Authentication doesn't handle sign in for cloud-only Azure AD users.

Can I use Pass-through Authentication in a multi-forest Active


Directory environment?
Yes. Multi-forest environments are supported if there are forest trusts between your Active Directory forests and if
name suffix routing is correctly configured.

How many Pass-through Authentication Agents do I need to install?


Installing multiple Pass-through Authentication Agents ensures high availability. But, it does not provide
deterministic load balancing between the Authentication Agents.
Consider the peak and average load of sign-in requests that you expect to see on your tenant. As a benchmark, a
single Authentication Agent can handle 300 to 400 authentications per second on a standard 4-core CPU, 16-GB
RAM server.
To estimate network traffic, use the following sizing guidance:
Each request has a payload size of (0.5K + 1K * num_of_agents) bytes; i.e., data from Azure AD to the
Authentication Agent. Here, "num_of_agents" indicates the number of Authentication Agents registered on your
tenant.
Each response has a payload size of 1K bytes; i.e., data from the Authentication Agent to Azure AD.
For most customers, two or three Authentication Agents in total are sufficient for high availability and capacity.
You should install Authentication Agents close to your domain controllers to improve sign-in latency.
NOTE
There is a system limit of 12 Authentication Agents per tenant.

Can I install the first Pass-through Authentication Agent on a server


other than the one that runs Azure AD Connect?
No, this scenario is not supported.

How can I disable Pass-through Authentication?


Rerun the Azure AD Connect wizard and change the user sign-in method from Pass-through Authentication to
another method. This change disables Pass-through Authentication on the tenant and uninstalls the Authentication
Agent from the server. You must manually uninstall the Authentication Agents from the other servers.

What happens when I uninstall a Pass-through Authentication Agent?


If you uninstall a Pass-through Authentication Agent from a server, it causes the server to stop accepting sign-in
requests. To avoid breaking the user sign-in capability on your tenant, ensure that you have another
Authentication Agent running before you uninstall a Pass-through Authentication Agent.

Next steps
Current limitations: Learn which scenarios are supported and which ones are not.
Quick start: Get up and running on Azure AD Pass-through Authentication.
Smart Lockout: Learn how to configure the Smart Lockout capability on your tenant to protect user accounts.
Technical deep dive: Understand how the Pass-through Authentication feature works.
Troubleshoot: Learn how to resolve common problems with the Pass-through Authentication feature.
Security deep dive: Get deep technical information on the Pass-through Authentication feature.
Azure AD Seamless SSO: Learn more about this complementary feature.
UserVoice: Use the Azure Active Directory Forum to file new feature requests.
Troubleshoot Azure Active Directory Pass-through
Authentication
1/5/2018 • 6 min to read • Edit Online

This article helps you find troubleshooting information about common issues regarding Azure AD Pass-through
Authentication.

IMPORTANT
If you are facing user sign-in issues with Pass-through Authentication, don't disable the feature or uninstall Pass-through
Authentication Agents without having a cloud-only Global Administrator account to fall back on. Learn about adding a
cloud-only Global Administrator account. Doing this step is critical and ensures that you don't get locked out of your
tenant.

General issues
Check status of the feature and Authentication Agents
Ensure that the Pass-through Authentication feature is still Enabled on your tenant and the status of
Authentication Agents shows Active, and not Inactive. You can check status by going to the Azure AD Connect
blade on the Azure Active Directory admin center.
User-facing sign-in error messages
If the user is unable to sign into using Pass-through Authentication, they may see one of the following user-facing
errors on the Azure AD sign-in screen:

ERROR DESCRIPTION RESOLUTION

AADSTS80001 Unable to connect to Active Directory Ensure that agent servers are members
of the same AD forest as the users
whose passwords need to be validated
and they are able to connect to Active
Directory.

AADSTS8002 A timeout occurred connecting to Check to ensure that Active Directory is


Active Directory available and is responding to requests
from the agents.

AADSTS80004 The username passed to the agent was Ensure the user is attempting to sign in
not valid with the right username.

AADSTS80005 Validation encountered unpredictable A transient error. Retry the request. If it


WebException continues to fail, contact Microsoft
support.

AADSTS80007 An error occurred communicating with Check the agent logs for more
Active Directory information and verify that Active
Directory is operating as expected.

Sign-in failure reasons on the Azure Active Directory admin center (needs Premium license )
If your tenant has an Azure AD Premium license associated with it, you can also look at the sign-in activity report
on the Azure Active Directory admin center.
Navigate to Azure Active Directory -> Sign-ins on the Azure Active Directory admin center and click a specific
user's sign-in activity. Look for the SIGN-IN ERROR CODE field. Map the value of that field to a failure reason and
resolution using the following table:

SIGN-IN ERROR CODE SIGN-IN FAILURE REASON RESOLUTION

50144 User's Active Directory password has Reset the user's password in your on-
expired. premises Active Directory.

80001 No Authentication Agent available. Install and register an Authentication


Agent.

80002 Authentication Agent's password Check if your Active Directory is


validation request timed out. reachable from the Authentication
Agent.

80003 Invalid response received by If the problem is consistently


Authentication Agent. reproducible across multiple users,
check your Active Directory
configuration.

80004 Incorrect User Principal Name (UPN) Ask the user to sign in with the correct
used in sign-in request. username.

80005 Authentication Agent: Error occurred. Transient error. Try again later.

80007 Authentication Agent unable to Check if your Active Directory is


connect to Active Directory. reachable from the Authentication
Agent.

80010 Authentication Agent unable to If the problem is consistently


decrypt password. reproducible, install and register a new
Authentication Agent. And uninstall the
current one.
SIGN-IN ERROR CODE SIGN-IN FAILURE REASON RESOLUTION

80011 Authentication Agent unable to If the problem is consistently


retrieve decryption key. reproducible, install and register a new
Authentication Agent. And uninstall the
current one.

Authentication Agent installation issues


An unexpected error occurred
Collect agent logs from the server and contact Microsoft Support with your issue.

Authentication Agent registration issues


Registration of the Authentication Agent failed due to blocked ports
Ensure that the server on which the Authentication Agent has been installed can communicate with our service
URLs and ports listed here.
Registration of the Authentication Agent failed due to token or account authorization errors
Ensure that you use a cloud-only Global Administrator account for all Azure AD Connect or standalone
Authentication Agent installation and registration operations. There is a known issue with MFA-enabled Global
Administrator accounts; turn off MFA temporarily (only to complete the operations) as a workaround.
An unexpected error occurred
Collect agent logs from the server and contact Microsoft Support with your issue.

Authentication Agent uninstallation issues


Warning message when uninstalling Azure AD Connect
If you have Pass-through Authentication enabled on your tenant and you try to uninstall Azure AD Connect, it
shows you the following warning message: "Users will not be able to sign-in to Azure AD unless you have other
Pass-through Authentication agents installed on other servers."
Ensure that your setup is high available before you uninstall Azure AD Connect to avoid breaking user sign-in.

Issues with enabling the feature


Enabling the feature failed because there were no Authentication Agents available
You need to have at least one active Authentication Agent to enable Pass-through Authentication on your tenant.
You can install an Authentication Agent by either installing Azure AD Connect or a standalone Authentication
Agent.
Enabling the feature failed due to blocked ports
Ensure that the server on which Azure AD Connect is installed can communicate with our service URLs and ports
listed here.
Enabling the feature failed due to token or account authorization errors
Ensure that you use a cloud-only Global Administrator account when enabling the feature. There is a known issue
with multi-factor authentication (MFA)-enabled Global Administrator accounts; turn off MFA temporarily (only to
complete the operation) as a workaround.

Exchange ActiveSync configuration issues


These are the common issues when you configure Exchange ActiveSync support for Pass-through Authentication.
Exchange PowerShell issue
If you see the "A parameter cannot be found that matches parameter name
'PerTenantSwitchToESTSEnabled'." error when you run the Set-OrganizationConfig Exchange PowerShell
command, contact Microsoft Support.
Exchange ActiveSync not working
The configuration takes some time to take effect - the time period depends on your environment. If the situation
persists for a long time, contact Microsoft Support.

Collecting Pass-through Authentication Agent logs


Depending on the type of issue you may have, you need to look in different places for Pass-through
Authentication Agent logs.
Azure AD Connect logs
For errors related to installation, check the Azure AD Connect logs at %ProgramData%\AADConnect\trace-
*.log.
Authentication Agent event logs
For errors related to the Authentication Agent, open up the Event Viewer application on the server and check
under Application and Service Logs\Microsoft\AzureAdConnect\AuthenticationAgent\Admin.
For detailed analytics, enable the "Session" log. Don't run the Authentication Agent with this log enabled during
normal operations; use only for troubleshooting. The log contents are only visible after the log is disabled again.
Detailed trace logs
To troubleshoot user sign-in failures, look for trace logs at %ProgramData%\Microsoft\Azure AD Connect
Authentication Agent\Trace\. These logs include reasons why a specific user sign-in failed using the Pass-
through Authentication feature. These errors are also mapped to the sign-in failure reasons shown in the
preceding table. Following is an example log entry:

AzureADConnectAuthenticationAgentService.exe Error: 0 : Passthrough Authentication request failed.


RequestId: 'df63f4a4-68b9-44ae-8d81-6ad2d844d84e'. Reason: '1328'.
ThreadId=5
DateTime=xxxx-xx-xxTxx:xx:xx.xxxxxxZ

You can get descriptive details of the error ('1328' in the preceding example) by opening up the command
prompt and running the following command (Note: Replace '1328' with the actual error number that you see in
your logs):
Net helpmsg 1328

Domain Controller logs


If audit logging is enabled, additional information can be found in the security logs of your Domain Controllers. A
simple way to query sign-in requests sent by Pass-through Authentication Agents is as follows:
<QueryList>
<Query Id="0" Path="Security">
<Select Path="Security">*[EventData[Data[@Name='ProcessName'] and (Data='C:\Program Files\Microsoft Azure
AD Connect Authentication Agent\AzureADConnectAuthenticationAgentService.exe')]]</Select>
</Query>
</QueryList>

Performance Monitor counters


Another way to monitor Authentication Agents is to track specific Performance Monitor counters on each server
where the Authentication Agent is installed. Use the following Global counters (# PTA authentications, #PTA
failed authentications and #PTA successful authentications) and Error counters (# PTA authentication
errors):

IMPORTANT
Pass-through Authentication provides high availability using multiple Authentication Agents, and not load balancing.
Depending on your configuration, not all your Authentication Agents receive roughly equal number of requests. It is
possible that a specific Authentication Agent receives no traffic at all.
Azure Active Directory Pass-through Authentication
security deep dive
12/11/2017 • 11 min to read • Edit Online

This article provides a more detailed description of how Azure Active Directory (Azure AD) Pass-through
Authentication works. It focuses on the security aspects of the feature. This article is for security and IT
administrators, chief compliance and security officers, and other IT professionals who are responsible for IT
security and compliance at small-to-medium sized organizations or large enterprises.
The topics addressed include:
Detailed technical information about how to install and register the Authentication Agents.
Detailed technical information about the encryption of passwords during user sign-in.
The security of the channels between on-premises Authentication Agents and Azure AD.
Detailed technical information about how to keep the Authentication Agents operationally secure.
Other security-related topics.

Key security capabilities


These are the key security aspects of this feature:
It's built on a secure multi-tenanted architecture that provides isolation of sign-in requests between tenants.
On-premises passwords are never stored in the cloud in any form.
On-premises Authentication Agents that listen for, and respond to, password validation requests only make
outbound connections from within your network. There is no requirement to install these Authentication
Agents in a perimeter network (DMZ).
Only standard ports (80 and 443) are used for outbound communication from the Authentication Agents to
Azure AD. You don't need to open inbound ports on your firewall.
Port 443 is used for all authenticated outbound communication.
Port 80 is used only for downloading the Certificate Revocation Lists (CRLs) to ensure that none of the
certificates used by this feature have been revoked.
For the complete list of the network requirements, see Azure Active Directory Pass-through
Authentication: Quick start.
Passwords that users provide during sign-in are encrypted in the cloud before the on-premises Authentication
Agents accept them for validation against Active Directory.
The HTTPS channel between Azure AD and the on-premises Authentication Agent is secured by using mutual
authentication.
The feature seamlessly integrates with Azure AD cloud-protection capabilities, such as conditional access
policies (including Azure Multi-Factor Authentication), identity protection, and Smart Lockout.

Components involved
For general details about Azure AD operational, service, and data security, see the Trust Center. The following
components are involved when you use Pass-through Authentication for user sign-in:
Azure AD STS: A stateless security token service (STS) that processes sign-in requests and issues security
tokens to users' browsers, clients, or services as required.
Azure Service Bus: Provides cloud-enabled communication with enterprise messaging and relays
communication that helps you connect on-premises solutions with the cloud.
Azure AD Connect Authentication Agent: An on-premises component that listens for and responds to
password validation requests.
Azure SQL Database: Holds information about your tenant's Authentication Agents, including their metadata
and encryption keys.
Active Directory: On-premises Active Directory, where your user accounts and their passwords are stored.

Installation and registration of the Authentication Agents


Authentication Agents are installed and registered with Azure AD when you either:
Enable Pass-through Authentication through Azure AD Connect
Add more Authentication Agents to ensure the high availability of sign-in requests
Getting an Authentication Agent working involves three main phases:
1. Authentication Agent installation
2. Authentication Agent registration
3. Authentication Agent initialization
The following sections discuss these phases in detail.
Authentication Agent installation
Only global administrators can install an Authentication Agent (by using Azure AD Connect or standalone) on an
on-premises server. Installation adds two new entries to the Control Panel > Programs > Programs and
Features list:
The Authentication Agent application itself. This application runs with NetworkService privileges.
The Updater application that's used to auto-update the Authentication Agent. This application runs with
LocalSystem privileges.
Authentication Agent registration
After you install the Authentication Agent, it needs to register itself with Azure AD. Azure AD assigns each
Authentication Agent a unique, digital-identity certificate that it can use for secure communication with Azure AD.
The registration procedure also binds the Authentication Agent with your tenant. This ensures that Azure AD
knows that this specific Authentication Agent is the only one authorized to handle password validation requests
for your tenant. This procedure is repeated for each new Authentication Agent that you register.
The Authentication Agents use the following steps to register themselves with Azure AD:
1. Azure AD first requests that a global administrator sign in to Azure AD with their credentials. During sign-in,
the Authentication Agent acquires an access token that it can use on behalf of the global administrator.
2. The Authentication Agent then generates a key pair: a public key and a private key.
The key pair is generated through standard RSA 2048-bit encryption.
The private key stays on the on-premises server where the Authentication Agent resides.
3. The Authentication Agent makes a “registration” request to Azure AD over HTTPS, with the following
components included in the request:
The access token acquired in step 1.
The public key generated in step 2.
A Certificate Signing Request (CSR or Certificate Request). This request applies for a digital identity
certificate, with Azure AD as its certificate authority (CA).
4. Azure AD validates the access token in the registration request and verifies that the request came from a global
administrator.
5. Azure AD then signs and sends a digital identity certificate back to the Authentication Agent.
The root CA in Azure AD is used to sign the certificate.

NOTE
This CA is not in the Windows Trusted Root Certificate Authorities store.

The CA is used only by the Pass-through Authentication feature. The CA is used only to sign CSRs
during the Authentication Agent registration.
None of the other Azure AD services use this CA.
The certificate’s subject (Distinguished Name or DN) is set to your tenant ID. This DN is a GUID that
uniquely identifies your tenant. This DN scopes the certificate for use only with your tenant.
6. Azure AD stores the public key of the Authentication Agent in an Azure SQL database, which only Azure AD has
access to.
7. The certificate (issued in step 5) is stored on the on-premises server in the Windows certificate store
(specifically in the CERT_SYSTEM_STORE_LOCAL_MACHINE location). It is used by both the Authentication
Agent and the Updater applications.
Authentication Agent initialization
When the Authentication Agent starts, either for the first time after registration or after a server restart, it needs a
way to communicate securely with the Azure AD service and start accepting password validation requests.
Here is how Authentication Agents are initialized:
1. The Authentication Agent makes an outbound bootstrap request to Azure AD.
This request is made over port 443 and is over a mutually authenticated HTTPS channel. The request
uses the same certificate that was issued during the Authentication Agent registration.
2. Azure AD responds to the request by providing an access key to an Azure Service Bus queue that's unique to
your tenant and that's identified by your tenant ID.
3. The Authentication Agent makes a persistent outbound HTTPS connection (over port 443) to the queue.
The Authentication Agent is now ready to retrieve and handle password-validation requests.
If you have multiple Authentication Agents registered on your tenant, then the initialization procedure ensures
that each one connects to the same Service Bus queue.

Process sign-in requests


The following diagram shows how Pass-through Authentication processes user sign-in requests.

Pass-through Authentication handles a user sign-in request as follows:


1. A user tries to access an application, for example, Outlook Web App.
2. If the user is not already signed in, the application redirects the browser to the Azure AD sign-in page.
3. The Azure AD STS service responds back with the User sign-in page.
4. The user enters their username and password into the User sign-in page, and then selects the Sign-in button.
5. The username and password are submitted to Azure AD STS in an HTTPS POST request.
6. Azure AD STS retrieves public keys for all the Authentication Agents registered on your tenant from the Azure
SQL database and encrypts the password by using them.
It produces "N" encrypted password values for "N" Authentication Agents registered on your tenant.
7. Azure AD STS places the password validation request, which consists of the username and the encrypted
password values, onto the Service Bus queue specific to your tenant.
8. Because the initialized Authentication Agents are persistently connected to the Service Bus queue, one of the
available Authentication Agents retrieves the password validation request.
9. The Authentication Agent locates the encrypted password value that's specific to its public key, by using an
identifier, and decrypts it by using its private key.
10. The Authentication Agent attempts to validate the username and the password against on-premises Active
Directory by using the Win32 LogonUser API with the dwLogonType parameter set to
LOGON32_LOGON_NETWORK.
This API is the same API that is used by Active Directory Federation Services (AD FS) to sign in users in a
federated sign-in scenario.
This API relies on the standard resolution process in Windows Server to locate the domain controller.
11. The Authentication Agent receives the result from Active Directory, such as success, username or password
incorrect, or password expired.
12. The Authentication Agent forwards the result back to Azure AD STS over an outbound mutually authenticated
HTTPS channel over port 443. Mutual authentication uses the certificate previously issued to the Authentication
Agent during registration.
13. Azure AD STS verifies that this result correlates with the specific sign-in request on your tenant.
14. Azure AD STS continues with the sign-in procedure as configured. For example, if the password validation was
successful, the user might be challenged for Multi-Factor Authentication or redirected back to the application.

Operational security of the Authentication Agents


To ensure that Pass-through Authentication remains operationally secure, Azure AD periodically renews
Authentication Agents' certificates. Azure AD triggers the renewals. The renewals are not governed by the
Authentication Agents themselves.

To renew an Authentication Agent's trust with Azure AD:


1. The Authentication Agent periodically pings Azure AD every few hours to check if it's time to renew its
certificate.
This check is done over a mutually authenticated HTTPS channel and uses the same certificate that was
issued during registration.
2. If the service indicates that it's time to renew, the Authentication Agent generates a new key pair: a public key
and a private key.
These keys are generated through standard RSA 2048-bit encryption.
The private key never leaves the on-premises server.
3. The Authentication Agent then makes a “certificate renewal” request to Azure AD over HTTPS, with the
following components included in the request:
The existing certificate that's retrieved from the CERT_SYSTEM_STORE_LOCAL_MACHINE location on
the Windows certificate store. There is no global administrator involved in this procedure, so there is no
access token needed on behalf of the global administrator.
The public key generated in step 2.
A Certificate Signing Request (CSR or Certificate Request). This request applies for a new digital identity
certificate, with Azure AD as its certificate authority.
4. Azure AD validates the existing certificate in the certificate renewal request. Then it verifies that the request
came from an Authentication Agent registered on your tenant.
5. If the existing certificate is still valid, Azure AD then signs a new digital identity certificate, and issues the new
certificate back to the Authentication Agent.
6. If the existing certificate has expired, Azure AD deletes the Authentication Agent from your tenant’s list of
registered Authentication Agents. Then a global administrator needs to manually install and register a new
Authentication Agent.
Use the Azure AD root CA to sign the certificate.
Set the certificate’s subject (Distinguished Name or DN) to your tenant ID, a GUID that uniquely
identifies your tenant. The DN scopes the certificate to your tenant only.
7. Azure AD stores the new public key of the Authentication Agent in an Azure SQL database that only it has
access to. It also invalidates the old public key associated with the Authentication Agent.
8. The new certificate (issued in step 5) is then stored on the server in the Windows certificate store
(specifically in the CERT_SYSTEM_STORE_CURRENT_USER location).
Because the trust renewal procedure happens non-interactively (without the presence of the global
administrator), the Authentication Agent no longer has access to update the existing certificate in the
CERT_SYSTEM_STORE_LOCAL_MACHINE location.

NOTE
This procedure does not remove the certificate itself from the CERT_SYSTEM_STORE_LOCAL_MACHINE location.

9. The new certificate is used for authentication from this point on. Every subsequent renewal of the certificate
replaces the certificate in the CERT_SYSTEM_STORE_LOCAL_MACHINE location.

Auto-update of the Authentication Agents


The Updater application automatically updates the Authentication Agent when a new version is released. The
application does not handle any password validation requests for your tenant.
Azure AD hosts the new version of the software as a signed Windows Installer package (MSI). The MSI is
signed by using Microsoft Authenticode with SHA256 as the digest algorithm.
To auto-update an Authentication Agent:
1. The Updater application pings Azure AD every hour to check if there is a new version of the Authentication
Agent available.
This check is done over a mutually authenticated HTTPS channel by using the same certificate that was
issued during registration. The Authentication Agent and the Updater share the certificate stored on the
server.
2. If a new version is available, Azure AD returns the signed MSI back to the Updater.
3. The Updater verifies that the MSI is signed by Microsoft.
4. The Updater runs the MSI. This action involves the following steps:

NOTE
The Updater runs with Local System privileges.

Stops the Authentication Agent service


Installs the new version of the Authentication Agent on the server
Restarts the Authentication Agent service

NOTE
If you have multiple Authentication Agents registered on your tenant, Azure AD does not renew their certificates or update
them at the same time. Instead, Azure AD does so gradually to ensure the high availability of sign-in requests.

Next steps
Current limitations: Learn which scenarios are supported and which ones are not.
Quick start: Get up and running on Azure AD Pass-through Authentication.
Smart Lockout: Configure the Smart Lockout capability on your tenant to protect user accounts.
How it works: Learn the basics of how Azure AD Pass-through Authentication works.
Frequently asked questions: Find answers to frequently asked questions.
Troubleshoot: Learn how to resolve common problems with the Pass-through Authentication feature.
Azure AD Seamless SSO: Learn more about this complementary feature.
Azure Active Directory Pass-through Authentication:
GDPR compliance
3/13/2018 • 3 min to read • Edit Online

Overview
In May 2018, a European privacy law, the General Data Protection Regulation (GDPR), is due to take effect. The
GDPR imposes new rules on companies, government agencies, non-profits, and other organizations that offer
goods and services to people in the European Union (EU), or that collect and analyze data tied to EU residents. The
GDPR applies no matter where you are located.
Microsoft products and services are available today to help you meet the GDPR requirements. Read more about
Microsoft Privacy policy at Trust Center.
Azure AD Pass-through Authentication creates the following log types, which can contain EUII:
Azure AD Connect trace log files.
Authentication Agent trace log files.
Windows Event log files.
GDPR compliance for Pass-through Authentication can be reached in two ways:
1. Upon request, extract data for a person and remove data from that person from the installations.
2. Ensure no data is retained beyond 48 hours.
We strongly recommend the second option as it is easier to implement and maintain. Following are the instructions
for each log type:
Delete Azure AD Connect trace log files
Check the contents of %ProgramData%\AADConnect folder and delete the trace log contents (trace-*.log files)
of this folder within 48 hours of installing or upgrading Azure AD Connect or modifying Pass-through
Authentication configuration, as this action may create data covered by GDPR.

IMPORTANT
Don’t delete the PersistedState.xml file in this folder, as this file is used to maintain the state of the previous installation of
Azure AD Connect and is used when an upgrade installation is done. This file will never contain any data about a person and
should never be deleted.

You can either review and delete these trace log files using Windows Explorer or you can use the following
PowerShell script to perform the necessary actions:

$Files = ((Get-Item -Path "$env:programdata\aadconnect\trace-*.log").VersionInfo).FileName

Foreach ($file in $Files) {


{Remove-Item -Path $File -Force}
}

Save the script in a file with the ".PS1" extension. Run this script as needed.
To learn more about related Azure AD Connect GDPR requirements, see this article.
Delete Authentication Agent event logs
This product may also create Windows Event Logs. To learn more, please read this article.
To view logs related to the Pass-through Authentication Agent, open the Event Viewer application on the server
and check under Application and Service Logs\Microsoft\AzureAdConnect\AuthenticationAgent\Admin.
Delete Authentication Agent trace log files
You should regularly check the contents of %ProgramData%\Microsoft\Azure AD Connect Authentication
Agent\Trace\ and delete the contents of this folder every 48 hours.

IMPORTANT
If the Authentication Agent service is running, you'll not be able to delete the current log file in the folder. Stop the service
before trying again. To avoid user sign-in failures, you should have already configured Pass-through Authentication for high
availability.

You can either review and delete these files using Windows Explorer or you can use the following script to perform
the necessary actions:

$Files = ((Get-childitem -Path "$env:programdata\microsoft\azure ad connect authentication agent\trace" -


Recurse).VersionInfo).FileName

Foreach ($file in $files) {


{Remove-Item -Path $File -Force}
}

To schedule this script to run every 48 hours follow these steps:


1. Save the script in a file with the ".PS1" extension.
2. Open Control Panel and click on System and Security.
3. Under the Administrative Tools heading, click on “Schedule Tasks”.
4. In Task Scheduler, right-click on “Task Schedule Library” and click on “Create Basic task…”.
5. Enter the name for the new task and click Next.
6. Select “Daily” for the Task Trigger and click Next.
7. Set the recurrence to two days and click Next.
8. Select “Start a program” as the action and click Next.
9. Type “PowerShell” in the box for the Program/script, and in box labeled “Add arguments (optional)”, enter
the full path to the script that you created earlier, then click Next.
10. The next screen shows a summary of the task you are about to create. Verify the values and click Finish to create
the task:
Note about Domain controller logs
If audit logging is enabled, this product may generate security logs for your Domain Controllers. To learn more
about configuring audit policies, read this article.

Next steps
Troubleshoot - Learn how to resolve common issues with the feature.
Multiple Domain Support for Federating with Azure
AD
1/3/2018 • 6 min to read • Edit Online

The following documentation provides guidance on how to use multiple top-level domains and sub-domains
when federating with Office 365 or Azure AD domains.

Multiple top-level domain support


Federating multiple, top-level domains with Azure AD requires some additional configuration that is not required
when federating with one top-level domain.
When a domain is federated with Azure AD, several properties are set on the domain in Azure. One important one
is IssuerUri. This is a URI that is used by Azure AD to identify the domain that the token is associated with. The URI
doesn’t need to resolve to anything but it must be a valid URI. By default, Azure AD sets this to the value of the
federation service identifier in your on-premises AD FS configuration.

NOTE
The federation service identifier is a URI that uniquely identifies a federation service. The federation service is an instance of
AD FS that functions as the security token service.

You can view the IssuerUri by using the PowerShell command


Get-MsolDomainFederationSettings -DomainName <your domain> .

A problem arises when we want to add more than one top-level domain. For example, let's say you have setup
federation between Azure AD and your on-premises environment. For this document I am using bmcontoso.com.
Now I have added a second, top-level domain, bmfabrikam.com.
When we attempt to convert our bmfabrikam.com domain to be federated, we receive an error. The reason for this
is, Azure AD has a constraint that does not allow the IssuerUri property to have the same value for more than one
domain.

SupportMultipleDomain Parameter
To workaround this, we need to add a different IssuerUri which can be done by using the -SupportMultipleDomain
parameter. This parameter is used with the following cmdlets:
New-MsolFederatedDomain
Convert-MsolDomaintoFederated
Update-MsolFederatedDomain

This parameter makes Azure AD configure the IssuerUri so that it is based on the name of the domain. This will be
unique across directories in Azure AD. Using the parameter allows the PowerShell command to complete
successfully.

Looking at the settings of our new bmfabrikam.com domain you can see the following:

Note that -SupportMultipleDomain does not change the other endpoints which are still configured to point to our
federation service on adfs.bmcontoso.com.
Another thing that -SupportMultipleDomain does is that it ensures that the AD FS system includes the proper Issuer
value in tokens issued for Azure AD. It does this by taking the domain portion of the users UPN and setting this as
the domain in the IssuerUri, i.e. https://{upn suffix}/adfs/services/trust.
Thus during authentication to Azure AD or Office 365, the IssuerUri element in the user’s token is used to locate
the domain in Azure AD. If a match cannot be found the authentication will fail.
For example, if a user’s UPN is bsimon@bmcontoso.com, the IssuerUri element in the token AD FS issues will be
set to http://bmcontoso.com/adfs/services/trust. This will match the Azure AD configuration, and authentication
will succeed.
The following is the customized claim rule that implements this logic:

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type =


"http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value, ".+@(?
<domain>.+)", "http://${domain}/adfs/services/trust/"));

IMPORTANT
In order to use the -SupportMultipleDomain switch when attempting to add new or convert already added domains, you
need to have setup your federated trust to support them originally.

How to update the trust between AD FS and Azure AD


If you did not setup the federated trust between AD FS and your instance of Azure AD, you may need to re-create
this trust. This is because, when it is originally setup without the -SupportMultipleDomain parameter, the IssuerUri
is set with the default value. In the screenshot below you can see the IssuerUri is set to
https://adfs.bmcontoso.com/adfs/services/trust.
So now, if we have successfully added an new domain in the Azure AD portal and then attempt to convert it using
Convert-MsolDomaintoFederated -DomainName <your domain> , we get the following error.

If you try to add the -SupportMultipleDomain switch we will receive the following error:

Simply trying to run Update-MsolFederatedDomain -DomainName <your domain> -SupportMultipleDomain on the original
domain will also result in an error.

Use the steps below to add an additional top-level domain. If you have already added a domain and did not use
the -SupportMultipleDomain parameter start with the steps for removing and updating your original domain. If you
have not added a top-level domain yet you can start with the steps for adding a domain using PowerShell of Azure
AD Connect.
Use the following steps to remove the Microsoft Online trust and update your original domain.
1. On your AD FS federation server open AD FS Management.
2. On the left, expand Trust Relationships and Relying Party Trusts
3. On the right, delete the Microsoft Office 365 Identity Platform entry.

4. On a machine that has Azure Active Directory Module for Windows PowerShell installed on it run the following:
$cred=Get-Credential .
5. Enter the username and password of a global administrator for the Azure AD domain you are federating with
6. In PowerShell enter Connect-MsolService -Credential $cred
7. In PowerShell enter Update-MSOLFederatedDomain -DomainName <Federated Domain Name> -SupportMultipleDomain .
This is for the original domain. So using the above domains it would be:
Update-MsolFederatedDomain -DomainName bmcontoso.com -SupportMultipleDomain

Use the following steps to add the new top-level domain using PowerShell
1. On a machine that has Azure Active Directory Module for Windows PowerShell installed on it run the following:
$cred=Get-Credential .
2. Enter the username and password of a global administrator for the Azure AD domain you are federating with
3. In PowerShell enter Connect-MsolService -Credential $cred
4. In PowerShell enter New-MsolFederatedDomain –SupportMultipleDomain –DomainName
Use the following steps to add the new top-level domain using Azure AD Connect.
1. Launch Azure AD Connect from the desktop or start menu
2. Choose “Add an additional Azure AD Domain”
3. Enter your Azure AD and Active Directory credentials
4. Select the second domain you wish to configure for federation.

5. Click Install
Verify the new top-level domain
By using the PowerShell command Get-MsolDomainFederationSettings -DomainName <your domain> you can view the
updated IssuerUri. The screenshot below shows the federation settings were updated on our original domain
http://bmcontoso.com/adfs/services/trust
And the IssuerUri on our new domain has been set to https://bmfabrikam.com/adfs/services/trust

Support for Sub-domains


When you add a sub-domain, because of the way Azure AD handled domains, it will inherit the settings of the
parent. This means that the IssuerUri needs to match the parents.
So lets say for example that I have bmcontoso.com and then add corp.bmcontoso.com. This means that the
IssuerUri for a user from corp.bmcontoso.com will need to be http://bmcontoso.com/adfs/services/trust.
However the standard rule implemented above for Azure AD, will generate a token with an issuer as
http://corp.bmcontoso.com/adfs/services/trust. which will not match the domain's required value and
authentication will fail.
How To enable support for sub-domains
In order to work around this the AD FS relying party trust for Microsoft Online needs to be updated. To do this,
you must configure a custom claim rule so that it strips off any sub-domains from the user’s UPN suffix when
constructing the custom Issuer value.
The following claim will do this:
c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type =
"http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value,
"^.*@([^.]+\.)*?(?<domain>([^.]+\.?){2})$", "http://${domain}/adfs/services/trust/"));

[!NOTE] The last number in the regular expression set the how many parent domains there is in your root domain.
Here i have bmcontoso.com so two parent domains are necessary. If three parent domains were to be kept (i.e.:
corp.bmcontoso.com), then the number would have been three. Eventually a range can be indicated, the match will
always be made to match the maximum of domains. "{2,3}" will match two to three domains (i.e.: bmfabrikam.com
and corp.bmcontoso.com).
Use the following steps to add a custom claim to support sub-domains.
1. Open AD FS Management
2. Right click the Microsoft Online RP trust and choose Edit Claim rules
3. Select the third claim rule, and replace

4. Replace the current claim:

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type =


"http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value,
".+@(?<domain>.+)","http://${domain}/adfs/services/trust/"));

with

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type =


"http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value,
"^.*@([^.]+\.)*?(?<domain>([^.]+\.?){2})$", "http://${domain}/adfs/services/trust/"));
5. Click Ok. Click Apply. Click Ok. Close AD FS Management.
Azure AD Connect: Automatic upgrade
1/17/2018 • 4 min to read • Edit Online

This feature was introduced with build 1.1.105.0 (released February 2016).

Overview
Making sure your Azure AD Connect installation is always up to date has never been easier with the automatic
upgrade feature. This feature is enabled by default for express installations and DirSync upgrades. When a new
version is released, your installation is automatically upgraded. Automatic upgrade is enabled by default for the
following:
Express settings installation and DirSync upgrades.
Using SQL Express LocalDB, which is what Express settings always use. DirSync with SQL Express also use
LocalDB.
The AD account is the default MSOL_ account created by Express settings and DirSync.
Have less than 100,000 objects in the metaverse.
The current state of automatic upgrade can be viewed with the PowerShell cmdlet Get-ADSyncAutoUpgrade . It has
the following states:

STATE COMMENT

Enabled Automatic upgrade is enabled.

Suspended Set by the system only. The system is no longer eligible to


receive automatic upgrades.

Disabled Automatic upgrade is disabled.

You can change between Enabled and Disabled with Set-ADSyncAutoUpgrade . Only the system should set the
state Suspended.
Automatic upgrade is using Azure AD Connect Health for the upgrade infrastructure. For automatic upgrade to
work, make sure you have opened the URLs in your proxy server for Azure AD Connect Health as documented
in Office 365 URLs and IP address ranges.
If the Synchronization Service Manager UI is running on the server, then the upgrade is suspended until the UI
is closed.

Troubleshooting
If your Connect installation does not upgrade itself as expected, then follow these steps to find out what could be
wrong.
First, you should not expect the automatic upgrade to be attempted the first day a new version is released. There
is an intentional randomness before an upgrade is attempted so don't be alarmed if your installation isn't
upgraded immediately.
If you think something is not right, then first run Get-ADSyncAutoUpgrade to ensure automatic upgrade is enabled.
Then, make sure you have opened the required URLs in your proxy or firewall. Automatic update is using Azure
AD Connect Health as described in the overview. If you use a proxy, make sure Health has been configured to use
a proxy server. Also test the Health connectivity to Azure AD.
With the connectivity to Azure AD verified, it is time to look into the eventlogs. Start the event viewer and look in
the Application eventlog. Add an eventlog filter for the source Azure AD Connect Upgrade and the event id
range 300-399.

You can now see the eventlogs associated with the status for automatic upgrade.

The result code has a prefix with an overview of the state.

RESULT CODE PREFIX DESCRIPTION

Success The installation was successfully upgraded.

UpgradeAborted A temporary condition stopped the upgrade. It will be retried


again and the expectation is that it succeeds later.

UpgradeNotSupported The system has a configuration that is blocking the system


from being automatically upgraded. It will be retried to see if
the state is changing, but the expectation is that the system
must be upgraded manually.

Here is a list of the most common messages you find. It does not list all, but the result message should be clear
with what the problem is.

RESULT MESSAGE DESCRIPTION

UpgradeAborted

UpgradeAbortedCouldNotSetUpgradeMarker Could not write to the registry.


RESULT MESSAGE DESCRIPTION

UpgradeAbortedInsufficientDatabasePermissions The built-in administrators group does not have permissions


to the database. Manually upgrade to the latest version of
Azure AD Connect to address this issue.

UpgradeAbortedInsufficientDiskSpace There is not enough disc space to support an upgrade.

UpgradeAbortedSecurityGroupsNotPresent Could not find and resolve all security groups used by the
sync engine.

UpgradeAbortedServiceCanNotBeStarted The NT Service Microsoft Azure AD Sync failed to start.

UpgradeAbortedServiceCanNotBeStopped The NT Service Microsoft Azure AD Sync failed to stop.

UpgradeAbortedServiceIsNotRunning The NT Service Microsoft Azure AD Sync is not running.

UpgradeAbortedSyncCycleDisabled The SyncCycle option in the scheduler has been disabled.

UpgradeAbortedSyncExeInUse The synchronization service manager UI is open on the


server.

UpgradeAbortedSyncOrConfigurationInProgress The installation wizard is running or a sync was scheduled


outside the scheduler.

UpgradeNotSupported

UpgradeNotSupportedAdfsSignInMethod You have selected Adfs as the sign-in method.

UpgradeNotSupportedCustomizedSyncRules You have added your own custom rules to the configuration.

UpgradeNotSupportedDeviceWritebackEnabled You have enabled the device writeback feature.

UpgradeNotSupportedGroupWritebackEnabled You have enabled the group writeback feature.

UpgradeNotSupportedInvalidPersistedState The installation is not an Express settings or a DirSync


upgrade.

UpgradeNotSupportedMetaverseSizeExceeeded You have more than 100,000 objects in the metaverse.

UpgradeNotSupportedMultiForestSetup You are connecting to more than one forest. Express setup
only connects to one forest.

UpgradeNotSupportedNonLocalDbInstall You are not using a SQL Server Express LocalDB database.

UpgradeNotSupportedNonMsolAccount The AD Connector account is not the default MSOL_ account


anymore.

UpgradeNotSupportedNotConfiguredSignInMethod When setting up AAD Connect, you chose Do Not Configure


when selecting the sign-on method.

UpgradeNotSupportedPtaSignInMethod You have selected Pass-through Authentication as the sign-


in method.
RESULT MESSAGE DESCRIPTION

UpgradeNotSupportedStagingModeEnabled The server is set to be in staging mode.

UpgradeNotSupportedUserWritebackEnabled You have enabled the user writeback feature.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Use a SAML 2.0 Identity Provider (IdP) for Single Sign On
12/11/2017 • 13 min to read • Edit Online

This topic contains information on using a SAML 2.0 compliant SP-Lite profile based Identity Provider as the preferred Security Token Service (STS) / identity provider. This is
useful where you already have a user directory and password store on-premises that can be accessed using SAML 2.0. This existing user directory can be used for sign-on to
Office 365 and other Azure AD-secured resources. The SAML 2.0 SP-Lite profile is based on the widely used Security Assertion Markup Language (SAML) federated identity
standard to provide a sign-on and attribute exchange framework.

NOTE
For a list of 3rd party Idps that have been tested for use with Azure AD see the Azure AD federation compatibility list

Microsoft supports this sign-on experience as the integration of a Microsoft cloud service, such as Office 365, with your properly configured SAML 2.0 profile based IdP. SAML
2.0 identity providers are third-party products and therefore Microsoft does not provide support for the deployment, configuration, troubleshooting best practices regarding
them. Once properly configured, the integration with the SAML 2.0 identity provider can be tested for proper configuration by using the Microsoft Connectivity Analyzer Tool
which is described in more detail below. For more information about your SAML 2.0 SP-Lite profile based identity provider, ask the organization that supplied it.

IMPORTANT
Only a limited set of clients are available in this sign-on scenario with SAML 2.0 identity providers, this includes:
Web-based clients such as Outlook Web Access and SharePoint Online
Email-rich clients that use basic authentication and a supported Exchange access method such as IMAP, POP, Active Sync, MAPI, etc. (the Enhanced Client Protocol end point is required to
be deployed), including:
Microsoft Outlook 2010/Outlook 2013/Outlook 2016, Apple iPhone (various iOS versions)
Various Google Android Devices
Windows Phone 7, Windows Phone 7.8, and Windows Phone 8.0
Windows 8 Mail Client and Windows 8.1 Mail Client
Windows 10 Mail Client

All other clients are not available in this sign-on scenario with your SAML 2.0 Identity Provider. For example, the Lync 2010 desktop client is not able to login into the service
with your SAML 2.0 Identity Provider configured for single sign-on.

Azure AD SAML 2.0 protocol requirements


This topic contains detailed requirements on the protocol and message formatting that your SAML 2.0 identity provider must implement to federate with Azure AD to enable
sign-on to one or more Microsoft cloud services (such as Office 365). The SAML 2.0 relying party (SP-STS) for a Microsoft cloud service used in this scenario is Azure AD.
It is recommended that you ensure your SAML 2.0 identity provider output messages be as similar to the provided sample traces as possible. Also, use specific attribute values
from the supplied Azure AD metadata where possible. Once you are happy with your output messages, you can test with the Microsoft Connectivity Analyzer as described
below.
The Azure AD metadata can be downloaded from this URL: https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml. For customers in China
using the China-specific instance of Office 365, the following federation endpoint should be used: https://nexus.partner.microsoftonline-
p.cn/federationmetadata/saml20/federationmetadata.xml.

SAML protocol requirements


This section details how the request and response message pairs are put together in order to help you to format your messages correctly.
Azure AD can be configured to work with identity providers that use the SAML 2.0 SP Lite profile with some specific requirements as listed below. Using the sample SAML
request and response messages along with automated and manual testing, you can work to achieve interoperability with Azure AD.

Signature block requirements


Within the SAML Response message the Signature node contains information about the digital signature for the message itself. The signature block has the following
requirements:
1. The assertion node itself must be signed
2. The RSA-sha1 algorithm must be used as the DigestMethod. Other digital signature algorithms are not accepted.
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
3. You may also sign the XML document.
4. The Transform Algorithm must match the values in the following sample:
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
5. The SignatureMethod Algorithm must match the following sample: <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>

Supported bindings
Bindings are the transport related communications parameters that are required. The following requirements apply to the bindings
1. HTTPS is the required transport.
2. Azure AD will require HTTP POST for token submission during logon
3. Azure AD will use HTTP POST for the authentication request to the identity provider and REDIRECT for the Logoff message to the identity provider.

Required attributes
This table shows requirements for specific attributes in the SAML 2.0 message.

ATTRIBUTE DESCRIPTION

NameID The value of this assertion must be the same as the Azure AD user’s ImmutableID. It can be up
to 64 alpha numeric characters. Any non HTML safe characters must be encoded, for example a
“+” character is shown as “.2B”.
ATTRIBUTE DESCRIPTION

IDPEmail The User Principal Name (UPN) is listed in the SAML response as an element with the name
IDPEmail This is the user’s UserPrincipalName (UPN) in Azure AD/Office 365. The UPN is in email
address format. UPN value in Windows Office 365 (Azure Active Directory).

Issuer This is required to be a URI of the identity provider. You should not reuse the Issuer from the
sample messages. If you have multiple top-level domains in your Azure AD tenants the Issuer
must match the specified URI setting configured per domain.

IMPORTANT
Azure AD currently supports the following NameID Format URI for SAML 2.0:urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

Sample SAML request and response messages


A request and response message pair is shown for the sign-on message exchange. This is a sample request message that is sent from Azure AD to a sample SAML 2.0 identity
provider. The sample SAML 2.0 identity provider is Active Directory Federation Services (AD FS) configured to use SAML-P protocol. Interoperability testing has also been
completed with other SAML 2.0 identity providers.

`<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_7171b0b2-19f2-4ba2-8f94-24b5e56b7f1e"


IssueInstant="2014-01-30T16:18:35Z" Version="2.0" AssertionConsumerServiceIndex="0" >
<saml:Issuer>urn:federation:MicrosoftOnline</saml:Issuer>
<samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"/>
</samlp:AuthnRequest>`

This is a sample response message that is sent from the sample SAML 2.0 compliant identity provider to Azure AD / Office 365.

`<samlp:Response ID="_592c022f-e85e-4d23-b55b-9141c95cd2a5" Version="2.0" IssueInstant="2014-01-31T15:36:31.357Z"


Destination="https://login.microsoftonline.com/login.srf" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" InResponseTo="_049917a6-1183-42fd-a190-1d2cbaf9b144"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://WS2012R2-0.contoso.com/adfs/services/trust</Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</samlp:Status>
<Assertion ID="_7e3c1bcd-f180-4f78-83e1-7680920793aa" IssueInstant="2014-01-31T15:36:31.279Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
<Issuer>http://WS2012R2-0.contoso.com/adfs/services/trust</Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<ds:Reference URI="#_7e3c1bcd-f180-4f78-83e1-7680920793aa">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<ds:DigestValue>CBn/5YqbheaJP425c0pHva9PhNY=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>

<ds:SignatureValue>TciWMyHW2ZODrh/2xrvp5ggmcHBFEd9vrp6DYXp+hZWJzmXMmzwmwS8KNRJKy8H7XqBsdELA1Msqi8I3TmWdnoIRfM/ZAyUppo8suMu6Zw+boE32hoQRnX9EWN/f0vH6zA/YKTzrjca6JQ8gAV1Erw
vRWDpyMcwdYCiWALv9ScbkAcebOE1s1JctZ5RBXggdZWrYi72X+I4i6WgyZcIGai/rZ4v2otoWAEHS0y1yh1qT7NDPpl/McDaTGkNU6C+8VfjD78DrUXEcAfKvPgKlKrOMZnD1lCGsViimGY+LSuIdY45MLmyaa5UT4KWph6d
A==</ds:SignatureValue>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>

<ds:X509Certificate>MIIC7jCCAdagAwIBAgIQRrjsbFPaXIlOG3GTv50fkjANBgkqhkiG9w0BAQsFADAzMTEwLwYDVQQDEyhBREZTIFNpZ25pbmcgLSBXUzIwMTJSMi0wLnN3aW5mb3JtZXIuY29tMB4XDTE0MDEyMDE1M
TY0MFoXDTE1MDEyMDE1MTY0MFowMzExMC8GA1UEAxMoQURGUyBTaWduaW5nIC0gV1MyMDEyUjItMC5zd2luZm9ybWVyLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKe+rLVmXy1QwCwZwqgbbp1/+3ZWxd
9T/jV0hpLIIWr+LCOHqq8n8beJvlivgLmDJo8f+EITnAxWcsJUvVai/35AhHCUq9tc9sqMp5PWtabAEMb2AU72/QlX/72D2/NbGQq1BWYbqUpgpCZ2nSgvlWDHlCiUo//UGsvfox01kjTFlmqQInsJVfRxF5AcCAwEAATANBg
kqhkiG9w0BAQsFAAOCAQEAi8c6C4zaTEc7aQiUgvnGQgCbMZbhUXXLGRpjvFLKaQzkwa9eq7WLJibcSNyGXBa/SfT5wJgsm3TPKgSehGAOTirhcqHheZyvBObAScY7GOT+u9pVYp6raFrc7ez3c+CGHeV/tNvy1hJNs12FYH4
X+ZCNFIT9tprieR25NCdi5SWUbPZL0tVzJsHc1y92b2M2FxqRDohxQgJvyJOpcg2mSBzZZIkvDg7gfPSUXHVS1MQs0RHSbwq/XdQocUUhl9/e/YWCbNNxlM84BxFsBUok1dH/gzBySx+Fc8zYi7cOq9yaBT3RLT6cGmFGVYZJ
W4FyhPZOCLVNsLlnPQcX3dDg9A==</ds:X509Certificate>
</ds:X509Data>
</KeyInfo>
</ds:Signature>
<Subject>
<NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">ABCDEG1234567890</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData InResponseTo="_049917a6-1183-42fd-a190-1d2cbaf9b144" NotOnOrAfter="2014-01-31T15:41:31.357Z"
Recipient="https://login.microsoftonline.com/login.srf" />
</SubjectConfirmation>
</Subject>
<Conditions NotBefore="2014-01-31T15:36:31.263Z" NotOnOrAfter="2014-01-31T16:36:31.263Z">
<AudienceRestriction>
<Audience>urn:federation:MicrosoftOnline</Audience>
</AudienceRestriction>
</Conditions>
<AttributeStatement>
<Attribute Name="IDPEmail">
<AttributeValue>administrator@contoso.com</AttributeValue>
</Attribute>
</AttributeStatement>
<AuthnStatement AuthnInstant="2014-01-31T15:36:30.200Z" SessionIndex="_7e3c1bcd-f180-4f78-83e1-7680920793aa">
<AuthnContext>
<AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthnContextClassRef>
</AuthnContext>
</AuthnStatement>
</Assertion>
</samlp:Response>`

Configure your SAML 2.0 compliant identity provider


This topic contains guidelines on how to configure your SAML 2.0 identity provider to federate with Azure AD to enable single sign-on access to one or more Microsoft cloud
services (such as Office 365) using the SAML 2.0 protocol. The SAML 2.0 relying party for a Microsoft cloud service used in this scenario is Azure AD.

Add Azure AD metadata


Your SAML 2.0 identity provider needs to adhere to information about the Azure AD relying party. Azure AD publishes metadata at https://nexus.microsoftonline-
p.com/federationmetadata/saml20/federationmetadata.xml.
It is recommended that you always import the latest Azure AD metadata when configuring your SAML 2.0 identity provider. Note that Azure AD does not read metadata from
the identity provider.

Add Azure AD as a relying party


You have to enable communication between your SAML 2.0 identity provider and Azure AD. This configuration will be dependent on your specific identity provider and you
should refer to documentation for it. You would typically set the relying party ID to the same as the entityID from the Azure AD metadata.

NOTE
Verify the clock on your SAML 2.0 identity provider server is synchronized to an accurate time source. An inaccurate clock time can cause federated logins to fail.

Install Windows PowerShell for sign-on with SAML 2.0 identity provider
After you have configured your SAML 2.0 identity provider for use with Azure AD sign-on, the next step is to download and install the Azure Active Directory Module for
Windows PowerShell. Once installed, you will use these cmdlets to configure your Azure AD domains as federated domains.
The Azure Active Directory Module for Windows PowerShell is a download for managing your organizations data in Azure AD. This module installs a set of cmdlets to
Windows PowerShell; you run those cmdlets to set up single sign-on access to Azure AD and in turn to all of the cloud services you are subscribed to. For instructions about
how to download and install the cmdlets, see http://technet.microsoft.com/library/jj151815.aspx

Set up a trust between your SAML identity provider and Azure AD


Before configuring federation on an Azure AD domain, it must have a custom domain configured. You cannot federate the default domain that is provided by Microsoft. The
default domain from Microsoft ends with “onmicrosoft.com”. You will run a series of cmdlets in the Windows PowerShell command-line interface to add or convert domains
for single sign-on.
Each Azure Active Directory domain that you want to federate using your SAML 2.0 identity provider must either be added as a single sign-on domain or converted to be a
single sign-on domain from a standard domain. Adding or converting a domain sets up a trust between your SAML 2.0 identity provider and Azure AD.
The following procedure walks you through converting an existing standard domain to a federated domain using SAML 2.0 SP-Lite. Note that your domain may experience an
outage that impacts users up to 2 hours after you take this step.

Configuring a domain in your Azure AD Directory for federation


1. Connect to your Azure AD Directory as a tenant administrator: Connect-MsolService .
2. Configure your desired Office 365 domain to use federation with SAML 2.0:
$dom = "contoso.com" $BrandName - "Sample SAML 2.0 IDP" $LogOnUrl = "https://WS2012R2-0.contoso.com/passiveLogon" $LogOffUrl = "https://WS2012R2-
0.contoso.com/passiveLogOff" $ecpUrl = "https://WS2012R2-0.contoso.com/PAOS" $MyURI = "urn:uri:MySamlp2IDP" $MySigningCert = @"
MIIC7jCCAdagAwIBAgIQRrjsbFPaXIlOG3GTv50fkjANBgkqhkiG9w0BAQsFADAzMTEwLwYDVQQDEyh BREZTIFNpZ25pbmcgLSBXUzIwMTJSMi0wLnN3aW5mb3JtZXIuY29tMB4XDTE0MDEyMDE1MTY0MFoXDT
E1MDEyMDE1MTY0MFowMzExMC8GA1UEAxMoQURGUyBTaWduaW5nIC0gV1MyMDEyUjItMC5zd2luZm9yb WVyLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKe+rLVmXy1QwCwZwqgbbp1/kupQ
VcjKuKLitVDbssFyqbDTjP7WRjlVMWAHBI3kgNT7oE362Gf2WMJFf1b0HcrsgLin7daRXpq4Qi6OA57 sW1YFMj3sqyuTP0eZV3S4+ZbDVob6amsZIdIwxaLP9Zfywg2bLsGnVldB0+XKedZwDbCLCVg+3ZWxd9
T/jV0hpLIIWr+LCOHqq8n8beJvlivgLmDJo8f+EITnAxWcsJUvVai/35AhHCUq9tc9sqMp5PWtabAEM b2AU72/QlX/72D2/NbGQq1BWYbqUpgpCZ2nSgvlWDHlCiUo//UGsvfox01kjTFlmqQInsJVfRxF5AcC
AwEAATANBgkqhkiG9w0BAQsFAAOCAQEAi8c6C4zaTEc7aQiUgvnGQgCbMZbhUXXLGRpjvFLKaQzkwa9 eq7WLJibcSNyGXBa/SfT5wJgsm3TPKgSehGAOTirhcqHheZyvBObAScY7GOT+u9pVYp6raFrc7ez3c+
CGHeV/tNvy1hJNs12FYH4X+ZCNFIT9tprieR25NCdi5SWUbPZL0tVzJsHc1y92b2M2FxqRDohxQgJvy JOpcg2mSBzZZIkvDg7gfPSUXHVS1MQs0RHSbwq/XdQocUUhl9/e/YWCbNNxlM84BxFsBUok1dH/gzBy
Sx+Fc8zYi7cOq9yaBT3RLT6cGmFGVYZJW4FyhPZOCLVNsLlnPQcX3dDg9A==" "@ $uri = "http://WS2012R2-0.contoso.com/adfs/services/trust" $Protocol = "SAMLP" Set-
MsolDomainAuthentication -DomainName $dom -FederationBrandName $dom -Authentication Federated -PassiveLogOnUri $MyURI -ActiveLogOnUri $ecpUrl -SigningCertificate
$MySigningCert -IssuerUri $uri -LogOffUri $url -PreferredAuthenticationProtocol $Protocol

3. You can obtain the signing certificate base64 encoded string from your IDP metadata file. An example of this location has been provided but may differ slightly based
on your implementation.
<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <KeyDescriptor use="signing"> <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> <X509Data>
<X509Certificate>MIIC5jCCAc6gAwIBAgIQLnaxUPzay6ZJsC8HVv/QfTANBgkqhkiG9w0BAQsFADAvMS0wKwYDVQQDEyRBREZTIFNpZ25pbmcgLSBmcy50ZWNobGFiY2VudHJhbC5vcmcwHhcNMTMxMTA0MTgxMzMyWhcNMTQxMTA0MTgxMzMyWjAvMS0wKwYDV
</X509Certificate> </X509Data> </KeyInfo> </KeyDescriptor>

For more information about “Set-MsolDomainAuthentication”, see: http://technet.microsoft.com/library/dn194112.aspx.

NOTE
You must run use “$ecpUrl = “https://WS2012R2-0.contoso.com/PAOS“” only if you set up an ECP extension for your identity provider. Exchange Online clients, excluding Outlook Web
Application (OWA), rely on a POST based active end point. If your SAML 2.0 STS implements an active end point similar to Shibboleth’s ECP implementation of an active end point it may be
possible for these rich clients to interact with the Exchange Online service.

Once federation has been configured you can switch back to “non-federated” (or “managed”), however this change takes up to two hours to complete and it requires
assigning new random passwords for cloud based sign-in to each user. Switching back to “managed” may be required in some scenarios to reset an error in your settings. For
more information on Domain conversion see: http://msdn.microsoft.com/library/windowsazure/dn194122.aspx.

Provision user principals to Azure AD / Office 365


Before you can authenticate your users to Office 365 you must provision Azure AD with user principals that correspond to the assertion in the SAML 2.0 claim. If these user
principals are not known to Azure AD in advance then they cannot be used for federated sign-in. Either Azure AD Connect or Windows PowerShell can be used to provision
user principals.
Azure AD Connect can be used to provision principals to your domains in your Azure AD Directory from the on-premises Active Directory. For more detailed information, see
Integrate your on-premises directories with Azure Active Directory.
Windows PowerShell can also be used to automate adding new users to Azure AD and to synchronize changes from the on-premises directory. To use the Windows
PowerShell cmdlets you must download the Azure Active Directory Modules.
This procedure shows how to add a single user to Azure AD.
1. Connect to your Azure AD Directory as a tenant administrator: Connect-MsolService.
2. Create a new user principal:
New-MsolUser -UserPrincipalName elwoodf1@contoso.com -ImmutableId ABCDEFG1234567890 -DisplayName "Elwood Folk" -FirstName Elwood -LastName Folk -
AlternateEmailAddresses "Elwood.Folk@contoso.com" -LicenseAssignment "samlp2test:ENTERPRISEPACK" -UsageLocation "US"
For more information about “New-MsolUser” check out, http://technet.microsoft.com/library/dn194096.aspx

NOTE
The “UserPrinciplName” value must match the value that you will send for “IDPEmail” in your SAML 2.0 claim and the “ImmutableID” value must match the value sent in your “NameID”
assertion.

Verify single sign-on with your SAML 2.0 IDP


As the administrator, before you verify and manage single sign-on (also called identity federation), review the information and perform the steps in the following articles to set
up single sign-on with your SAML 2.0 SP-Lite based identity provider:
1. You have reviewed the Azure AD SAML 2.0 Protocol Requirements
2. You have configured your SAML 2.0 identity provider
3. Install Windows PowerShell for single sign-on with SAML 2.0 identity provider
4. Set up a trust between SAML 2.0 identity provider and Azure AD
5. Provisioned a known test user principal to Azure Active Directory (Office 365) either through Windows PowerShell or Azure AD Connect.
6. Configure directory synchronization using Azure AD Connect.
After setting up single sign-on with your SAML 2.0 SP-Lite based identity Provider, you should verify that it is working correctly.

NOTE
If you converted a domain, rather than adding one, it may take up to 24 hours to set up single sign-on. Before you verify single sign-on, you should finish setting up Active Directory
synchronization, synchronize your directories, and activate your synced users.

Use the tool to verify that single sign-on has been set up correctly
To verify that single sign-on has been set up correctly, you can perform the following procedure to confirm that you are able to sign in to the cloud service with your corporate
credentials.
Microsoft has provided a tool that you can use to test your SAML 2.0 based identity provider. Before running the test tool you must have configured an Azure AD tenant to
federate with your identity provider.

NOTE
The Connectivity Analyzer requires Internet Explorer 10 or later.

1. Download the Connectivity Analyzer from, https://testconnectivity.microsoft.com/?tabid=Client.


2. Click Install Now to begin downloading and installing the tool.
3. Select “I can’t set up federation with Office 365, Azure, or other services that use Azure Active Directory”.
4. Once the tool is downloaded and running, you will see the Connectivity Diagnostics window. The tool will step you through testing your federation connection.
5. The Connectivity Analyzer will open your SAML 2.0 IDP for you to logon, enter the credentials for the user principal you are testing:

6. At the Federation test sign-in window you should enter an account name and password for the Azure AD tenant that is configured to be federated with your SAML 2.0
identity provider. The tool will attempt to sign-in using those credentials and detailed results of tests performed during the sign-in attempt will be provided as output.
7. This window shows a failed result of testing. Clicking on Review detailed results will show information about the results for each test that was performed. You can also save
the results to disk in order to share them.

NOTE
The Connectivity analyzer also tests Active Federation using the WS*-based and ECP/PAOS protocols. If you are not using these you can disregard the following error: Testing the Active sign-in
flow using your identity provider’s Active federation endpoint.

Manually verify that single sign-on has been set up correctly


Manual verification provides additional steps that you can take to ensure that your SAML 2.0 identity Provider is working properly in many scenarios. To verify that single
sign-on has been set up correctly, complete the following steps:
1. On a domain-joined computer, sign in to your cloud service using the same logon name that you use for your corporate credentials.
2. Click inside the password box. If single sign-on is set up, the password box will be shaded, and you will see the following message: “You are now required to sign in at .”
3. Click the Sign in at link. If you are able to sign in, then single sign-on has been set up.

Next Steps
Active Directory Federation Services management and customization with Azure AD Connect
Azure AD federation compatibility list
Azure AD Connect Custom Installation
GDPR compliance and Azure AD Connect
2/26/2018 • 3 min to read • Edit Online

In May 2018, a European privacy law, the General Data Protection Regulation (GDPR), is due to take effect. The
GDPR imposes new rules on companies, government agencies, non-profits, and other organizations that offer
goods and services to people in the European Union (EU), or that collect and analyze data tied to EU residents. The
GDPR applies no matter where you are located.
Microsoft products and services are available today to help you meet the GDPR requirements. Read more about
Microsoft Privacy policy at Trust Center

NOTE
This article deals with Azure AD Connect and GDPR compliance. For information on Azure AD Connect Health and GDPR
compliance see the article here.

General Data Protection Regulation compliance for Azure AD Connect installations can be reached in two ways:
1. Upon request, extract data for a person and remove data from that person from the installations
2. Ensure no data is retained beyond 48 hours.
The Azure AD Connect team recommends the second option since it is much easier to implement and maintain.
An Azure AD Connect sync server stores the following data that is in scope for GDPR compliance:
1. Data about a person in the Azure AD Connect database
2. Data in the Windows Event log files that may contain information about a person
3. Data in the Azure AD Connect installation log files that may contain about a person
To be GDPR compliant, Azure AD Connect customers should use the following guidelines:
1. Delete the contents of the folder that contains the Azure AD Connect installation log files on a regular basis – at
least every 48 hours
2. This product may also create Event Logs. To learn more about Event Logs logs, please see the documentation
here.
Data about a person is automatically removed from the Azure AD Connect database when that person’s data is
removed from the source system where it originated from. No specific action from administrators is required to be
GDPR compliant. However, it does require that the Azure AD Connect data is synced with your data source at least
every two days.

Delete the Azure AD Connect installation log file folder contents


Regularly check and delete the contents of c:\programdata\aadconnect folder – except for the
PersistedState.Xml file. This file maintains the state of the previous installation of Azure A Connect and is used
when an upgrade installation is performed. This file doesn't contain any data about a person and shouldn't be
deleted.
IMPORTANT
Do not delete the PersistedState.xml file. This file contains no user information and maintains the state of the previous
installation.

You can either review and delete these files using Windows Explorer or you can use a script like the following to
perform the necessary actions:

$Files = ((Get-childitem -Path "$env:programdata\aadconnect" -Recurse).VersionInfo).FileName


Foreach ($file in $files) {
If ($File.ToUpper() -ne "$env:programdata\aadconnect\PERSISTEDSTATE.XML".toupper()) # Do not delete this file
{Remove-Item -Path $File -Force}
}

Schedule this script to run every 48 hours


Use the following steps to schedule the script to run every 48 hours.
1. Save the script in a file with the extension .PS1, then open the Control Panel and click on Systems and
Security.

2. Under the Administrative Tools heading, click on Schedule Tasks.


3. In Task Scheduler, right click on Task Schedule Library and click on Create Basic task…
4. Enter the name for the new task and click Next.
5. Select Daily for the task trigger and click on Next.
6. Set the recurrence to 2 days and click Next.
7. Select Start a program as the action and click on Next.
8. Type PowerShell in the box for the Program/script, and in box labeled Add arguments (optional), enter the
full path to the script that you created earlier, then click Next.
9. The next screen shows a summary of the task you are about to create. Verify the values and click Finish to
create the task.

Next steps
Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect Health and GDPR
Azure AD Connect sync: Prevent accidental deletes
1/17/2018 • 2 min to read • Edit Online

This topic describes the prevent accidental deletes (preventing accidental deletions) feature in Azure AD Connect.
When installing Azure AD Connect, prevent accidental deletes is enabled by default and configured to not allow
an export with more than 500 deletes. This feature is designed to protect you from accidental configuration
changes and changes to your on-premises directory that would affect many users and other objects.

What is prevent accidental deletes


Common scenarios when you see many deletes include:
Changes to filtering where an entire OU or domain is unselected.
All objects in an OU are deleted.
An OU is renamed so all objects in it are considered to be out of scope for synchronization.
The default value of 500 objects can be changed with PowerShell using Enable-ADSyncExportDeletionThreshold ,
which is part of the AD Sync module installed with Azure Active Directory Connect. You should configure this
value to fit the size of your organization. Since the sync scheduler runs every 30 minutes, the value is the number
of deletes seen within 30 minutes.
If there are too many deletes staged to be exported to Azure AD, then the export stops and you receive an email
like this:

Hello (technical contact). At (time) the Identity synchronization service detected that the number of deletions
exceeded the configured deletion threshold for (organization name). A total of (number) objects were sent for
deletion in this Identity synchronization run. This met or exceeded the configured deletion threshold value of
(number) objects. We need you to provide confirmation that these deletions should be processed before we
will proceed. Please see the preventing accidental deletions for more information about the error listed in this
email message.

You can also see the status stopped-deletion-threshold-exceeded when you look in the Synchronization Service
Manager UI for the Export profile.
If this was unexpected, then investigate and take corrective actions. To see which objects are about to be deleted,
do the following:
1. Start Synchronization Service from the Start Menu.
2. Go to Connectors.
3. Select the Connector with type Azure Active Directory.
4. Under Actions to the right, select Search Connector Space.
5. In the pop-up under Scope, select Disconnected Since and pick a time in the past. Click Search. This page
provides a view of all objects about to be deleted. By clicking each item, you can get additional information
about the object. You can also click Column Setting to add additional attributes to be visible in the grid.

If all the deletes are desired, then do the following:


1. To retrieve the current deletion threshold, run the PowerShell cmdlet Get-ADSyncExportDeletionThreshold .
Provide an Azure AD Global Administrator account and password. The default value is 500.
2. To temporarily disable this protection and let those deletes go through, run the PowerShell cmdlet:
Disable-ADSyncExportDeletionThreshold . Provide an Azure AD Global Administrator account and password.

3. With the Azure Active Directory Connector still selected, select the action Run and select Export.
4. To re-enable the protection, run the PowerShell cmdlet:
Enable-ADSyncExportDeletionThreshold -DeletionThreshold 500 . Replace 500 with the value you noticed when
retrieving the current deletion threshold. Provide an Azure AD Global Administrator account and password.

Next steps
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Implement password synchronization with Azure
AD Connect sync
1/17/2018 • 9 min to read • Edit Online

This article provides information that you need to synchronize your user passwords from an on-premises Active
Directory instance to a cloud-based Azure Active Directory (Azure AD) instance.

What is password synchronization


The probability that you're blocked from getting your work done due to a forgotten password is related to the
number of different passwords you need to remember. The more passwords you need to remember, the higher
the probability to forget one. Questions and calls about password resets and other password-related issues
demand the most helpdesk resources.
Password synchronization is a feature used to synchronize user passwords from an on-premises Active
Directory instance to a cloud-based Azure AD instance. Use this feature to sign in to Azure AD services like
Office 365, Microsoft Intune, CRM Online, and Azure Active Directory Domain Services (Azure AD DS). You sign
in to the service by using the same password you use to sign in to your on-premises Active Directory instance.

By reducing the number of passwords, your users need to maintain to just one. Password synchronization helps
you to:
Improve the productivity of your users.
Reduce your helpdesk costs.
Also, if you decide to use Federation with Active Directory Federation Services (AD FS), you can optionally set up
password synchronization as a backup in case your AD FS infrastructure fails.
Password synchronization is an extension to the directory synchronization feature implemented by Azure AD
Connect sync. To use password synchronization in your environment, you need to:
Install Azure AD Connect.
Configure directory synchronization between your on-premises Active Directory instance and your Azure
Active Directory instance.
Enable password synchronization.
For more details, see Integrating your on-premises identities with Azure Active Directory.

NOTE
For more details about Azure Active Directory Domain Services configured for FIPS and password synchronization, see
"Password synchronization and FIPS" later in this article.

How password synchronization works


The Active Directory domain service stores passwords in the form of a hash value representation of the actual
user password. A hash value is a result of a one-way mathematical function (the hashing algorithm). There is no
method to revert the result of a one-way function to the plain text version of a password. You cannot use a
password hash to sign in to your on-premises network.
To synchronize your password, Azure AD Connect sync extracts your password hash from the on-premises
Active Directory instance. Extra security processing is applied to the password hash before it is synchronized to
the Azure Active Directory authentication service. Passwords are synchronized on a per-user basis and in
chronological order.
The actual data flow of the password synchronization process is similar to the synchronization of user data such
as DisplayName or Email Addresses. However, passwords are synchronized more frequently than the standard
directory synchronization window for other attributes. The password synchronization process runs every 2
minutes. You cannot modify the frequency of this process. When you synchronize a password, it overwrites the
existing cloud password.
The first time you enable the password synchronization feature, it performs an initial synchronization of the
passwords of all in-scope users. You cannot explicitly define a subset of user passwords that you want to
synchronize.
When you change an on-premises password, the updated password is synchronized, most often in a matter of
minutes. The password synchronization feature automatically retries failed synchronization attempts. If an error
occurs during an attempt to synchronize a password, an error is logged in your event viewer.
The synchronization of a password has no impact on the user who is currently signed in. Your current cloud
service session is not immediately affected by a synchronized password change that occurs while you are
signed in to a cloud service. However, when the cloud service requires you to authenticate again, you need to
provide your new password.
A user must enter their corporate credentials a second time to authenticate to Azure AD, regardless of whether
they're signed in to their corporate network. These pattern can be minimized, however, if the user selects the
Keep me signed in (KMSI) check box at sign in. This selection sets a session cookie that bypasses authentication
for a short period. KMSI behavior can be enabled or disabled by the Azure AD administrator.

NOTE
Password sync is only supported for the object type user in Active Directory. It is not supported for the iNetOrgPerson
object type.

Detailed description of how password synchronization works


The following describes in-depth how password synchronization works between Active Directory and Azure AD.
1. Every two minutes, the password synchronization agent on the AD Connect server requests stored password
hashes (the unicodePwd attribute) from a DC via the standard MS-DRSR replication protocol used to
synchronize data between DCs. The service account must have Replicate Directory Changes and Replicate
Directory Changes All AD permissions (granted by default on installation) to obtain the password hashes.
2. Before sending, the DC encrypts the MD4 password hash by using a key that is a MD5 hash of the RPC
session key and a salt. It then sends the result to the password synchronization agent over RPC. The DC also
passes the salt to the synchronization agent by using the DC replication protocol, so the agent will be able to
decrypt the envelope.
3. After the password synchronization agent has the encrypted envelope, it uses MD5CryptoServiceProvider
and the salt to generate a key to decrypt the received data back to its original MD4 format. At no point does
the password synchronization agent have access to the clear text password. The password synchronization
agent’s use of MD5 is strictly for replication protocol compatibility with the DC, and it is only used on
premises between the DC and the password synchronization agent.
4. The password synchronization agent expands the 16-byte binary password hash to 64 bytes by first
converting the hash to a 32-byte hexadecimal string, then converting this string back into binary with UTF-
16 encoding.
5. The password synchronization agent adds a salt, consisting of a 10-byte length salt, to the 64-byte binary to
further protect the original hash.
6. The password synchronization agent then combines the MD4 hash plus salt, and inputs it into the PBKDF2
function. 1000 iterations of the HMAC-SHA256 keyed hashing algorithm is used.
7. The password synchronization agent takes the resulting 32-byte hash, concatenates both the salt and the
number of SHA256 iterations to it (for use by Azure AD), then transmits the string from Azure AD Connect to
Azure AD over SSL.
8. When a user attempts to sign in to Azure AD and enters their password, the password is run through the
same MD4+salt+PBKDF2+HMAC-SHA256 process. If the resulting hash matches the hash stored in Azure
AD, the user has entered the correct password and is authenticated.

NOTE
The original MD4 hash is not transmitted to Azure AD. Instead, the SHA256 hash of the original MD4 hash is
transmitted. As a result, if the hash stored in Azure AD is obtained, it cannot be used in an on-premises pass-the-hash
attack.

How password synchronization works with Azure Active Directory Domain Services
You can also use the password synchronization feature to synchronize your on-premises passwords to Azure
Active Directory Domain Services. In this scenario, the Azure Active Directory Domain Services instance
authenticates your users in the cloud with all the methods available in your on-premises Active Directory
instance. The experience of this scenario is similar to using the Active Directory Migration Tool (ADMT) in an on-
premises environment.
Security considerations
When synchronizing passwords, the plain-text version of your password is not exposed to the password
synchronization feature, to Azure AD, or any of the associated services.
User authentication takes place against Azure AD rather than against the organization's own Active Directory
instance. If your organization has concerns about password data in any form leaving the premises, consider the
fact that the SHA256 password data stored in Azure AD--a hash of the original MD4 hash--is significantly more
secure than what is stored in Active Directory. Further, because this SHA256 hash cannot be decrypted, it cannot
be brought back to the organization's Active Directory environment and presented as a valid user password in a
pass-the-hash attack.
Password policy considerations
There are two types of password policies that are affected by enabling password synchronization:
Password complexity policy
Password expiration policy
Password complexity policy
When password synchronization is enabled, the password complexity policies in your on-premises Active
Directory instance override complexity policies in the cloud for synchronized users. You can use all of the valid
passwords from your on-premises Active Directory instance to access Azure AD services.

NOTE
Passwords for users that are created directly in the cloud are still subject to password policies as defined in the cloud.

Password expiration policy


If a user is in the scope of password synchronization, the cloud account password is set to Never Expire.
You can continue to sign in to your cloud services by using a synchronized password that is expired in your on-
premises environment. Your cloud password is updated the next time you change the password in the on-
premises environment.
Account expiration
If your organization uses the accountExpires attribute as part of user account management, be aware that this
attribute is not synchronized to Azure AD. As a result, an expired Active Directory account in an environment
configured for password synchronization will still be active in Azure AD. We recommend that if the account is
expired, a workflow action should trigger a PowerShell script that disables the user's Azure AD account.
Conversely, when the account is turned on, the Azure AD instance should be turned on.
Overwrite synchronized passwords
An administrator can manually reset your password by using Windows PowerShell.
In this case, the new password overrides your synchronized password, and all password policies defined in the
cloud are applied to the new password.
If you change your on-premises password again, the new password is synchronized to the cloud, and it
overrides the manually updated password.
The synchronization of a password has no impact on the Azure user who is signed in. Your current cloud service
session is not immediately affected by a synchronized password change that occurs while you're signed in to a
cloud service. KMSI extends the duration of this difference. When the cloud service requires you to authenticate
again, you need to provide your new password.
Additional advantages
Generally, password synchronization is simpler to implement than a federation service. It doesn't require any
additional servers, and eliminates dependence on a highly available federation service to authenticate users.
Password synchronization can also be enabled in addition to federation. It may be used as a fallback if your
federation service experiences an outage.

Enable password synchronization


When you install Azure AD Connect by using the Express Settings option, password synchronization is
automatically enabled. For more details, see Getting started with Azure AD Connect using express settings.
If you use custom settings when you install Azure AD Connect, password synchronization is available on the
user sign-in page. For more details, see Custom installation of Azure AD Connect.

Password synchronization and FIPS


If your server has been locked down according to Federal Information Processing Standard (FIPS), then MD5 is
disabled.
To enable MD5 for password synchronization, perform the following steps:
1. Go to %programfiles%\Azure AD Sync\Bin.
2. Open miiserver.exe.config.
3. Go to the configuration/runtime node at the end of the file.
4. Add the following node: <enforceFIPSPolicy enabled="false"/>
5. Save your changes.
For reference, this snippet is what it should look like:
<configuration>
<runtime>
<enforceFIPSPolicy enabled="false"/>
</runtime>
</configuration>

For information about security and FIPS, see AAD Password Sync, encryption and FIPS compliance.

Troubleshoot password synchronization


If you have problems with password synchronization, see Troubleshoot password synchronization.

Next steps
Azure AD Connect sync: Customizing synchronization options
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: How to manage the Azure
AD service account
1/17/2018 • 1 min to read • Edit Online

The service account used by the Azure AD Connector is supposed to be service free. If you need to reset its
credentials, then this topic is for you. For example, if a Global Administrator has by mistake reset the password on
the service account using PowerShell.

Reset the credentials


If the service account defined on the Azure AD Connector cannot contact Azure AD due to authentication problems,
the password can be reset.
1. Sign in to the Azure AD Connect sync server and start PowerShell.
2. Run Add-ADSyncAADServiceAccount .

3. Provide Azure AD Global admin credentials.


This cmdlet resets the password for the service account and update it both in Azure AD and in the sync engine.

Known issues these steps can solve


This section is a list of errors reported by customers that were fixed by a credentials reset on the Azure AD service
account.

Event 6900
The server encountered an unexpected error while processing a password change notification:
AADSTS70002: Error validating credentials. AADSTS50054: Old password is used for authentication.

Event 659
Error while retrieving password policy sync configuration.
Microsoft.IdentityModel.Clients.ActiveDirectory.AdalServiceException:
AADSTS70002: Error validating credentials. AADSTS50054: Old password is used for authentication.

Next steps
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: Running the installation
wizard a second time
1/17/2018 • 2 min to read • Edit Online

The first time you run the Azure AD Connect installation wizard, it walks you through how to configure your
installation. If you run the installation wizard again, it offers options for maintenance.
You can find the installation wizard in the start menu named Azure AD Connect.

When you start the installation wizard, you see a page with these options:

If you have installed ADFS with Azure AD Connect, you have even more options. The additional options you have
for ADFS are documented in ADFS management.
Select one of the tasks and click Next to continue.

IMPORTANT
While you have the installation wizard open, all operations in the sync engine are suspended. Make sure you close the
installation wizard as soon as you have completed your configuration changes.
View current configuration
This option gives you a quick view of your currently configured options.

Click Previous to go back. If you select Exit, you close the installation wizard.

Customize synchronization options


This option is used to make changes to the sync configuration. You see a subset of options from the custom
configuration installation path. You see this option even if you used express installation initially.
Add more directories. For removing a directory, see Delete a Connector.
Change Domain and OU filtering.
Remove Group filtering.
Change optional features.
The other options from the initial installation cannot be changed and are not available. These options are:
Change the attribute to use for userPrincipalName and sourceAnchor.
Change the joining method for objects from different forest.
Enable group-based filtering.

Refresh directory schema


This option is used if you have changed the schema in one of your on-premises AD DS forests. For example, you
might have installed Exchange or upgraded to a Windows Server 2012 schema with device objects. In this case,
you need to instruct Azure AD Connect to read the schema again from AD DS and update its cache. This action also
regenerates the Sync Rules. If you add the Exchange schema, as an example, the Sync Rules for Exchange are
added to the configuration.
When you select this option, all the directories in your configuration are listed. You can keep the default setting and
refresh all forests or unselect some of them.

Configure staging mode


This option allows you to enable and disable staging mode on the server. More information about staging mode
and how it is used can be found in Operations.
The option shows if staging is currently enabled or disabled:

To change the state, select this option and select or unselect the checkbox.

Change user sign-in


This option allows you to change from password sync to federation or the other way around. You cannot change to
do not configure.
For more information on this option, see user sign-in.

Next steps
Learn more about the configuration model used by Azure AD Connect sync in Understanding Declarative
Provisioning.
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Azure AD UserPrincipalName population
2/10/2018 • 5 min to read • Edit Online

This article describes how the UserPrincipalName attribute is populated in Azure Active Directory (Azure AD). The
UserPrincipalName attribute value is the Azure AD username for the user accounts.

UPN terminology
The following terminology is used in this article:

TERM DESCRIPTION

Initial domain The default domain (onmicrosoft.com) in the Azure AD Tenant.


For example, contoso.onmicrosoft.com.

Microsoft Online Email Routing Address (MOERA) Azure AD calculates the MOERA from Azure AD MailNickName
attribute and Azure AD initial domain as
<MailNickName>@<initial domain>.

On-premises mailNickName attribute An attribute in Active Directory, the value of which represents
the alias of a user in an Exchange organization.

On-premises mail attribute An attribute in Active Directory, the value of which represents
the email address of a user

Primary SMTP Address The primary email address of an Exchange recipient object. For
example, SMTP:user@contoso.com.

Alternate login ID An on-premises attribute other than UserPrincipalName, such


as mail attribute, used for sign-in.

What is UserPrincipalName?
UserPrincipalName is an attribute that is an Internet-style login name for a user based on the Internet standard RFC
822.
UPN format
A UPN consists of a UPN prefix (the user account name) and a UPN suffix (a DNS domain name). The prefix is
joined with the suffix using the "@" symbol. For example, "someone@example.com". A UPN must be unique among
all security principal objects within a directory forest.

UPN in Azure AD
The UPN is used by Azure AD to allow users to sign-in. The UPN that a user can use, depends on whether or not the
domain has been verified. If the domain has been verified, then a user with that suffix will be allowed to sign-in to
Azure AD.
The attribute is synchronized by Azure AD Connect. During installation you can view the domains that have been
verified and those that have not.
Alternate login ID
In some environments, due to corporate policy or on-premises line-of-business application dependencies, end
users may only be aware of their email address and not their UPN.
Alternate login ID allows you to configure a sign-in experience where users can sign in with an attribute other than
their UPN, such as mail.
To enable Alternate login ID with Azure AD, no additional configurations steps are needed when using Azure AD
Connect. Alternate ID can be configured directly from the wizard. See Azure AD sign-in configuration for your users
under the section Sync. Under the User Principal Name drop-down, select the attribute for Alternate login ID.
For more information see Configure Alternate login ID and Azure AD sign-in configuration

Non-verified UPN Suffix


If the on-premises UserPrincipalName attribute/Alternate login ID suffix is not verified with Azure AD Tenant, then
the Azure AD UserPrincipalName attribute value is set to MOERA. Azure AD calculates the MOERA from the Azure
AD MailNickName attribute and Azure AD initial domain as <MailNickName>@<initial domain>.

Verified UPN suffix


If the on-premises UserPrincipalName attribute/Alternate login ID suffix is verified with the Azure AD Tenant, then
the Azure AD UserPrincipalName attribute value is going to be the same as the on-premises UserPrincipalName
attribute/Alternate login ID value.

Azure AD MailNickName attribute value calculation


Because the Azure AD UserPrincipalName attribute value could be set to MOERA, it is important to understand how
the Azure AD MailNickName attribute value, which is the MOERA prefix, is calculated.
When a user object is synchronized to an Azure AD Tenant for the first time, Azure AD checks the following in the
given order and sets the MailNickName attribute value to the first existing one:
On-premises mailNickName attribute
Prefix of primary SMTP address
Prefix of on-premises mail attribute
Prefix of on-premises userPrincipalName attribute/Alternate login ID
Prefix of secondary smtp address
When the updates to a user object are synchronized to the Azure AD Tenant, Azure AD updates the MailNickName
attribute value only in case there is an update to the on-premises mailNickName attribute value.
IMPORTANT
Azure AD recalculates the UserPrincipalName attribute value only in case an update to the on-premises UserPrincipalName
attribute/Alternate login ID value is synchronized to the Azure AD Tenant.
Whenever Azure AD recalculates the UserPrincipalName attribute, it also recalculates the MOERA.

UPN scenarios
The following are example scenarios of how the UPN is calculated based on the given scenario.
Scenario 1: Non-verified UPN suffix – initial synchronization
On-Premises user object:
mailNickName : <not set>
proxyAddresses : {SMTP:us1@contoso.com}
mail : us2@contoso.com
userPrincipalName : us3@contoso.com`
Synchronized the user object to Azure AD Tenant for the first time
Set Azure AD MailNickName attribute to primary SMTP address prefix.
Set MOERA to <MailNickName>@<initial domain>.
Set Azure AD UserPrincipalName attribute to MOERA.
Azure AD Tenant user object:
MailNickName : us1
UserPrincipalName : us1@contoso.onmicrosoft.com
Scenario 2: Non-verified UPN suffix – set on-premises mailNickName attribute
On-Premises user object:
mailNickName : us4
proxyAddresses : {SMTP:us1@contoso.com}
mail : us2@contoso.com
userPrincipalName : us3@contoso.com
Synchronize update on on-premises mailNickName attribute to Azure AD Tenant
Update Azure AD MailNickName attribute with on-premises mailNickName attribute.
Because there is no update to the on-premises userPrincipalName attribute, there is no change to the Azure AD
UserPrincipalName attribute.
Azure AD Tenant user object:
MailNickName : us4
UserPrincipalName : us1@contoso.onmicrosoft.com
Scenario 3: Non-verified UPN suffix – update on-premises userPrincipalName attribute
On-Premises user object:
mailNickName : us4
proxyAddresses : {SMTP:us1@contoso.com}
mail : us2@contoso.com
userPrincipalName : us5@contoso.com
Synchronize update on on-premises userPrincipalName attribute to Azure AD Tenant
Update on on-premises userPrincipalName attribute triggers recalculation of MOERA and Azure AD
UserPrincipalName attribute.
Set MOERA to <MailNickName>@<initial domain>.
Set Azure AD UserPrincipalName attribute to MOERA.
Azure AD Tenant user object:
MailNickName : us4
UserPrincipalName : us4@contoso.onmicrosoft.com
Scenario 4: Non-verified UPN suffix – update primary SMTP address and on-premises mail attribute
On-Premises user object:
mailNickName : us4
proxyAddresses : {SMTP:us6@contoso.com}
mail : us7@contoso.com
userPrincipalName : us5@contoso.com
Synchronize update on on-premises mail attribute and primary SMTP address to Azure AD Tenant
After the initial synchronization of the user object, updates to the on-premises mail attribute and primary SMTP
address will not affect neither the Azure AD MailNickName nor UserPrincipalName attribute.
Azure AD Tenant user object:
MailNickName : us4
UserPrincipalName : us4@contoso.onmicrosoft.com
Scenario 5: Verified UPN suffix – update on-premises userPrincipalName attribute suffix
On-Premises user object:
mailNickName : us4
proxyAddresses : {SMTP:us6@contoso.com}
mail : us7@contoso.com
serPrincipalName : us5@verified.contoso.com
Synchronize update on on-premises userPrincipalName attribute to the Azure AD Tenant
Update on on-premises userPrincipalName attribute triggers recalculation of Azure AD UserPrincipalName
attribute.
Set Azure AD UserPrincipalName attribute to on-premises userPrincipalName attribute as the UPN suffix is
verified with the Azure AD Tenant.
Azure AD Tenant user object:
MailNickName : us4
UserPrincipalName : us5@verified.contoso.com

Next Steps
Integrate your on-premises directories with Azure Active Directory
Custom installation of Azure AD Connect
Azure AD Connect sync: Best practices for changing
the default configuration
1/17/2018 • 3 min to read • Edit Online

The purpose of this topic is to describe supported and unsupported changes to Azure AD Connect sync.
The configuration created by Azure AD Connect works “as is” for most environments that synchronize on-
premises Active Directory with Azure AD. However, in some cases, it is necessary to apply some changes to a
configuration to satisfy a particular need or requirement.

Changes to the service account


Azure AD Connect sync is running under a service account created by the installation wizard. This service account
holds the encryption keys to the database used by sync. It is created with a 127 characters long password and the
password is set to not expire.
It is unsupported to change or reset the password of the service account. Doing so destroys the encryption
keys and the service is not able to access the database and is not able to start.

Changes to the scheduler


Starting with the releases from build 1.1 (February 2016) you can configure the scheduler to have a different sync
cycle than the default 30 minutes.

Changes to Synchronization Rules


The installation wizard provides a configuration that is supposed to work for the most common scenarios. In case
you need to make changes to the configuration, then you must follow these rules to still have a supported
configuration.
You can change attribute flows if the default direct attribute flows are not suitable for your organization.
If you want to not flow an attribute and remove any existing attribute values in Azure AD, then you need to
create a rule for this scenario.
Disable an unwanted Sync Rule rather than deleting it. A deleted rule is recreated during an upgrade.
To change an out-of-box rule, you should make a copy of the original rule and disable the out-of-box rule. The
Sync Rule Editor prompts and helps you.
Export your custom synchronization rules using the Synchronization Rules Editor. The editor provides you with
a PowerShell script you can use to easily recreate them in a disaster recovery scenario.

WARNING
The out-of-box sync rules have a thumbprint. If you make a change to these rules, the thumbprint is no longer matching.
You might have problems in the future when you try to apply a new release of Azure AD Connect. Only make changes the
way it is described in this article.

Disable an unwanted Sync Rule


Do not delete an out-of-box sync rule. It is recreated during next upgrade.
In some cases, the installation wizard has produced a configuration that is not working for your topology. For
example, if you have an account-resource forest topology but you have extended the schema in the account forest
with the Exchange schema, then rules for Exchange are created for the account forest and the resource forest. In
this case, you need to disable the Sync Rule for Exchange.

In the picture above, the installation wizard has found an old Exchange 2003 schema in the account forest. This
schema extension was added before the resource forest was introduced in Fabrikam's environment. To ensure no
attributes from the old Exchange implementation are synchronized, the sync rule should be disabled as shown.
Change an out-of-box rule
The only time you should change an out-of-box rule is when you need to change the join rule. If you need to
change an attribute flow, then you should create a sync rule with higher precedence than the out-of-box rules. The
only rule you practically need to clone is the rule In from AD - User Join. You can override all other rules with a
higher precedence rule.
If you need to make changes to an out-of-box rule, then you should make a copy of the out-of-box rule and
disable the original rule. Then make the changes to the cloned rule. The Sync Rule Editor is helping you with those
steps. When you open an out-of-box rule, you are presented with this dialog box:

Select Yes to create a copy of the rule. The cloned rule is then opened.
On this cloned rule, make any necessary changes to scope, join, and transformations.

Next steps
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: Configure filtering
1/17/2018 • 21 min to read • Edit Online

By using filtering, you can control which objects appear in Azure Active Directory (Azure AD) from your on-
premises directory. The default configuration takes all objects in all domains in the configured forests. In general,
this is the recommended configuration. Users using Office 365 workloads, such as Exchange Online and Skype
for Business, benefit from a complete Global Address List so they can send email and call everyone. With the
default configuration, they would have the same experience that they would have with an on-premises
implementation of Exchange or Lync.
In some cases however, you're required make some changes to the default configuration. Here are some
examples:
You plan to use the multi-Azure AD directory topology. Then you need to apply a filter to control which
objects are synchronized to a particular Azure AD directory.
You run a pilot for Azure or Office 365 and you only want a subset of users in Azure AD. In the small pilot, it's
not important to have a complete Global Address List to demonstrate the functionality.
You have many service accounts and other nonpersonal accounts that you don't want in Azure AD.
For compliance reasons, you don't delete any user accounts on-premises. You only disable them. But in Azure
AD, you only want active accounts to be present.
This article covers how to configure the different filtering methods.

IMPORTANT
Microsoft doesn't support modifying or operating Azure AD Connect sync outside of the actions that are formally
documented. Any of these actions might result in an inconsistent or unsupported state of Azure AD Connect sync. As a
result, Microsoft can't provide technical support for such deployments.

Basics and important notes


In Azure AD Connect sync, you can enable filtering at any time. If you start with a default configuration of
directory synchronization and then configure filtering, the objects that are filtered out are no longer synchronized
to Azure AD. Because of this change, any objects in Azure AD that were previously synchronized but were then
filtered are deleted in Azure AD.
Before you start making changes to filtering, make sure that you disable the scheduled task so you don't
accidentally export changes that you haven't yet verified to be correct.
Because filtering can remove many objects at the same time, you want to make sure that your new filters are
correct before you start exporting any changes to Azure AD. After you've completed the configuration steps, we
strongly recommend that you follow the verification steps before you export and make changes to Azure AD.
To protect you from deleting many objects by accident, the feature "prevent accidental deletes" is on by default. If
you delete many objects due to filtering (500 by default), you need to follow the steps in this article to allow the
deletes to go through to Azure AD.
If you use a build before November 2015 (1.0.9125), make a change to a filter configuration, and use password
synchronization, then you need to trigger a full sync of all passwords after you've completed the configuration.
For steps on how to trigger a password full sync, see Trigger a full sync of all passwords. If you're on build
1.0.9125 or later, then the regular full synchronization action also calculates whether passwords should be
synchronized and if this extra step is no longer required.
If user objects were inadvertently deleted in Azure AD because of a filtering error, you can recreate the user
objects in Azure AD by removing your filtering configurations. Then you can synchronize your directories again.
This action restores the users from the recycle bin in Azure AD. However, you can't undelete other object types.
For example, if you accidentally delete a security group and it was used to ACL a resource, the group and its ACLs
can't be recovered.
Azure AD Connect only deletes objects that it has once considered to be in scope. If there are objects in Azure AD
that were created by another sync engine and these objects aren't in scope, adding filtering doesn't remove them.
For example, if you start with a DirSync server that created a complete copy of your entire directory in Azure AD,
and you install a new Azure AD Connect sync server in parallel with filtering enabled from the beginning, Azure
AD Connect doesn't remove the extra objects that are created by DirSync.
The filtering configuration is retained when you install or upgrade to a newer version of Azure AD Connect. It's
always a best practice to verify that the configuration wasn't inadvertently changed after an upgrade to a newer
version before running the first synchronization cycle.
If you have more than one forest, then you must apply the filtering configurations that are described in this topic
to every forest (assuming that you want the same configuration for all of them).
Disable the scheduled task
To disable the built-in scheduler that triggers a synchronization cycle every 30 minutes, follow these steps:
1. Go to a PowerShell prompt.
2. Run Set-ADSyncScheduler -SyncCycleEnabled $False to disable the scheduler.
3. Make the changes that are documented in this article.
4. Run Set-ADSyncScheduler -SyncCycleEnabled $True to enable the scheduler again.
If you use an Azure AD Connect build before 1.1.105.0
To disable the scheduled task that triggers a synchronization cycle every three hours, follow these steps:
1. Start Task Scheduler from the Start menu.
2. Directly under Task Scheduler Library, find the task named Azure AD Sync Scheduler, right-click, and
select Disable.

3. You can now make configuration changes and run the sync engine manually from the Synchronization
Service Manager console.
After you've completed all your filtering changes, don't forget to come back and Enable the task again.

Filtering options
You can apply the following filtering configuration types to the directory synchronization tool:
Group-based: Filtering based on a single group can only be configured on initial installation by using the
installation wizard.
Domain-based: By using this option, you can select which domains synchronize to Azure AD. You can also
add and remove domains from the sync engine configuration when you make changes to your on-premises
infrastructure after you install Azure AD Connect sync.
Organizational unit (OU)–based: By using this option, you can select which OUs synchronize to Azure AD.
This option is for all object types in selected OUs.
Attribute-based: By using this option, you can filter objects based on attribute values on the objects. You can
also have different filters for different object types.
You can use multiple filtering options at the same time. For example, you can use OU-based filtering to only
include objects in one OU. At the same time, you can use attribute-based filtering to filter the objects further.
When you use multiple filtering methods, the filters use a logical "AND" between the filters.

Domain-based filtering
This section provides you with the steps to configure your domain filter. If you added or removed domains in
your forest after you installed Azure AD Connect, you also have to update the filtering configuration.
The preferred way to change domain-based filtering is by running the installation wizard and changing domain
and OU filtering. The installation wizard automates all the tasks that are documented in this topic.
You should only follow these steps if you're unable to run the installation wizard for some reason.
Domain-based filtering configuration consists of these steps:
1. Select the domains that you want to include in the synchronization.
2. For each added and removed domain, adjust the run profiles.
3. Apply and verify changes.
Select the domains to be synchronized
To set the domain filter, do the following steps:
1. Sign in to the server that is running Azure AD Connect sync by using an account that is a member of the
ADSyncAdmins security group.
2. Start Synchronization Service from the Start menu.
3. Select Connectors, and in the Connectors list, select the Connector with the type Active Directory Domain
Services. In Actions, select Properties.

4. Click Configure Directory Partitions.


5. In the Select directory partitions list, select and unselect domains as needed. Verify that only the partitions
that you want to synchronize are selected.

If you've changed your on-premises Active Directory infrastructure and added or removed domains from the
forest, then click the Refresh button to get an updated list. When you refresh, you're asked for credentials.
Provide any credentials with read access to Windows Server Active Directory. It doesn't have to be the user
that is prepopulated in the dialog box.

6. When you're done, close the Properties dialog by clicking OK. If you removed domains from the forest, a
message pop-up says that a domain was removed and that configuration will be cleaned up.
7. Continue to adjust the run profiles.
Update the run profiles
If you've updated your domain filter, you also need to update the run profiles.
1. In the Connectors list, make sure that the Connector that you changed in the previous step is selected. In
Actions, select Configure Run Profiles.

2. Find and identify the following profiles:


Full Import
Full Synchronization
Delta Import
Delta Synchronization
Export
3. For each profile, adjust the added and removed domains.
a. For each of the five profiles, do the following steps for each added domain:
a. Select the run profile and click New Step.
b. On the Configure Step page, in the Type drop-down menu, select the step type with the same
name as the profile that you're configuring. Then click Next.

c. On the Connector Configuration page, in the Partition drop-down menu, select the name of
the domain that you've added to your domain filter.

d. To close the Configure Run Profile dialog, click Finish.


b. For each of the five profiles, do the following steps for each removed domain:
a. Select the run profile.
b. If the Value of the Partition attribute is a GUID, select the run step and click Delete Step.
c. Verify your change. Each domain that you want to synchronize should be listed as a step in each run
profile.
4. To close the Configure Run Profiles dialog, click OK.
5. To complete the configuration, you need to run a Full import and a Delta sync. Continue reading the section
Apply and verify changes.

Organizational unit–based filtering


The preferred way to change OU-based filtering is by running the installation wizard and changing domain and
OU filtering. The installation wizard automates all the tasks that are documented in this topic.
You should only follow these steps if you're unable to run the installation wizard for some reason.
To configure organizational unit–based filtering, do the following steps:
1. Sign in to the server that is running Azure AD Connect sync by using an account that is a member of the
ADSyncAdmins security group.
2. Start Synchronization Service from the Start menu.
3. Select Connectors, and in the Connectors list, select the Connector with the type Active Directory Domain
Services. In Actions, select Properties.

4. Click Configure Directory Partitions, select the domain that you want to configure, and then click
Containers.
5. When you're prompted, provide any credentials with read access to your on-premises Active Directory. It
doesn't have to be the user that is prepopulated in the dialog box.
6. In the Select Containers dialog box, clear the OUs that you don’t want to synchronize with the cloud
directory, and then click OK.

The Computers container should be selected for your Windows 10 computers to be successfully
synchronized to Azure AD. If your domain-joined computers are located in other OUs, make sure those
are selected.
The ForeignSecurityPrincipals container should be selected if you have multiple forests with trusts.
This container allows cross-forest security group membership to be resolved.
The RegisteredDevices OU should be selected if you enabled the device writeback feature. If you use
another writeback feature, such as group writeback, make sure these locations are selected.
Select any other OU where Users, iNetOrgPersons, Groups, Contacts, and Computers are located. In the
picture, all these OUs are located in the ManagedObjects OU.
If you use group-based filtering, then the OU where the group is located must be included.
Note that you can configure whether new OUs that are added after the filtering configuration finishes
are synchronized or not synchronized. See the next section for details.
7. When you're done, close the Properties dialog by clicking OK.
8. To complete the configuration, you need to run a Full import and a Delta sync. Continue reading the section
Apply and verify changes.
Synchronize new OUs
New OUs that are created after filtering has been configured are synchronized by default. This state is indicated
by a selected check box. You can also unselect some sub-OUs. To get this behavior, click the box until it becomes
white with a blue check mark (its default state). Then unselect any sub-OUs that you don't want to synchronize.
If all sub-OUs are synchronized, then the box is white with a blue check mark.

If some sub-OUs have been unselected, then the box is gray with a white check mark.

With this configuration, a new OU that was created under ManagedObjects is synchronized.
The Azure AD Connect installation wizard always creates this configuration.
Don't synchronize new OUs
You can configure the sync engine to not synchronize new OUs after the filtering configuration has finished. This
state is indicated in the UI by the box appearing solid gray with no check mark. To get this behavior, click the box
until it becomes white with no check mark. Then select the sub-OUs that you want to synchronize.
With this configuration, a new OU that was created under ManagedObjects isn't synchronized.

Attribute-based filtering
Make sure that you're using the November 2015 (1.0.9125) or later build for these steps to work.
Attribute-based filtering is the most flexible way to filter objects. You can use the power of declarative
provisioning to control almost every aspect of when an object is synchronized to Azure AD.
You can apply inbound filtering from Active Directory to the metaverse, and outbound filtering from the
metaverse to Azure AD. We recommend that you apply inbound filtering because that is the easiest to maintain.
You should only use outbound filtering if it's required to join objects from more than one forest before the
evaluation can take place.
Inbound filtering
Inbound filtering uses the default configuration, where objects going to Azure AD must have the metaverse
attribute cloudFiltered not set to a value to be synchronized. If this attribute's value is set to True, then the object
isn't synchronized. It shouldn't be set to False, by design. To make sure other rules have the ability to contribute a
value, this attribute is only supposed to have the values True or NULL (absent).
In inbound filtering, you use the power of scope to determine which objects to synchronize or not synchronize.
This is where you make adjustments to fit your own organization's requirements. The scope module has a group
and a clause to determine when a sync rule is in scope. A group contains one or many clauses. There is a logical
"AND" between multiple clauses, and a logical "OR" between multiple groups.
Let us look at an example:

This should be read as (department = IT) OR (department = Sales AND c = US).


In the following samples and steps, you use the user object as an example, but you can use this for all object
types.
In the following samples, the precedence value starts with 50. This can be any number not used, but should be
lower than 100.
Negative filtering: "do not sync these"
In the following example, you filter out (not synchronize) all users where extensionAttribute15 has the value
NoSync.
1. Sign in to the server that is running Azure AD Connect sync by using an account that is a member of the
ADSyncAdmins security group.
2. Start Synchronization Rules Editor from the Start menu.
3. Make sure Inbound is selected, and click Add New Rule.
4. Give the rule a descriptive name, such as "In from AD – User DoNotSyncFilter". Select the correct forest, select
User as the CS object type, and select Person as the MV object type. In Link Type, select Join. In
Precedence, type a value that isn't currently used by another synchronization rule (for example 50), and then
click Next.

5. In Scoping filter, click Add Group, and click Add Clause. In Attribute, select ExtensionAttribute15. Make
sure that Operator is set to EQUAL, and type the value NoSync in the Value box. Click Next.

6. Leave the Join rules empty, and then click Next.


7. Click Add Transformation, select the FlowType as Constant, and select cloudFiltered as the Target
Attribute. In the Source text box, type True. Click Add to save the rule.

8. To complete the configuration, you need to run a Full sync. Continue reading the section Apply and verify
changes.
Positive filtering: "only sync these"
Expressing positive filtering can be more challenging because you also have to consider objects that aren't
obvious to be synchronized, such as conference rooms. You are also going to override the default filter in the out-
of-box rule In from AD - User Join. When you create your custom filter, make sure to not include critical system
objects, replication conflict objects, special mailboxes, and the service accounts for Azure AD Connect.
The positive filtering option requires two sync rules. You need one rule (or several) with the correct scope of
objects to synchronize. You also need a second catch-all sync rule that filters out all objects that haven't yet been
identified as an object that should be synchronized.
In the following example, you only synchronize user objects where the department attribute has the value Sales.
1. Sign in to the server that is running Azure AD Connect sync by using an account that is a member of the
ADSyncAdmins security group.
2. Start Synchronization Rules Editor from the Start menu.
3. Make sure Inbound is selected, and click Add New Rule.
4. Give the rule a descriptive name, such as "In from AD – User Sales sync". Select the correct forest, select User
as the CS object type, and select Person as the MV object type. In Link Type, select Join. In Precedence,
type a value that isn't currently used by another synchronization rule (for example 51), and then click Next.

5. In Scoping filter, click Add Group, and click Add Clause. In Attribute, select department. Make sure that
Operator is set to EQUAL, and type the value Sales in the Value box. Click Next.

6. Leave the Join rules empty, and then click Next.


7. Click Add Transformation, select Constant as the FlowType, and select the cloudFiltered as the Target
Attribute. In the Source box, type False. Click Add to save the rule.

This is a special case where you explicitly set cloudFiltered to False.


8. We now have to create the catch-all sync rule. Give the rule a descriptive name, such as "In from AD – User
Catch-all filter". Select the correct forest, select User as the CS object type, and select Person as the MV
object type. In Link Type, select Join. In Precedence, type a value that isn't currently used by another
Synchronization Rule (for example 99). You've selected a precedence value that is higher (lower precedence)
than the previous sync rule. But you've also left some room so that you can add more filtering sync rules later
when you want to start synchronizing additional departments. Click Next.

9. Leave Scoping filter empty, and click Next. An empty filter indicates that the rule is to be applied to all
objects.
10. Leave the Join rules empty, and then click Next.
11. Click Add Transformation, select Constant as the FlowType, and select cloudFiltered as the Target
Attribute. In the Source box, type True. Click Add to save the rule.

12. To complete the configuration, you need to run a Full sync. Continue reading the section Apply and verify
changes.
If you need to, you can create more rules of the first type where you include more objects in the synchronization.
Outbound filtering
In some cases, it's necessary to do the filtering only after the objects have joined in the metaverse. For example, it
might be necessary to look at the mail attribute from the resource forest, and the userPrincipalName attribute
from the account forest, to determine if an object should be synchronized. In these cases, you create the filtering
on the outbound rule.
In this example, you change the filtering so that only users that have both their mail and userPrincipalName
ending in @contoso.com are synchronized:
1. Sign in to the server that is running Azure AD Connect sync by using an account that is a member of the
ADSyncAdmins security group.
2. Start Synchronization Rules Editor from the Start menu.
3. Under Rules Type, click Outbound.
4. Depending on the version of Connect you use, either find the rule named Out to AAD – User Join or Out to
AAD - User Join SOAInAD, and click Edit.
5. In the pop-up, answer Yes to create a copy of the rule.
6. On the Description page, change Precedence to an unused value, such as 50.
7. Click Scoping filter on the left-hand navigation, and then click Add clause. In Attribute, select mail. In
Operator, select ENDSWITH. In Value, type @contoso.com, and then click Add clause. In Attribute, select
userPrincipalName. In Operator, select ENDSWITH. In Value, type @contoso.com.
8. Click Save.
9. To complete the configuration, you need to run a Full sync. Continue reading the section Apply and verify
changes.

Apply and verify changes


After you've made your configuration changes, you must apply them to the objects that are already present in the
system. It might also be that the objects that aren't currently in the sync engine should be processed (and the
sync engine needs to read the source system again to verify its content).
If you changed the configuration by using domain or organizational-unit filtering, then you need to do a Full
import, followed by Delta synchronization.
If you changed the configuration by using attribute filtering, then you need to do a Full synchronization.
Do the following steps:
1. Start Synchronization Service from the Start menu.
2. Select Connectors. In the Connectors list, select the Connector where you made a configuration change
earlier. In Actions, select Run.
3. In Run profiles, select the operation that was mentioned in the previous section. If you need to run two
actions, run the second after the first one has finished. (The State column is Idle for the selected connector.)
After the synchronization, all changes are staged to be exported. Before you actually make the changes in Azure
AD, you want to verify that all these changes are correct.
1. Start a command prompt, and go to %Program Files%\Microsoft Azure AD Sync\bin .
2. Run csexport "Name of Connector" %temp%\export.xml /f:x .
The name of the Connector is in Synchronization Service. It has a name similar to "contoso.com – AAD" for
Azure AD.
3. Run CSExportAnalyzer %temp%\export.xml > %temp%\export.csv .
4. You now have a file in %temp% named export.csv that can be examined in Microsoft Excel. This file contains all
the changes that are about to be exported.
5. Make the necessary changes to the data or configuration, and run these steps again (Import, Synchronize, and
Verify) until the changes that are about to be exported are what you expect.
When you're satisfied, export the changes to Azure AD.
1. Select Connectors. In the Connectors list, select the Azure AD Connector. In Actions, select Run.
2. In Run profiles, select Export.
3. If your configuration changes delete many objects, then you see an error in the export when the number is
more than the configured threshold (by default 500). If you see this error, then you need to temporarily
disable the "prevent accidental deletes" feature.
Now it's time to enable the scheduler again.
1. Start Task Scheduler from the Start menu.
2. Directly under Task Scheduler Library, find the task named Azure AD Sync Scheduler, right-click, and
select Enable.

Group-based filtering
You can configure group-based filtering the first time that you install Azure AD Connect by using custom
installation. It's intended for a pilot deployment where you want only a small set of objects to be synchronized.
When you disable group-based filtering, it can't be enabled again. It's not supported to use group-based filtering
in a custom configuration. It's only supported to configure this feature by using the installation wizard. When
you've completed your pilot, then use one of the other filtering options in this topic. When using OU-based
filtering in conjunction with group-based filtering, the OU(s) where the group and its members are located must
be included.
When synchronizing multiple AD forests, you can configure group-based filtering by specifying a different group
for each AD connector. If you wish to synchronize a user in one AD forest and the same user has one or more
corresponding objects in other AD forests, you must ensure that the user object and all its corresponding objects
are within group-based filtering scope. For examples:
You have a user in one forest that has a corresponding FSP (Foreign Security Principal) object in another
forest. Both objects must be within group-based filtering scope. Otherwise, the user will not be
synchronized to Azure AD.
You have a user in one forest that has a corresponding resource account (e.g., linked mailbox) in another
forest. Further, you have configured Azure AD Connect to link the user with the resource account. Both
objects must be within group-based filtering scope. Otherwise, the user will not be synchronized to Azure
AD.
You have a user in one forest that has a corresponding mail contact in another forest. Further, you have
configured Azure AD Connect to link the user with the mail contact. Both objects must be within group-
based filtering scope. Otherwise, the user will not be synchronized to Azure AD.

Next steps
Learn more about Azure AD Connect sync configuration.
Learn more about integrating your on-premises identities with Azure AD.
Azure AD Connect sync: Scheduler
1/17/2018 • 7 min to read • Edit Online

This topic describes the built-in scheduler in Azure AD Connect sync (a.k.a. sync engine).
This feature was introduced with build 1.1.105.0 (released February 2016).

Overview
Azure AD Connect sync synchronize changes occurring in your on-premises directory using a scheduler. There
are two scheduler processes, one for password sync and another for object/attribute sync and maintenance
tasks. This topic covers the latter.
In earlier releases, the scheduler for objects and attributes was external to the sync engine. It used Windows task
scheduler or a separate Windows service to trigger the synchronization process. The scheduler is with the 1.1
releases built-in to the sync engine and do allow some customization. The new default synchronization
frequency is 30 minutes.
The scheduler is responsible for two tasks:
Synchronization cycle. The process to import, sync, and export changes.
Maintenance tasks. Renew keys and certificates for Password reset and Device Registration Service (DRS).
Purge old entries in the operations log.
The scheduler itself is always running, but it can be configured to only run one or none of these tasks. For
example, if you need to have your own synchronization cycle process, you can disable this task in the scheduler
but still run the maintenance task.

Scheduler configuration
To see your current configuration settings, go to PowerShell and run Get-ADSyncScheduler . It shows you
something like this picture:

If you see The sync command or cmdlet is not available when you run this cmdlet, then the PowerShell
module is not loaded. This problem could happen if you run Azure AD Connect on a domain controller or on a
server with higher PowerShell restriction levels than the default settings. If you see this error, then run
Import-Module ADSync to make the cmdlet available.

AllowedSyncCycleInterval. The shortest time interval between synchronization cycles allowed by Azure AD.
You cannot synchronize more frequently than this setting and still be supported.
CurrentlyEffectiveSyncCycleInterval. The schedule currently in effect. It has the same value as
CustomizedSyncInterval (if set) if it is not more frequent than AllowedSyncInterval. If you use a build before
1.1.281 and you change CustomizedSyncCycleInterval, this change takes effect after next synchronization
cycle. From build 1.1.281 the change takes effect immediately.
CustomizedSyncCycleInterval. If you want the scheduler to run at any other frequency than the default 30
minutes, then you configure this setting. In the picture above, the scheduler has been set to run every hour
instead. If you set this setting to a value lower than AllowedSyncInterval, then the latter is used.
NextSyncCyclePolicyType. Either Delta or Initial. Defines if the next run should only process delta changes,
or if the next run should do a full import and sync. The latter would also reprocess any new or changed rules.
NextSyncCycleStartTimeInUTC. Next time the scheduler starts the next sync cycle.
PurgeRunHistoryInterval. The time operation logs should be kept. These logs can be reviewed in the
synchronization service manager. The default is to keep these logs for 7 days.
SyncCycleEnabled. Indicates if the scheduler is running the import, sync, and export processes as part of its
operation.
MaintenanceEnabled. Shows if the maintenance process is enabled. It updates the certificates/keys and
purges the operations log.
StagingModeEnabled. Shows if staging mode is enabled. If this setting is enabled, then it suppresses the
exports from running but still run import and synchronization.
SchedulerSuspended. Set by Connect during an upgrade to temporarily block the scheduler from running.
You can change some of these settings with Set-ADSyncScheduler . The following parameters can be modified:
CustomizedSyncCycleInterval
NextSyncCyclePolicyType
PurgeRunHistoryInterval
SyncCycleEnabled
MaintenanceEnabled
In earlier builds of Azure AD Connect, isStagingModeEnabled was exposed in Set-ADSyncScheduler. It is
unsupported to set this property. The property SchedulerSuspended should only be modified by Connect. It is
unsupported to set this with PowerShell directly.
The scheduler configuration is stored in Azure AD. If you have a staging server, any change on the primary server
also affects the staging server (except IsStagingModeEnabled).
CustomizedSyncCycleInterval
Syntax: Set-ADSyncScheduler -CustomizedSyncCycleInterval d.HH:mm:ss
d - days, HH - hours, mm - minutes, ss - seconds
Example: Set-ADSyncScheduler -CustomizedSyncCycleInterval 03:00:00
Changes the scheduler to run every 3 hours.
Example: Set-ADSyncScheduler -CustomizedSyncCycleInterval 1.0:0:0
Changes change the scheduler to run daily.
Disable the scheduler
If you need to make configuration changes, then you want to disable the scheduler. For example, when you
configure filtering or make changes to synchronization rules.
To disable the scheduler, run Set-ADSyncScheduler -SyncCycleEnabled $false .

When you've made your changes, do not forget to enable the scheduler again with
Set-ADSyncScheduler -SyncCycleEnabled $true .

Start the scheduler


The scheduler is by default run every 30 minutes. In some cases, you might want to run a sync cycle in between
the scheduled cycles or you need to run a different type.
Delta sync cycle
A delta sync cycle includes the following steps:
Delta import on all Connectors
Delta sync on all Connectors
Export on all Connectors
It could be that you have an urgent change that must be synchronized immediately, which is why you need to
manually run a cycle. If you need to manually run a cycle, then from PowerShell run
Start-ADSyncSyncCycle -PolicyType Delta .

Full sync cycle


If you have made one of the following configuration changes, you need to run a full sync cycle (a.k.a. Initial):
Added more objects or attributes to be imported from a source directory
Made changes to the Synchronization rules
Changed filtering so a different number of objects should be included
If you have made one of these changes, then you need to run a full sync cycle so the sync engine has the
opportunity to reconsolidate the connector spaces. A full sync cycle includes the following steps:
Full Import on all Connectors
Full Sync on all Connectors
Export on all Connectors
To initiate a full sync cycle, run Start-ADSyncSyncCycle -PolicyType Initial from a PowerShell prompt. This
command starts a full sync cycle.

Stop the scheduler


If the scheduler is currently running a synchronization cycle, you might need to stop it. For example if you start
the installation wizard and you get this error:
When a sync cycle is running, you cannot make configuration changes. You could wait until the scheduler has
finished the process, but you can also stop it so you can make your changes immediately. Stopping the current
cycle is not harmful and pending changes are processed with next run.
1. Start by telling the scheduler to stop its current cycle with the PowerShell cmdlet Stop-ADSyncSyncCycle .
2. If you use a build before 1.1.281, then stopping the scheduler does not stop the current Connector from its
current task. To force the Connector to stop, take the following actions:

Start Synchronization Service from the start menu. Go to Connectors, highlight the Connector with
the state Running, and select Stop from the Actions.
The scheduler is still active and starts again on next opportunity.

Custom scheduler
The cmdlets documented in this section are only available in build 1.1.130.0 and later.
If the built-in scheduler does not satisfy your requirements, then you can schedule the Connectors using
PowerShell.
Invoke -ADSyncRunProfile
You can start a profile for a Connector in this way:

Invoke-ADSyncRunProfile -ConnectorName "name of connector" -RunProfileName "name of profile"

The names to use for Connector names and Run Profile Names can be found in the Synchronization Service
Manager UI.

The Invoke-ADSyncRunProfile cmdlet is synchronous, that is, it does not return control until the Connector has
completed the operation, either successfully or with an error.
When you schedule your Connectors, the recommendation is to schedule them in the following order:
1. (Full/Delta) Import from on-premises directories, such as Active Directory
2. (Full/Delta) Import from Azure AD
3. (Full/Delta) Synchronization from on-premises directories, such as Active Directory
4. (Full/Delta) Synchronization from Azure AD
5. Export to Azure AD
6. Export to on-premises directories, such as Active Directory
This order is how the built-in scheduler runs the Connectors.
Get-ADSyncConnectorRunStatus
You can also monitor the sync engine to see if it is busy or idle. This cmdlet returns an empty result if the sync
engine is idle and is not running a Connector. If a Connector is running, it returns the name of the Connector.

Get-ADSyncConnectorRunStatus

In the picture above, the first line is from a state where the sync engine is idle. The second line from when the
Azure AD Connector is running.

Scheduler and installation wizard


If you start the installation wizard, then the scheduler is temporarily suspended. This behavior is because it is
assumed you make configuration changes and these settings cannot be applied if the sync engine is actively
running. For this reason, do not leave the installation wizard open since it stops the sync engine from performing
any synchronization actions.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect sync: Directory extensions
2/21/2018 • 1 min to read • Edit Online

You can use directory extensions to extend the schema in Azure Active Directory (Azure AD) with your own
attributes from on-premises Active Directory. This feature enables you to build LOB apps by consuming attributes
that you continue to manage on-premises. These attributes can be consumed through Azure AD Graph API
directory extensions or Microsoft Graph. You can see the available attributes by using Azure AD Graph Explorer
and Microsoft Graph Explorer, respectively.
At present, no Office 365 workload consumes these attributes.
You configure which additional attributes you want to synchronize in the custom settings path in the installation
wizard.

The installation shows the following attributes, which are valid candidates:
User and Group object types
Single-valued attributes: String, Boolean, Integer, Binary
Multi-valued attributes: String, Binary

NOTE
Azure AD Connect supports synchronizing multi-valued Active Directory attributes to Azure AD as multi-valued directory
extensions. But no features in Azure AD currently support the use of multi-valued directory extensions.

The list of attributes is read from the schema cache that's created during installation of Azure AD Connect. If you
have extended the Active Directory schema with additional attributes, you must refresh the schema before these
new attributes are visible.
An object in Azure AD can have up to 100 attributes for directory extensions. The maximum length is 250
characters. If an attribute value is longer, the sync engine truncates it.
During installation of Azure AD Connect, an application is registered where these attributes are available. You can
see this application in the Azure portal.

The attributes are prefixed with the extension _{AppClientId}_. AppClientId has the same value for all attributes in
your Azure AD tenant.
These attributes are now available through the Azure AD Graph API. You can query them by using Azure AD
Graph Explorer.

Or you can query the attributes through the Microsoft Graph API, by using Microsoft Graph Explorer.

NOTE
You need to ask for the attributes to be returned. Explicitly select the attributes like this:
https://graph.microsoft.com/beta/users/abbie.spencer@fabrikamonline.com?
$select=extension_9d98ed114c4840d298fad781915f27e4_employeeID,extension_9d98ed114c4840d298fad781915f27e4_
division.
For more information, see Microsoft Graph: Use query parameters.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Changing the Azure AD Connect sync service
account password
1/17/2018 • 4 min to read • Edit Online

If you change the Azure AD Connect sync service account password, the Synchronization Service will not be able
start correctly until you have abandoned the encryption key and reinitialized the Azure AD Connect sync service
account password.
Azure AD Connect, as part of the Synchronization Services uses an encryption key to store the passwords of the AD
DS and Azure AD service accounts. These accounts are encrypted before they are stored in the database.
The encryption key used is secured using Windows Data Protection (DPAPI). DPAPI protects the encryption key
using the password of the Azure AD Connect sync service account.
If you need to change the service account password you can use the procedures in Abandoning the Azure AD
Connect Sync encryption key to accomplish this. These procedures should also be used if you need to abandon the
encryption key for any reason.

Issues that arise from changing the password


There are two things that need to be done when you change the service account password.
First, you need to change the password under the Windows Service Control Manager. Until this issue is resolved
you will see following errors:
If you try to start the Synchronization Service in Windows Service Control Manager, you receive the error
"Windows could not start the Microsoft Azure AD Sync service on Local Computer". Error 1069: The
service did not start due to a logon failure."
Under Windows Event Viewer, the system event log contains an error with Event ID 7038 and message “The
ADSync service was unable to log on as with the currently configured password due to the following
error: The user name or password is incorrect."
Second, under specific conditions, if the password is updated, the Synchronization Service can no longer retrieve
the encryption key via DPAPI. Without the encryption key, the Synchronization Service cannot decrypt the
passwords required to synchronize to/from on-premises AD and Azure AD. You will see errors such as:
Under Windows Service Control Manager, if you try to start the Synchronization Service and it cannot retrieve
the encryption key, it fails with error “Windows could not start the Microsoft Azure AD Sync on Local
Computer. For more information, review the System Event log. If this is a non-Microsoft service,
contact the service vendor, and refer to service-specific error code **-21451857952**.”
Under Windows Event Viewer, the application event log contains an error with Event ID 6028 and error
message “The server encryption key cannot be accessed.”
To ensure that you do not receive these errors, follow the procedures in Abandoning the Azure AD Connect Sync
encryption key when changing the password.

Abandoning the Azure AD Connect Sync encryption key


IMPORTANT
The following procedures only apply to Azure AD Connect build 1.1.443.0 or older.

Use the following procedures to abandon the encryption key.


What to do if you need to abandon the encryption key
If you need to abandon the encryption key, use the following procedures to accomplish this.
1. Abandon the existing encryption key
2. Provide the password of the AD DS account
3. Reinitialize the password of the Azure AD sync account
4. Start the Synchronization Service
Abandon the existing encryption key
Abandon the existing encryption key so that new encryption key can be created:
1. Log in to your Azure AD Connect Server as administrator.
2. Start a new PowerShell session.
3. Navigate to folder: $env:Program Files\Microsoft Azure AD Sync\bin\

4. Run the command: ./miiskmu.exe /a

Provide the password of the AD DS account


As the existing passwords stored inside the database can no longer be decrypted, you need to provide the
Synchronization Service with the password of the AD DS account. The Synchronization Service encrypts the
passwords using the new encryption key:
1. Start the Synchronization Service Manager (START → Synchronization Service).

2. Go to the Connectors tab.


3. Select the AD Connector that corresponds to your on-premises AD. If you have more than one AD connector,
repeat the following steps for each of them.
4. Under Actions, select Properties.
5. In the pop-up dialog, select Connect to Active Directory Forest:
6. Enter the password of the AD DS account in the Password textbox. If you do not know its password, you must
set it to a known value before performing this step.
7. Click OK to save the new password and close the pop-up dialog.

Reinitialize the password of the Azure AD sync account


You cannot directly provide the password of the Azure AD service account to the Synchronization Service. Instead,
you need to use the cmdlet Add-ADSyncAADServiceAccount to reinitialize the Azure AD service account. The
cmdlet resets the account password and makes it available to the Synchronization Service:
1. Start a new PowerShell session on the Azure AD Connect server.
2. Run cmdlet Add-ADSyncAADServiceAccount .
3. In the pop-up dialog, provide the Azure AD Global admin credentials for your Azure AD tenant.

4. If it is successful, you will see the PowerShell command prompt.


Start the Synchronization Service
Now that the Synchronization Service has access to the encryption key and all the passwords it needs, you can
restart the service in the Windows Service Control Manager:
1. Go to Windows Service Control Manager (START → Services).
2. Select Microsoft Azure AD Sync and click Restart.

Next steps
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Changing the AD DS account password
1/17/2018 • 1 min to read • Edit Online

The AD DS account refers to the user account used by Azure AD Connect to communicate with on-premises Active
Directory. If you change the password of the AD DS account, you must update Azure AD Connect Synchronization
Service with the new password. Otherwise, the Synchronization can no longer synchronize correctly with the on-
premises Active Directory and you will encounter the following errors:
In the Synchronization Service Manager, any import or export operation with on-premises AD fails with no-
start-credentials error.
Under Windows Event Viewer, the application event log contains an error with Event ID 6000 and message
'The management agent "contoso.com" failed to run because the credentials were invalid'.

How to update the Synchronization Service with new password for AD


DS account
To update the Synchronization Service with the new password:
1. Start the Synchronization Service Manager (START → Synchronization Service).

2. Go to the Connectors tab.


3. Select the AD Connector that corresponds to the AD DS account for which its password was changed.
4. Under Actions, select Properties.
5. In the pop-up dialog, select Connect to Active Directory Forest:
6. Enter the new password of the AD DS account in the Password textbox.
7. Click OK to save the new password and close the pop-up dialog.
8. Restart the Azure AD Connect Synchronization Service under Windows Service Control Manager. This is to
ensure that any reference to the old password is removed from the memory cache.

Next steps
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: Enable AD recycle bin
1/17/2018 • 1 min to read • Edit Online

It is recommended that you enable the AD Recycle Bin feature for your on-premises Active Directories, which are
synchronized to Azure AD.
If you accidentally deleted an on-premises AD user object and restore it using the feature, Azure AD restores the
corresponding Azure AD user object. For information about the AD Recycle Bin feature, refer to article Scenario
Overview for Restoring Deleted Active Directory Objects.

Benefits of enabling the AD recycle bin


This feature helps with restoring Azure AD user objects by doing the following:
If you accidentally deleted an on-premises AD user object, the corresponding Azure AD user object will be
deleted in the next sync cycle. By default, Azure AD keeps the deleted Azure AD user object in soft-deleted
state for 30 days.
If you have on-premises AD Recycle Bin feature enabled, you can restore the deleted on-premises AD user
object without changing its Source Anchor value. When the recovered on-premises AD user object is
synchronized to Azure AD, Azure AD will restore the corresponding soft-deleted Azure AD user object. For
information about Source Anchor attribute, refer to article Azure AD Connect: Design concepts.
If you do not have on-premises AD Recycle Bin feature enabled, you may be required to create an AD user
object to replace the deleted object. If Azure AD Connect Synchronization Service is configured to use
system-generated AD attribute (such as ObjectGuid) for the Source Anchor attribute, the newly created AD
user object will not have the same Source Anchor value as the deleted AD user object. When the newly
created AD user object is synchronized to Azure AD, Azure AD creates a new Azure AD user object instead of
restoring the soft-deleted Azure AD user object.

NOTE
By default, Azure AD keeps deleted Azure AD user objects in soft-deleted state for 30 days before they are permanently
deleted. However, administrators can accelerate the deletion of such objects. Once the objects are permanently deleted, they
can no longer be recovered, even if on-premises AD Recycle Bin feature is enabled.

Next steps
Overview topics
Azure AD Connect sync: Understand and customize synchronization
Integrating your on-premises identities with Azure Active Directory
Introduction to the Azure AD Connect
Synchronization Service Manager UI
1/17/2018 • 1 min to read • Edit Online

The Synchronization Service Manager UI is used to configure more advanced aspects of the sync engine and to
see the operational aspects of the service.
You start the Synchronization Service Manager UI from the start menu. It is named Synchronization Service
and can be found in the Azure AD Connect group.

Click the links at the top of this topic to learn more about the different tabs in the UI.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Using the Sync Service Manager Operations tab
1/29/2018 • 1 min to read • Edit Online

The operations tab shows the results from the most recent operations. This tab is key to understand and
troubleshoot issues.

Understand the information visible in the operations tab


The top half shows all runs in chronological order. By default, the operations log keeps information about the last
seven days, but this setting can be changed with the scheduler. You want to look for any run that does not show a
success status. You can change the sorting by clicking the headers.
The Status column is the most important information and shows the most severe problem for a run. Here is a
quick summary of the most common statuses in order of priority to investigate (where * indicate several possible
error strings).

STATUS COMMENT

stopped-* The run could not complete. For example, if the remote system
is down and cannot be contacted.

stopped-error-limit There are more than 5,000 errors. The run was automatically
stopped due to the large number of errors.

completed-*-errors The run completed, but there are errors (fewer than 5,000)
that should be investigated.
STATUS COMMENT

completed-*-warnings The run completed, but some data is not in the expected state.
If you have errors, then this message is usually only a
symptom. Until you have addressed errors, you should not
investigate warnings.

success No issues.

When you select a row, the bottom updates to show the details of that run. To the far left of the bottom, you might
have a list saying Step #. This list only appears if you have multiple domains in your forest where each domain is
represented by a step. The domain name can be found under the heading Partition. Under Synchronization
Statistics, you can find more information about the number of changes that were processed. You can click the links
to get a list of the changed objects. If you have objects with errors, those errors show up under Synchronization
Errors.
For more information, see troubleshoot an object that is not synchronizing

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Using connectors with the Azure AD Connect Sync
Service Manager
1/17/2018 • 2 min to read • Edit Online

The Connectors tab is used to manage all systems the sync engine is connected to.

Connector actions
ACTION COMMENT

Create Do not use. For connecting to additional AD forests, use the


installation wizard.

Properties Used for domain and OU filtering.

Delete Used to either delete the data in the connector space or to


delete connection to a forest.

Configure Run Profiles Except for domain filtering, nothing to configure here. You can
use this action to see already configured run profiles.

Run Used to start a one-off run of a profile.

Stop Stops a Connector currently running a profile.

Export Connector Do not use.


ACTION COMMENT

Import Connector Do not use.

Update Connector Do not use.

Refresh Schema Refreshes the cached schema. It is preferred to use the option
in the installation wizard instead, since that also updates sync
rules.

Search Connector Space Used to find objects and to Follow an object and its data
through the system.

Delete
The delete action is used for two different things.

The option Delete connector space only removes all data, but keep the configuration.
The option Delete Connector and connector space removes the data and the configuration. This option is used
when you do not want to connect to a forest anymore.
Both options sync all objects and update the metaverse objects. This action is a long running operation.
Configure Run Profiles
This option allows you to see the run profiles configured for a Connector.
Search Connector Space
The search connector space action is useful to find objects and troubleshoot data issues.

Start by selecting a scope. You can search based on data (RDN, DN, Anchor, Sub-Tree), or state of the object (all
other options).

If you for example do a Sub-Tree search, you get all objects in one OU.
From this grid you can select an object, select properties, and follow it from the source connector space, through
the metaverse, and to the target connector space.
Changing the AD DS account password
If you change the account password, the Synchronization Service will no longer be able to import/export changes
to on-premises AD. You may see the following:
The import/export step for the AD connector fails with "no-start-credentials" error.
Under Windows Event Viewer, the application event log contains an error with Event ID 6000 and message “The
management agent “contoso.com” failed to run because the credentials were invalid.”
To resolve the issue, update the AD DS user account using the following:
1. Start the Synchronization Service Manager (START → Synchronization Service).

2. Go to the Connectors tab.


3. Select the AD Connector which is configured to use the AD DS account.
4. Under Actions, select Properties.
5. In the pop-up dialog, select Connect to Active Directory Forest:
6. The Forest name indicates the corresponding on-prem AD.
7. The User name indicates the AD DS account used for synchronization.
8. Enter the new password of the AD DS account in the Password textbox

9. Click OK to save the new password and restart the Synchronization Service to remove the old password from
memory cache.
Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Sync Service Manager Metaverse Designer
1/17/2018 • 1 min to read • Edit Online

For most customers, there is nothing to configure here.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Sync Service Manager Metaverse Search
1/17/2018 • 1 min to read • Edit Online

The metaverse search tab is useful for troubleshooting data-related problems. In the top half, you can create a
query based on a combination of attributes. When you are satisfied with your query, click Search. The result is
visible in the bottom grid. You can select which columns should be visible with Column Settings.
In the search results, select an object and Properties to see the metaverse object properties.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Manage and customize Active Directory Federation
Services by using Azure AD Connect
1/17/2018 • 10 min to read • Edit Online

This article describes how to manage and customize Active Directory Federation Services (AD FS) by using Azure
Active Directory (Azure AD) Connect. It also includes other common AD FS tasks that you might need to do for a
complete configuration of an AD FS farm.

TOPIC WHAT IT COVERS

Manage AD FS

Repair the trust How to repair the federation trust with Office 365.

Federate with Azure AD using alternate login ID Configure federation using alternate login ID

Add an AD FS server How to expand an AD FS farm with an additional AD FS


server.

Add an AD FS Web Application Proxy server How to expand an AD FS farm with an additional Web
Application Proxy (WAP) server.

Add a federated domain How to add a federated domain.

Update the SSL certificate How to update the SSL certificate for an AD FS farm.

Customize AD FS

Add a custom company logo or illustration How to customize an AD FS sign-in page with a company
logo and illustration.

Add a sign-in description How to add a sign-in page description.

Modify AD FS claim rules How to modify AD FS claims for various federation scenarios.

Manage AD FS
You can perform various AD FS-related tasks in Azure AD Connect with minimal user intervention by using the
Azure AD Connect wizard. After you've finished installing Azure AD Connect by running the wizard, you can run
the wizard again to perform additional tasks.

Repair the trust


You can use Azure AD Connect to check the current health of the AD FS and Azure AD trust and take appropriate
actions to repair the trust. Follow these steps to repair your Azure AD and AD FS trust.
1. Select Repair AAD and ADFS Trust from the list of additional tasks.
2. On the Connect to Azure AD page, provide your global administrator credentials for Azure AD, and click
Next.

3. On the Remote access credentials page, enter the credentials for the domain administrator.
After you click Next, Azure AD Connect checks for certificate health and shows any issues.

The Ready to configure page shows the list of actions that will be performed to repair the trust.
4. Click Install to repair the trust.

NOTE
Azure AD Connect can only repair or act on certificates that are self-signed. Azure AD Connect can't repair third-party
certificates.

Federate with Azure AD using AlternateID


It is recommended that the on-premises User Principal Name(UPN) and the cloud User Principal Name are kept
the same. If the on-premises UPN uses a non-routable domain (ex. Contoso.local) or cannot be changed due to
local application dependencies, we recommend setting up alternate login ID. Alternate login ID allows you to
configure a sign-in experience where users can sign in with an attribute other than their UPN, such as mail. The
choice for User Principal Name in Azure AD Connect defaults to the userPrincipalName attribute in Active
Directory. If you choose any other attribute for User Principal Name and are federating using AD FS, then Azure
AD Connect will configure AD FS for alternate login ID. An example of choosing a different attribute for User
Principal Name is shown below:
Configuring alternate login ID for AD FS consists of two main steps:
1. Configure the right set of issuance claims: The issuance claim rules in the Azure AD relying party trust are
modified to use the selected UserPrincipalName attribute as the alternate ID of the user.
2. Enable alternate login ID in the AD FS configuration: The AD FS configuration is updated so that AD FS
can look up users in the appropriate forests using the alternate ID. This configuration is supported for AD FS
on Windows Server 2012 R2 (with KB2919355) or later. If the AD FS servers are 2012 R2, Azure AD
Connect checks for the presence of the required KB. If the KB is not detected, a warning will be displayed
after configuration completes, as shown below:
To rectify the configuration in case of missing KB, install the required KB2919355 and then repair the trust
using Repair AAD and AD FS Trust.

NOTE
For more information on alternateID and steps to manually configure, read Configuring Alternate Login ID

Add an AD FS server
NOTE
To add an AD FS server, Azure AD Connect requires the PFX certificate. Therefore, you can perform this operation only if you
configured the AD FS farm by using Azure AD Connect.

1. Select Deploy an additional Federation Server, and click Next.


2. On the Connect to Azure AD page, enter your global administrator credentials for Azure AD, and click
Next.

3. Provide the domain administrator credentials.


4. Azure AD Connect asks for the password of the PFX file that you provided while configuring your new AD
FS farm with Azure AD Connect. Click Enter Password to provide the password for the PFX file.
5. On the AD FS Servers page, enter the server name or IP address to be added to the AD FS farm.

6. Click Next, and go through the final Configure page. After Azure AD Connect has finished adding the
servers to the AD FS farm, you will be given the option to verify the connectivity.
Add an AD FS WAP server
NOTE
To add a WAP server, Azure AD Connect requires the PFX certificate. Therefore, you can only perform this operation if you
configured the AD FS farm by using Azure AD Connect.

1. Select Deploy Web Application Proxy from the list of available tasks.
2. Provide the Azure global administrator credentials.

3. On the Specify SSL certificate page, provide the password for the PFX file that you provided when you
configured the AD FS farm with Azure AD Connect.
4. Add the server to be added as a WAP server. Because the WAP server might not be joined to the domain,
the wizard asks for administrative credentials to the server being added.
5. On the Proxy trust credentials page, provide administrative credentials to configure the proxy trust and
access the primary server in the AD FS farm.

6. On the Ready to configure page, the wizard shows the list of actions that will be performed.
7. Click Install to finish the configuration. After the configuration is complete, the wizard gives you the option
to verify the connectivity to the servers. Click Verify to check connectivity.

Add a federated domain


It's easy to add a domain to be federated with Azure AD by using Azure AD Connect. Azure AD Connect adds the
domain for federation and modifies the claim rules to correctly reflect the issuer when you have multiple domains
federated with Azure AD.
1. To add a federated domain, select the task Add an additional Azure AD domain.

2. On the next page of the wizard, provide the global administrator credentials for Azure AD.

3. On the Remote access credentials page, provide the domain administrator credentials.
4. On the next page, the wizard provides a list of Azure AD domains that you can federate your on-premises
directory with. Choose the domain from the list.

After you choose the domain, the wizard provides you with appropriate information about further actions
that the wizard will take and the impact of the configuration. In some cases, if you select a domain that isn't
yet verified in Azure AD, the wizard provides you with information to help you verify the domain. See Add
your custom domain name to Azure Active Directory for more details.
5. Click Next. The Ready to configure page shows the list of actions that Azure AD Connect will perform.
Click Install to finish the configuration.

NOTE
Users from the added federated domain must be synchronized before they will be able to login to Azure AD.

AD FS customization
The following sections provide details about some of the common tasks that you might have to perform when you
customize your AD FS sign-in page.

Add a custom company logo or illustration


To change the logo of the company that's displayed on the Sign-in page, use the following Windows PowerShell
cmdlet and syntax.

NOTE
The recommended dimensions for the logo are 260 x 35 @ 96 dpi with a file size no greater than 10 KB.

Set-AdfsWebTheme -TargetName default -Logo @{path="c:\Contoso\logo.PNG"}

NOTE
The TargetName parameter is required. The default theme that's released with AD FS is named Default.

Add a sign-in description


To add a sign-in page description to the Sign-in page, use the following Windows PowerShell cmdlet and syntax.

Set-AdfsGlobalWebContent -SignInPageDescriptionText "<p>Sign-in to Contoso requires device registration. Click


<A href='http://fs1.contoso.com/deviceregistration/'>here</A> for more information.</p>"

Modify AD FS claim rules


AD FS supports a rich claim language that you can use to create custom claim rules. For more information, see The
Role of the Claim Rule Language.
The following sections describe how you can write custom rules for some scenarios that relate to Azure AD and AD
FS federation.
Immutable ID conditional on a value being present in the attribute
Azure AD Connect lets you specify an attribute to be used as a source anchor when objects are synced to Azure
AD. If the value in the custom attribute is not empty, you might want to issue an immutable ID claim.
For example, you might select ms-ds-consistencyguid as the attribute for the source anchor and issue
ImmutableID as ms-ds-consistencyguid in case the attribute has a value against it. If there's no value against
the attribute, issue objectGuid as the immutable ID. You can construct the set of custom claim rules as described
in the following section.
Rule 1: Query attributes

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> add(store = "Active Directory", types = ("http://contoso.com/ws/2016/02/identity/claims/objectguid",
"http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid"), query = "; objectGuid,ms-ds-
consistencyguid;{0}", param = c.Value);

In this rule, you're querying the values of ms-ds-consistencyguid and objectGuid for the user from Active
Directory. Change the store name to an appropriate store name in your AD FS deployment. Also change the claims
type to a proper claims type for your federation, as defined for objectGuid and ms-ds-consistencyguid.
Also, by using add and not issue, you avoid adding an outgoing issue for the entity, and can use the values as
intermediate values. You will issue the claim in a later rule after you establish which value to use as the immutable
ID.
Rule 2: Check if ms-ds-consistencyguid exists for the user

NOT EXISTS([Type == "http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid"])


=> add(Type = "urn:anandmsft:tmp/idflag", Value = "useguid");

This rule defines a temporary flag called idflag that is set to useguid if there's no ms-ds-consistencyguid
populated for the user. The logic behind this is the fact that AD FS doesn't allow empty claims. So when you add
claims http://contoso.com/ws/2016/02/identity/claims/objectguid and
http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid in Rule 1, you end up with an
msdsconsistencyguid claim only if the value is populated for the user. If it isn't populated, AD FS sees that it will
have an empty value and drops it immediately. All objects will have objectGuid, so that claim will always be there
after Rule 1 is executed.
Rule 3: Issue ms-ds-consistencyguid as immutable ID if it's present

c:[Type == "http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = c.Value);
This is an implicit Exist check. If the value for the claim exists, then issue that as the immutable ID. The previous
example uses the nameidentifier claim. You'll have to change this to the appropriate claim type for the
immutable ID in your environment.
Rule 4: Issue objectGuid as immutable ID if ms-ds-consistencyGuid is not present

c1:[Type == "urn:anandmsft:tmp/idflag", Value =~ "useguid"]


&& c2:[Type == "http://contoso.com/ws/2016/02/identity/claims/objectguid"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Value = c2.Value);

In this rule, you're simply checking the temporary flag idflag. You decide whether to issue the claim based on its
value.

NOTE
The sequence of these rules is important.

SSO with a subdomain UPN


You can add more than one domain to be federated by using Azure AD Connect, as described in Add a new
federated domain. You must modify the user principal name (UPN) claim so that the issuer ID corresponds to the
root domain and not the subdomain, because the federated root domain also covers the child.
By default, the claim rule for issuer ID is set as:

c:[Type
== “http://schemas.xmlsoap.org/claims/UPN“]

=> issue(Type = “http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid“, Value =


regexreplace(c.Value, “.+@(?<domain>.+)“, “http://${domain}/adfs/services/trust/“));

The default rule simply takes the UPN suffix and uses it in the issuer ID claim. For example, John is a user in
sub.contoso.com, and contoso.com is federated with Azure AD. John enters john@sub.contoso.com as the
username while signing in to Azure AD. The default issuer ID claim rule in AD FS handles it in the following
manner:
c:[Type
== “http://schemas.xmlsoap.org/claims/UPN“]

=> issue(Type = “http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid“, Value =


regexreplace(john@sub.contoso.com, “.+@(?<domain>.+)“, “http://${domain}/adfs/services/trust/“));

Claim value: http://sub.contoso.com/adfs/services/trust/


To have only the root domain in the issuer claim value, change the claim rule to match the following:

c:[Type == “http://schemas.xmlsoap.org/claims/UPN“]

=> issue(Type = “http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid“, Value =


regexreplace(c.Value, “^((.*)([.|@]))?(?<domain>[^.]*[.].*)$”, “http://${domain}/adfs/services/trust/“));

Next steps
Learn more about user sign-in options.
Federate multiple instances of Azure AD with single
instance of AD FS
12/11/2017 • 1 min to read • Edit Online

A single high available AD FS farm can federate multiple forests if they have 2-way trust between them. These
multiple forests may or may not correspond to the same Azure Active Directory. This article provides instructions
on how to configure federation between a single AD FS deployment and more than one forests that sync to
different Azure AD.

NOTE
Device writeback and automatic device join are not supported in this scenario.

NOTE
Azure AD Connect cannot be used to configure federation in this scenario as Azure AD Connect can configure federation for
domains in a single Azure AD.

Steps for federating AD FS with multiple Azure AD


Consider a domain contoso.com in Azure Active Directory contoso.onmicrosoft.com is already federated with the
AD FS on-premises installed in contoso.com on-premises Active Directory environment. Fabrikam.com is a domain
in fabrikam.onmicrosoft.com Azure Active Directory.

Step 1: Establish a two-way trust


For AD FS in contoso.com to be able to authenticate users in fabrikam.com, a two-way trust is needed between
contoso.com and fabrikam.com. Follow the guideline in this article to create the two-way trust.
Step 2: Modify contoso.com federation settings
The default issuer set for a single domain federated to AD FS is "http://ADFSServiceFQDN/adfs/services/trust", for
example, “http://fs.contoso.com/adfs/services/trust”. Azure Active Directory requires unique issuer for each
federated domain. Since the same AD FS is going to federate two domains, the issuer value needs to be modified
so that it is unique for each domain AD FS federates with Azure Active Directory.
On the AD FS server, open Azure AD PowerShell and perform the following steps:
Connect to the Azure Active Directory that contains the domain contoso.com Connect-MsolService Update the
federation settings for contoso.com Update-MsolFederatedDomain -DomainName contoso.com –
SupportMultipleDomain
Issuer in the domain federation setting will be changed to "http://contoso.com/adfs/services/trust" and an issuance
claim rule will be added for the Azure AD Relying Party Trust to issue the correct issuerId value based on the UPN
suffix.

Step 3: Federate fabrikam.com with AD FS


In Azure AD powershell session perform the following steps: Connect to Azure Active Directory that contains the
domain fabrikam.com

Connect-MsolService

Convert the fabrikam.com managed domain to federated:

Convert-MsolDomainToFederated -DomainName anandmsft.com -Verbose -SupportMultipleDomain

The above operation will federate the domain fabrikam.com with the same AD FS. You can verify the domain
settings by using Get-MsolDomainFederationSettings for both domains.

Next steps
Connect Active Directory with Azure Active Directory
Troubleshoot connectivity issues with Azure AD
Connect
1/17/2018 • 7 min to read • Edit Online

This article explains how connectivity between Azure AD Connect and Azure AD works and how to troubleshoot
connectivity issues. These issues are most likely to be seen in an environment with a proxy server.

Troubleshoot connectivity issues in the installation wizard


Azure AD Connect is using Modern Authentication (using the ADAL library) for authentication. The installation
wizard and the sync engine proper require machine.config to be properly configured since these two are .NET
applications.
In this article, we show how Fabrikam connects to Azure AD through its proxy. The proxy server is named
fabrikamproxy and is using port 8080.
First we need to make sure machine.config is correctly configured.

NOTE
In some non-Microsoft blogs, it is documented that changes should be made to miiserver.exe.config instead. However, this
file is overwritten on every upgrade so even if it works during initial install, the system stops working on first upgrade. For
that reason, the recommendation is to update machine.config instead.

The proxy server must also have the required URLs opened. The official list is documented in Office 365 URLs and
IP address ranges.
Of these URLs, the following table is the absolute bare minimum to be able to connect to Azure AD at all. This list
does not include any optional features, such as password writeback, or Azure AD Connect Health. It is documented
here to help in troubleshooting for the initial configuration.

URL PORT DESCRIPTION

mscrl.microsoft.com HTTP/80 Used to download CRL lists.

*.verisign.com HTTP/80 Used to download CRL lists.

*.entrust.com HTTP/80 Used to download CRL lists for MFA.


URL PORT DESCRIPTION

*.windows.net HTTPS/443 Used to sign in to Azure AD.

secure.aadcdn.microsoftonline-p.com HTTPS/443 Used for MFA.

*.microsoftonline.com HTTPS/443 Used to configure your Azure AD


directory and import/export data.

Errors in the wizard


The installation wizard is using two different security contexts. On the page Connect to Azure AD, it is using the
currently signed in user. On the page Configure, it is changing to the account running the service for the sync
engine. If there is an issue, it appears most likely already at the Connect to Azure AD page in the wizard since the
proxy configuration is global.
The following issues are the most common errors you encounter in the installation wizard.
The installation wizard has not been correctly configured
This error appears when the wizard itself cannot reach the proxy.

If you see this error, verify the machine.config has been correctly configured.
If that looks correct, follow the steps in Verify proxy connectivity to see if the issue is present outside the wizard
as well.
A Microsoft account is used
If you use a Microsoft account rather than a school or organization account, you see a generic error.

The MFA endpoint cannot be reached


This error appears if the endpoint https://secure.aadcdn.microsoftonline-p.com cannot be reached and your
global admin has MFA enabled.

If you see this error, verify that the endpoint secure.aadcdn.microsoftonline-p.com has been added to the
proxy.
The password cannot be verified
If the installation wizard is successful in connecting to Azure AD, but the password itself cannot be verified you see
this error:

Is the password a temporary password and must be changed? Is it actually the correct password? Try to sign in
to https://login.microsoftonline.com (on another computer than the Azure AD Connect server) and verify the
account is usable.
Verify proxy connectivity
To verify if the Azure AD Connect server has actual connectivity with the Proxy and Internet, use some PowerShell
to see if the proxy is allowing web requests or not. In a PowerShell prompt, run
Invoke-WebRequest -Uri https://adminwebservice.microsoftonline.com/ProvisioningService.svc . (Technically the first
call is to https://login.microsoftonline.com and this URI works as well, but the other URI is faster to respond.)
PowerShell uses the configuration in machine.config to contact the proxy. The settings in winhttp/netsh should not
impact these cmdlets.
If the proxy is correctly configured, you should get a success status:

If you receive Unable to connect to the remote server, then PowerShell is trying to make a direct call without
using the proxy or DNS is not correctly configured. Make sure the machine.config file is correctly configured.

If the proxy is not correctly configured, you get an error:

ERROR ERROR TEXT COMMENT

403 Forbidden The proxy has not been opened for the
requested URL. Revisit the proxy
configuration and make sure the URLs
have been opened.

407 Proxy Authentication Required The proxy server required a sign-in and
none was provided. If your proxy server
requires authentication, make sure to
have this setting configured in the
machine.config. Also make sure you are
using domain accounts for the user
running the wizard and for the service
account.

Proxy idle timeout setting


When Azure AD Connect sends an export request to Azure AD, Azure AD can take up to 5 minutes to process the
request before generating a response. This can happen especially if there are a number of group objects with large
group memberships included in the same export request. Ensure the Proxy idle timeout is configured to be greater
than 5 minutes. Otherwise, intermittent connectivity issue with Azure AD may be observed on the Azure AD
Connect server.

The communication pattern between Azure AD Connect and Azure


AD
If you have followed all these preceding steps and still cannot connect, you might at this point start looking at
network logs. This section is documenting a normal and successful connectivity pattern. It is also listing common
red herrings that can be ignored when you are reading the network logs.
There are calls to https://dc.services.visualstudio.com. It is not required to have this URL open in the proxy for
the installation to succeed and these calls can be ignored.
You see that dns resolution lists the actual hosts to be in the DNS name space nsatc.net and other namespaces
not under microsoftonline.com. However, there are not any web service requests on the actual server names
and you do not have to add these URLs to the proxy.
The endpoints adminwebservice and provisioningapi are discovery endpoints and used to find the actual
endpoint to use. These endpoints are different depending on your region.
Reference proxy logs
Here is a dump from an actual proxy log and the installation wizard page from where it was taken (duplicate
entries to the same endpoint have been removed). This section can be used as a reference for your own proxy and
network logs. The actual endpoints might be different in your environment (in particular those URLs in italic).
Connect to Azure AD

TIME URL

1/11/2016 8:31 connect://login.microsoftonline.com:443

1/11/2016 8:31 connect://adminwebservice.microsoftonline.com:443

1/11/2016 8:32 connect://bba800-anchor.microsoftonline.com:443

1/11/2016 8:32 connect://login.microsoftonline.com:443

1/11/2016 8:33 connect://provisioningapi.microsoftonline.com:443

1/11/2016 8:33 connect://bwsc02-relay.microsoftonline.com:443

Configure

TIME URL

1/11/2016 8:43 connect://login.microsoftonline.com:443

1/11/2016 8:43 connect://bba800-anchor.microsoftonline.com:443

1/11/2016 8:43 connect://login.microsoftonline.com:443

1/11/2016 8:44 connect://adminwebservice.microsoftonline.com:443

1/11/2016 8:44 connect://bba900-anchor.microsoftonline.com:443

1/11/2016 8:44 connect://login.microsoftonline.com:443

1/11/2016 8:44 connect://adminwebservice.microsoftonline.com:443

1/11/2016 8:44 connect://bba800-anchor.microsoftonline.com:443


TIME URL

1/11/2016 8:44 connect://login.microsoftonline.com:443

1/11/2016 8:46 connect://provisioningapi.microsoftonline.com:443

1/11/2016 8:46 connect://bwsc02-relay.microsoftonline.com:443

Initial Sync

TIME URL

1/11/2016 8:48 connect://login.windows.net:443

1/11/2016 8:49 connect://adminwebservice.microsoftonline.com:443

1/11/2016 8:49 connect://bba900-anchor.microsoftonline.com:443

1/11/2016 8:49 connect://bba800-anchor.microsoftonline.com:443

Authentication errors
This section covers errors that can be returned from ADAL (the authentication library used by Azure AD Connect)
and PowerShell. The error explained should help you in understand your next steps.
Invalid Grant
Invalid username or password. For more information, see The password cannot be verified.
Unknown User Type
Your Azure AD directory cannot be found or resolved. Maybe you try to login with a username in an unverified
domain?
User Realm Discovery Failed
Network or proxy configuration issues. The network cannot be reached. See Troubleshoot connectivity issues in
the installation wizard.
User Password Expired
Your credentials have expired. Change your password.
AuthorizationFailure
Unknown issue.
Authentication Cancelled
The multi-factor authentication (MFA) challenge was cancelled.
ConnectToMSOnline
Authentication was successful, but Azure AD PowerShell has an authentication problem.
AzureRoleMissing
Authentication was successful. You are not a global administrator.
PrivilegedIdentityManagement
Authentication was successful. Privileged identity management has been enabled and you are currently not a
global administrator. For more information, see Privileged Identity Management.
CompanyInfoUnavailable
Authentication was successful. Could not retrieve company information from Azure AD.
RetrieveDomains
Authentication was successful. Could not retrieve domain information from Azure AD.
Unexpected exception
Shown as Unexpected error in the installation wizard. Can happen if you try to use a Microsoft Account rather
than a school or organization account.

Troubleshooting steps for previous releases.


With releases starting with build number 1.1.105.0 (released February 2016), the sign-in assistant was retired. This
section and the configuration should no longer be required, but is kept as reference.
For the single-sign in assistant to work, winhttp must be configured. This configuration can be done with netsh.

The Sign-in assistant has not been correctly configured


This error appears when the Sign-in assistant cannot reach the proxy or the proxy is not allowing the request.

If you see this error, look at the proxy configuration in netsh and verify it is correct.

If that looks correct, follow the steps in Verify proxy connectivity to see if the issue is present outside the wizard
as well.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Troubleshooting Errors during synchronization
1/17/2018 • 13 min to read • Edit Online

Errors could occur when identity data is synchronized from Windows Server Active Directory (AD DS) to Azure
Active Directory (Azure AD). This article provides an overview of different types of sync errors, some of the possible
scenarios that cause those errors and potential ways to fix the errors. This article includes the common error types
and may not cover all the possible errors.
This article assumes the reader is familiar with the underlying design concepts of Azure AD and Azure AD Connect.
With the latest version of Azure AD Connect (August 2016 or higher), a report of Synchronization Errors is available
in the Azure Portal as part of Azure AD Connect Health for sync.
Starting September 1, 2016 Azure Active Directory Duplicate Attribute Resiliency feature will be enabled by default
for all the new Azure Active Directory Tenants. This feature will be automatically enabled for existing tenants in the
upcoming months.
Azure AD Connect performs 3 types of operations from the directories it keeps in sync: Import, Synchronization
and Export. Errors can take place in all the operations. This article mainly focuses on errors during Export to Azure
AD.

Errors during Export to Azure AD


Following section describes different types of synchronization errors that can occur during the export operation to
Azure AD using the Azure AD connector. This connector can be identified by the name format being
"contoso.onmicrosoft.com". Errors during Export to Azure AD indicate that the operation (add, update, delete etc.)
attempted by Azure AD Connect (Sync Engine) on Azure Active Directory failed.

Data Mismatch Errors


InvalidSoftMatch
Description
When Azure AD Connect (sync engine) instructs Azure Active Directory to add or update objects, Azure AD
matches the incoming object using the sourceAnchor attribute to the immutableId attribute of objects in
Azure AD. This match is called a Hard Match.
When Azure AD does not find any object that matches the immutableId attribute with the sourceAnchor
attribute of the incoming object, before provisioning a new object, it falls back to use the ProxyAddresses and
UserPrincipalName attributes to find a match. This match is called a Soft Match. The Soft Match is designed to
match objects already present in Azure AD (that are sourced in Azure AD) with the new objects being
added/updated during synchronization that represent the same entity (users, groups) on premises.
InvalidSoftMatch error occurs when the hard match does not find any matching object AND soft match finds
a matching object but that object has a different value of immutableId than the incoming object's SourceAnchor,
suggesting that the matching object was synchronized with another object from on premises Active Directory.
In other words, in order for the soft match to work, the object to be soft-matched with should not have any value
for the immutableId. If any object with immutableId set with a value is failing the hard-match but satisfying the
soft-match criteria, the operation would result in an InvalidSoftMatch synchronization error.
Azure Active Directory schema does not allow two or more objects to have the same value of the following
attributes. (This is not an exhaustive list.)
ProxyAddresses
UserPrincipalName
onPremisesSecurityIdentifier
ObjectId

NOTE
Azure AD Attribute Duplicate Attribute Resiliency feature is also being rolled out as the default behavior of Azure Active
Directory. This will reduce the number of synchronization errors seen by Azure AD Connect (as well as other sync clients) by
making Azure AD more resilient in the way it handles duplicated ProxyAddresses and UserPrincipalName attributes present in
on premises AD environments. This feature does not fix the duplication errors. So the data still needs to be fixed. But it allows
provisioning of new objects which are otherwise blocked from being provisioned due to duplicated values in Azure AD. This
will also reduce the number of synchronization errors returned to the synchronization client. If this feature is enabled for your
Tenant, you will not see the InvalidSoftMatch synchronization errors seen during provisioning of new objects.

Example Scenarios for InvalidSoftMatch


1. Two or more objects with the same value of ProxyAddresses attribute exists in on premises Active Directory.
Only one is getting provisioned in Azure AD.
2. Two or more objects with the same value of userPrincipalName exists in on premises Active Directory. Only one
is getting provisioned in Azure AD.
3. An object was added in the on premises Active Directory with the same value of ProxyAddresses attribute as
that of an existing object in Azure Active Directory. The object added on premises is not getting provisioned in
Azure Active Directory.
4. An object was added in on premises Active Directory with the same value of userPrincipalName attribute as that
of an account in Azure Active Directory. The object is not getting provisioned in Azure Active Directory.
5. A synced account was moved from Forest A to Forest B. Azure AD Connect (sync engine) was using ObjectGUID
attribute to compute the SourceAnchor. After the forest move, the value of the SourceAnchor is different. The
new object (from Forest B) is failing to sync with the existing object in Azure AD.
6. A synced object got accidentally deleted from on premises Active Directory and a new object was created in
Active Directory for the same entity (such as user) without deleting the account in Azure Active Directory. The
new account fails to sync with the existing Azure AD object.
7. Azure AD Connect was uninstalled and re-installed. During the re-installation, a different attribute was chosen as
the SourceAnchor. All the objects that had previously synced stopped syncing with InvalidSoftMatch error.
Example case:
1. Bob Smith is a synced user in Azure Active Directory from on premises Active Directory of contoso.com
2. Bob Smith's UserPrincipalName is set as bobs@contoso.com.
3. "abcdefghijklmnopqrstuv==" is the SourceAnchor calculated by Azure AD Connect using Bob Smith's
objectGUID from on premises Active Directory, which is the immutableId for Bob Smith in Azure Active
Directory.
4. Bob also has following values for the proxyAddresses attribute:
smtp:bobs@contoso.com
smtp:bob.smith@contoso.com
smtp:bob@contoso.com
5. A new user, Bob Taylor, is added to the on premises Active Directory.
6. Bob Taylor's UserPrincipalName is set as bobt@contoso.com.
7. "abcdefghijkl0123456789=="" is the sourceAnchor calculated by Azure AD Connect using Bob Taylor's
objectGUID from on premises Active Directory. Bob Taylor's object has NOT synced to Azure Active Directory
yet.
8. Bob Taylor has the following values for the proxyAddresses attribute
smtp:bobt@contoso.com
smtp:bob.taylor@contoso.com
smtp:bob@contoso.com
9. During sync, Azure AD Connect will recognize the addition of Bob Taylor in on premises Active Directory and
ask Azure AD to make the same change.
10. Azure AD will first perform hard match. That is, it will search if there is any object with the immutableId equal to
"abcdefghijkl0123456789==". Hard Match will fail as no other object in Azure AD will have that immutableId.
11. Azure AD will then attempt to soft-match Bob Taylor. That is, it will search if there is any object with
proxyAddresses equal to the three values, including smtp:bob@contoso.com
12. Azure AD will find Bob Smith's object to match the soft-match criteria. But this object has the value of
immutableId = "abcdefghijklmnopqrstuv==". which indicates this object was synced from another object from
on premises Active Directory. Thus, Azure AD cannot soft-match these objects and results in an
InvalidSoftMatch sync error.
How to fix InvalidSoftMatch error
The most common reason for the InvalidSoftMatch error is two objects with different SourceAnchor (immutableId)
have the same value for the ProxyAddresses and/or UserPrincipalName attributes, which are used during the soft-
match process on Azure AD. In order to fix the Invalid Soft Match
1. Identify the duplicated proxyAddresses, userPrincipalName or other attribute value that's causing the error. Also
identify which two (or more) objects are involved in the conflict. The report generated by Azure AD Connect
Health for sync can help you identify the two objects.
2. Identify which object should continue to have the duplicated value and which object should not.
3. Remove the duplicated value from the object that should NOT have that value. Note that you should make the
change in the directory where the object is sourced from. In some cases, you may need to delete one of the
objects in conflict.
4. If you made the change in the on premises AD, let Azure AD Connect sync the change.
Note that Sync error report within Azure AD Connect Health for sync is updated every 30 minutes and includes the
errors from the latest synchronization attempt.

NOTE
ImmutableId, by definition, should not change in the lifetime of the object. If Azure AD Connect was not configured with
some of the scenarios in mind from the above list, you could end up in a situation where Azure AD Connect calculates a
different value of the SourceAnchor for the AD object that represents the same entity (same user/group/contact etc) that has
an existing Azure AD Object that you wish to continue using.
Related Articles
Duplicate or invalid attributes prevent directory synchronization in Office 365
ObjectTypeMismatch
Description
When Azure AD attempts to soft match two objects, it is possible that two objects of different "object type" (such as
User, Group, Contact etc.) have the same values for the attributes used to perform the soft match. As duplication of
these attributes is not permitted in Azure AD, the operation can result in "ObjectTypeMismatch" synchronization
error.
Example Scenarios for ObjectTypeMismatch error
A mail enabled security group is created in Office 365. Admin adds a new user or contact in on premises AD
(that's not synchronized to Azure AD yet) with the same value for the ProxyAddresses attribute as that of the
Office 365 group.
Example case
1. Admin creates a new mail enabled security group in Office 365 for the Tax department and provides an email
address as tax@contoso.com. This assigns the ProxyAddresses attribute for this group with the value of
smtp:tax@contoso.com
2. A new user joins Contoso.com and an account is created for the user on premises with the proxyAddress as
smtp:tax@contoso.com
3. When Azure AD Connect will sync the new user account, it will get the "ObjectTypeMismatch" error.
How to fix ObjectTypeMismatch error
The most common reason for the ObjectTypeMismatch error is two objects of different type (User, Group, Contact
etc.) have the same value for the ProxyAddresses attribute. In order to fix the ObjectTypeMismatch:
1. Identify the duplicated proxyAddresses (or other attribute) value that's causing the error. Also identify which two
(or more) objects are involved in the conflict. The report generated by Azure AD Connect Health for sync can
help you identify the two objects.
2. Identify which object should continue to have the duplicated value and which object should not.
3. Remove the duplicated value from the object that should NOT have that value. Note that you should make the
change in the directory where the object is sourced from. In some cases, you may need to delete one of the
objects in conflict.
4. If you made the change in the on premises AD, let Azure AD Connect sync the change. Sync error report within
Azure AD Connect Health for sync gets updated every 30 minutes and includes the errors from the latest
synchronization attempt.

Duplicate Attributes
AttributeValueMustBeUnique
Description
Azure Active Directory schema does not allow two or more objects to have the same value of the following
attributes. That is each object in Azure AD is forced to have a unique value of these attributes at a given instance.
ProxyAddresses
UserPrincipalName
If Azure AD Connect attempts to add a new object or update an existing object with a value for the above attributes
that is already assigned to another object in Azure Active Directory, the operation results in the
"AttributeValueMustBeUnique" sync error.
Possible Scenarios:
1. Duplicate value is assigned to an already synced object, which conflicts with another synced object.
Example case:
1. Bob Smith is a synced user in Azure Active Directory from on premises Active Directory of contoso.com
2. Bob Smith's UserPrincipalName on premises is set as bobs@contoso.com.
3. Bob also has following values for the proxyAddresses attribute:
smtp:bobs@contoso.com
smtp:bob.smith@contoso.com
smtp:bob@contoso.com
4. A new user, Bob Taylor, is added to the on premises Active Directory.
5. Bob Taylor's UserPrincipalName is set as bobt@contoso.com.
6. Bob Taylor has the following values for the ProxyAddresses attribute i. smtp:bobt@contoso.com ii.
smtp:bob.taylor@contoso.com
7. Bob Taylor's object is synchronized with Azure AD successfully.
8. Admin decided to update Bob Taylor's ProxyAddresses attribute with the following value: i.
smtp:bob@contoso.com
9. Azure AD will attempt to update Bob Taylor's object in Azure AD with the above value, but that operation will fail
as that ProxyAddresses value is already assigned to Bob Smith, resulting in "AttributeValueMustBeUnique"
error.
How to fix AttributeValueMustBeUnique error
The most common reason for the AttributeValueMustBeUnique error is two objects with different SourceAnchor
(immutableId) have the same value for the ProxyAddresses and/or UserPrincipalName attributes. In order to fix
AttributeValueMustBeUnique error
1. Identify the duplicated proxyAddresses, userPrincipalName or other attribute value that's causing the error. Also
identify which two (or more) objects are involved in the conflict. The report generated by Azure AD Connect
Health for sync can help you identify the two objects.
2. Identify which object should continue to have the duplicated value and which object should not.
3. Remove the duplicated value from the object that should NOT have that value. Note that you should make the
change in the directory where the object is sourced from. In some cases, you may need to delete one of the
objects in conflict.
4. If you made the change in the on premises AD, let Azure AD Connect sync the change for the error to get fixed.
Related Articles
-Duplicate or invalid attributes prevent directory synchronization in Office 365

Data Validation Failures


IdentityDataValidationFailed
Description
Azure Active Directory enforces various restrictions on the data itself before allowing that data to be written into
the directory. This is to ensure that end users get the best possible experiences while using the applications that
depend on this data.
Scenarios
a. The UserPrincipalName attribute value has invalid/unsupported characters. b. The UserPrincipalName attribute
does not follow the required format.
How to fix IdentityDataValidationFailed error
a. Ensure that the userPrincipalName attribute has supported characters and required format.
Related Articles
Prepare to provision users through directory synchronization to Office 365
FederatedDomainChangeError
Description
This is a specific case that results in a "FederatedDomainChangeError" sync error when the suffix of a user's
UserPrincipalName is changed from one federated domain to another federated domain.
Scenarios
For a synchronized user, the UserPrincipalName suffix was changed from one federated domain to another
federated domain on premises. For example, UserPrincipalName = bob@contoso.com was changed to
UserPrincipalName = bob@fabrikam.com.
Example
1. Bob Smith, an account for Contoso.com, gets added as a new user in Active Directory with the
UserPrincipalName bob@contoso.com
2. Bob moves to a different division of Contoso.com called Fabrikam.com and his UserPrincipalName is changed
to bob@fabrikam.com
3. Both contoso.com and fabrikam.com domains are federated domains with Azure Active Directory.
4. Bob's userPrincipalName does not get updated and results in a "FederatedDomainChangeError" sync error.
How to fix
If a user's UserPrincipalName suffix was updated from bob@contoso.com to bob@fabrikam.com, where both
contoso.com and fabrikam.com are federated domains, then follow these steps to fix the sync error
1. Update the user's UserPrincipalName in Azure AD from bob@contoso.com to bob@contoso.onmicrosoft.com.
You can use the following PowerShell command with the Azure AD PowerShell Module:
Set-MsolUserPrincipalName -UserPrincipalName bob@contoso.com -NewUserPrincipalName
bob@contoso.onmicrosoft.com
2. Allow the next sync cycle to attempt synchronization. This time synchronization will be successful and it will
update the UserPrincipalName of Bob to bob@fabrikam.com as expected.
Related Articles
Changes aren't synced by the Azure Active Directory Sync tool after you change the UPN of a user account to
use a different federated domain

LargeObject
Description
When an attribute exceeds the allowed size limit, length limit or count limit set by Azure Active Directory schema,
the synchronization operation results in the LargeObject or ExceededAllowedLength sync error. Typically this
error occurs for the following attributes
userCertificate
userSMIMECertificate
thumbnailPhoto
proxyAddresses
Possible Scenarios
1. Bob's userCertificate attribute is storing too many certificates assigned to Bob. These may include older, expired
certificates. The hard limit is 15 certificates. For more information on how to handle LargeObject errors with
userCertificate attribute, please refer to article Handling LargeObject errors caused by userCertificate attribute.
2. Bob's userSMIMECertificate attribute is storing too many certificates assigned to Bob. These may include older,
expired certificates. The hard limit is 15 certificates.
3. Bob's thumbnailPhoto set in Active Directory is too large to be synced in Azure AD.
4. During automatic population of the ProxyAddresses attribute in Active Directory, an object has too many
ProxyAddresses assigned.
How to fix
1. Ensure that the attribute causing the error is within the allowed limitation.
Related links
Locate Active Directory Objects in Active Directory Administrative Center
How to query Azure Active Directory for an object using Azure Active Directory PowerShell
Troubleshoot an object that is not synchronizing to
Azure AD
2/21/2018 • 7 min to read • Edit Online

If an object is not synchronizing as expected to Azure AD, then it can be because of several reasons. If you have
received an error email from Azure AD or you see the error in Azure AD Connect Health, then read troubleshoot
export errors instead. But if you are troubleshooting a problem where the object is not in Azure AD, then this topic
is for you. It describes how to find errors in the on-premises component Azure AD Connect sync.

IMPORTANT
For Azure Active Directory (AAD) Connect deployment with version or higher, use the troubleshooting task in the wizard to
troubleshoot object synchronization issues.

To find the errors, you are going to look at a few different places in the following order:
1. The operation logs for finding errors identified by the sync engine during import and synchronization.
2. The connector space for finding missing objects and synchronization errors.
3. The metaverse for finding data-related problems.
Start Synchronization Service Manager before you begin these steps.

Operations
The operations tab in the Synchronization Service Manager is where you should start your troubleshooting. The
operations tab shows the results from the most recent operations.

The top half shows all runs in chronological order. By default, the operations log keeps information about the last
seven days, but this setting can be changed with the scheduler. You want to look for any run that does not show a
success status. You can change the sorting by clicking the headers.
The Status column is the most important information and shows the most severe problem for a run. Here is a
quick summary of the most common statuses in order of priority to investigate (where * indicate several possible
error strings).

STATUS COMMENT

stopped-* The run could not complete. For example, if the remote
system is down and cannot be contacted.

stopped-error-limit There are more than 5,000 errors. The run was automatically
stopped due to the large number of errors.

completed-*-errors The run completed, but there are errors (fewer than 5,000)
that should be investigated.

completed-*-warnings The run completed, but some data is not in the expected
state. If you have errors, then this message is usually only a
symptom. Until you have addressed errors, you should not
investigate warnings.

success No issues.

When you select a row, the bottom updates to show the details of that run. To the far left of the bottom, you might
have a list saying Step #. This list only appears if you have multiple domains in your forest where each domain is
represented by a step. The domain name can be found under the heading Partition. Under Synchronization
Statistics, you can find more information about the number of changes that were processed. You can click the
links to get a list of the changed objects. If you have objects with errors, those errors show up under
Synchronization Errors.
Troubleshoot errors in operations tab

When you have errors, both the object in error and the error itself are links that provide more information.
Start by clicking the error string (sync-rule-error-function-triggered in the picture). You are first presented with
an overview of the object. To see the actual error, click the button Stack Trace. This trace provides debug level
information for the error.
You can right-click in the call stack information box, choose select all, and copy. You can then copy the stack
and look at the error in your favorite editor, such as Notepad.
If the error is from SyncRulesEngine, then the call stack information first has a list of all attributes on the
object. Scroll down until you see the heading InnerException =>.
The line after shows the error. In the picture above, the error is from a custom Sync Rule Fabrikam created.
If the error itself does not give enough information, then it is time to look at the data itself. You can click the link
with the object identifier and continue troubleshooting the connector space imported object.

Connector space object properties


If you do not have any errors found in the operations tab, then the next step is to follow the connector space object
from Active Directory, to the metaverse, and to Azure AD. In this path, you should find where the problem is.
Search for an object in the CS
In Synchronization Service Manager, click Connectors, select the Active Directory Connector, and Search
Connector Space.
In Scope, select RDN (when you want to search on the CN attribute) or DN or anchor (when you want to search
on the distinguishedName attribute). Enter a value and click Search.

If you do not find the object you are looking for, then it might have been filtered with domain-based filtering or
OU-based filtering. Read the configure filtering topic to verify that the filtering is configured as expected.
Another useful search is to select the Azure AD Connector, in Scope select Pending Import, and select the Add
checkbox. This search gives you all synchronized objects in Azure AD that cannot be associated with an on-
premises object.

Those objects have been created by another sync engine or a sync engine with a different filtering configuration.
This view is a list of orphan objects no longer managed. You should review this list and consider removing these
objects using the Azure AD PowerShell cmdlets.
CS Import
When you open a cs object, there are several tabs at the top. The Import tab shows the data that is staged after an
import.

The Old Value shows what currently is stored in Connect and the New Value what has been received from the
source system and has not been applied yet. If there is an error on the object, then changes are not processed.
Error

The Synchronization Error tab is only visible if there is a problem with the object. For more information, see
troubleshoot synchronization errors.
CS Lineage
The lineage tab shows how the connector space object is related to the metaverse object. You can see when the
Connector last imported a change from the connected system and which rules applied to populate data in the
metaverse.
In the Action column, you can see there is one Inbound sync rule with the action Provision. That indicates that as
long as this connector space object is present, the metaverse object remains. If the list of sync rules instead shows
a sync rule with direction Outbound and Provision, it indicates that this object is deleted when the metaverse
object is deleted.

You can also see in the PasswordSync column that the inbound connector space can contribute changes to the
password since one sync rule has the value True. This password is then sent to Azure AD through the outbound
rule.
From the lineage tab, you can get to the metaverse by clicking Metaverse Object Properties.
At the bottom of all tabs are two buttons: Preview and Log.
Preview
The preview page is used to synchronize one single object. It is useful if you are troubleshooting some custom
sync rules and want to see the effect of a change on a single object. You can select between Full sync and Delta
sync. You can also select between Generate Preview, which only keeps the change in memory, and Commit
Preview, which updated the metaverse and stages all changes to target connector spaces.
You can inspect the object and which rule applied for a particular attribute flow.

Log
The Log page is used to see the password sync status and history. For more information, see Troubleshoot
password synchronization.

Metaverse object properties


It is usually better to start searching from the source Active Directory connector space. But you can also start
searching from the metaverse.
Search for an object in the MV
In Synchronization Service Manager, click Metaverse Search. Create a query you know finds the user. You can
search for common attributes, such as accountName (sAMAccountName) and userPrincipalName. For more
information, see Metaverse search.

In the Search Results window, click the object.


If you did not find the object, then it has not yet reached the metaverse. Continue to search for the object in the
Active Directory connector space. There could be an error from synchronization that is blocking the object from
coming to the metaverse or there might be a filter applied.
MV Attributes
On the attributes tab, you can see the values and which Connector contributed it.

If an object is not synchronizing, then look at the following attributes in the metaverse:
Is the attribute cloudFiltered present and set to true? If it is, then it has been filtered according to the steps in
attribute based filtering.
Is the attribute sourceAnchor present? If not, do you have an account-resource forest topology? If an object is
identified as a linked mailbox (the attribute msExchRecipientTypeDetails has the value 2), then the
sourceAnchor is contributed by the forest with an enabled Active Directory account. Make sure the master
account has been imported and synchronized correctly. The master account must be listed in the connectors for
the object.
MV Connectors
The Connectors tab shows all connector spaces that have a representation of the object.

You should have a connector to:


Each Active Directory forest the user is represented in. This representation can include foreignSecurityPrincipals
and Contact objects.
A connector in Azure AD.
If you are missing the connector to Azure AD, then read MV attributes to verify the criteria for being provisioned to
Azure AD.
This tab also allows you to navigate to the connector space object. Select a row and click Properties.

Next steps
Learn more about the Azure AD Connect sync configuration.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Troubleshoot object synchronization with Azure AD
Connect sync
2/16/2018 • 2 min to read • Edit Online

This document provides steps for how to troubleshoot issues with object synchronization using the
troubleshooting task.

Troubleshooting task
For Azure Active Directory (AAD) Connect deployment with version or higher, use the troubleshooting task in the
wizard to troubleshoot object synchronization issues. For earlier versions, please troubleshoot manually as
described here.
Run the troubleshooting task in the wizard
To run the troubleshooting task in the wizard, perform the following steps:
1. Open a new Windows PowerShell session on your Azure AD Connect server with the Run as Administrator
option.
2. Run Set-ExecutionPolicy RemoteSigned or Set-ExecutionPolicy Unrestricted .
3. Start the Azure AD Connect wizard.
4. Navigate to the Additional Tasks page, select Troubleshoot, and click Next.
5. On the Troubleshooting page, click Launch to start the troubleshooting menu in PowerShell.
6. In the main menu, select Troubleshoot Object Synchronization.
Troubleshooting Input Parameters
The following input parameters are needed by the troubleshooting task:
1. Object Distinguished Name – This is the distinguished name of the object that needs troubleshooting
2. AD Connector Name – This is the name of the AD forest where the above object resides.
3. Azure AD tenant global administrator credentials

Understand the results of the troubleshooting task


The troubleshooting task performs the following checks:
1. Detect UPN mismatch if the object is synced to Azure Active Directory
2. Check if object is filtered due to domain filtering
3. Check if object is filtered due to OU filtering
The rest of this section describes specific results that are returned by the task. In each case, the task provides an
analysis followed by recommended actions to resolve the issue.

Detect UPN mismatch if object is synced to Azure Active Directory


UPN Suffix is NOT verified with Azure AD Tenant
When UserPrincipalName (UPN)/Alternate Login ID suffix is not verified with the Azure AD Tenant, then Azure
Active Directory replaces the UPN suffixes with the default domain name "onmicrosoft.com".

Changing UPN Suffix from one federated domain to another federated domain
Azure Active Directory does not allow the synchronization of UserPrincipalName (UPN)/Alternate Login ID suffix
change from one federated domain to another federated domain. This applies to domains, that are verified with the
Azure AD Tenant and have the Authentication Type as Federated.

Azure AD Tenant DirSync Feature ‘SynchronizeUpnForManagedUsers’ is disabled


When the Azure AD Tenant DirSync Feature ‘SynchronizeUpnForManagedUsers’ is disabled, Azure Active Directory
does not allow synchronization updates to UserPrincipalName/Alternate Login ID for licensed user accounts with
managed authentication.
Object is filtered due to domain filtering
Domain is not configured to sync
Object is out of scope due to domain not being configured. In the example below, the object is out of sync scope as
the domain that it belongs to is filtered from synchronization.

Domain is configured to sync but is missing run profiles/run steps


Object is out of scope as the domain is missing run profiles/run steps. In the example below, the object is out of
sync scope as the domain that it belongs to is missing run steps for the Full Import run profile.

Object is filtered due to OU filtering


The object is out of sync scope due to OU filtering configuration. In the example below, the object belongs to
OU=NoSync,DC=bvtadwbackdc,DC=com. This OU is not included in sync scope.

HTML Report
In addition to analyzing the object, the troubleshooting task also generates an HTML report that has everything
known about the object. This HTML report can be shared with support team to do further troubleshooting, if
needed.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Troubleshoot password synchronization with Azure
AD Connect sync
1/17/2018 • 12 min to read • Edit Online

This topic provides steps for how to troubleshoot issues with password synchronization. If passwords are not
synchronizing as expected, it can be either for a subset of users or for all users.
For Azure Active Directory (Azure AD) Connect deployment with version 1.1.614.0 or after, use the troubleshooting
task in the wizard to troubleshoot password synchronization issues:
If you have an issue where no passwords are synchronized, refer to the No passwords are synchronized:
troubleshoot by using the troubleshooting task section.
If you have an issue with individual objects, refer to the One object is not synchronizing passwords:
troubleshoot by using the troubleshooting task section.
For deployment with version 1.1.524.0 or later, there is a diagnostic cmdlet that you can use to troubleshoot
password synchronization issues:
If you have an issue where no passwords are synchronized, refer to the No passwords are synchronized:
troubleshoot by using the diagnostic cmdlet section.
If you have an issue with individual objects, refer to the One object is not synchronizing passwords:
troubleshoot by using the diagnostic cmdlet section.
For older versions of Azure AD Connect deployment:
If you have an issue where no passwords are synchronized, refer to the No passwords are synchronized:
manual troubleshooting steps section.
If you have an issue with individual objects, refer to the One object is not synchronizing passwords: manual
troubleshooting steps section.

No passwords are synchronized: troubleshoot by using the


troubleshooting task
You can use the troubleshooting task to figure out why no passwords are synchronized.

NOTE
The troubleshooting task is available only for Azure AD Connect version 1.1.614.0 or later.

Run the troubleshooting task


To troubleshoot issues where no passwords are synchronized:
1. Open a new Windows PowerShell session on your Azure AD Connect server with the Run as
Administrator option.
2. Run Set-ExecutionPolicy RemoteSigned or Set-ExecutionPolicy Unrestricted .
3. Start the Azure AD Connect wizard.
4. Navigate to the Additional Tasks page, select Troubleshoot, and click Next.
5. On the Troubleshooting page, click Launch to start the troubleshooting menu in PowerShell.
6. In the main menu, select Troubleshoot Password Synchronization.
7. In the sub menu, select Password Synchronization does not work at all.
Understand the results of the troubleshooting task
The troubleshooting task performs the following checks:
Validates that the password synchronization feature is enabled for your Azure AD tenant.
Validates that the Azure AD Connect server is not in staging mode.
For each existing on-premises Active Directory connector (which corresponds to an existing Active Directory
forest):
Validates that the password synchronization feature is enabled.
Searches for password synchronization heartbeat events in the Windows Application Event logs.
For each Active Directory domain under the on-premises Active Directory connector:
Validates that the domain is reachable from the Azure AD Connect server.
Validates that the Active Directory Domain Services (AD DS) accounts used by the on-
premises Active Directory connector has the correct username, password, and permissions
required for password synchronization.
The following diagram illustrates the results of the cmdlet for a single-domain, on-premises Active Directory
topology:

The rest of this section describes specific results that are returned by the task and corresponding issues.
Password synchronization feature isn't enabled
If you haven't enabled password synchronization by using the Azure AD Connect wizard, the following error is
returned:

Azure AD Connect server is in staging mode


If the Azure AD Connect server is in staging mode, password synchronization is temporarily disabled, and the
following error is returned:
No password synchronization heartbeat events
Each on-premises Active Directory connector has its own password synchronization channel. When the password
synchronization channel is established and there aren't any password changes to be synchronized, a heartbeat
event (EventId 654) is generated once every 30 minutes under the Windows Application Event Log. For each on-
premises Active Directory connector, the cmdlet searches for corresponding heartbeat events in the past three
hours. If no heartbeat event is found, the following error is returned:

AD DS account does not have correct permissions


If the AD DS account that's used by the on-premises Active Directory connector to synchronize password hashes
does not have the appropriate permissions, the following error is returned:

Incorrect AD DS account username or password


If the AD DS account used by the on-premises Active Directory connector to synchronize password hashes has an
incorrect username or password, the following error is returned:

One object is not synchronizing passwords: troubleshoot by using the


troubleshooting task
You can use the troubleshooting task to determine why one object is not synchronizing passwords.

NOTE
The troubleshooting task is available only for Azure AD Connect version 1.1.614.0 or later.

Run the diagnostics cmdlet


To troubleshoot issues for a specific user object:
1. Open a new Windows PowerShell session on your Azure AD Connect server with the Run as
Administrator option.
2. Run Set-ExecutionPolicy RemoteSigned or Set-ExecutionPolicy Unrestricted .
3. Start the Azure AD Connect wizard.
4. Navigate to the Additional Tasks page, select Troubleshoot, and click Next.
5. On the Troubleshooting page, click Launch to start the troubleshooting menu in PowerShell.
6. In the main menu, select Troubleshoot Password Synchronization.
7. In the sub menu, select Password is not synchronized for a specific user account.
Understand the results of the troubleshooting task
The troubleshooting task performs the following checks:
Examines the state of the Active Directory object in the Active Directory connector space, Metaverse, and
Azure AD connector space.
Validates that there are synchronization rules with password synchronization enabled and applied to the
Active Directory object.
Attempts to retrieve and display the results of the last attempt to synchronize the password for the object.
The following diagram illustrates the results of the cmdlet when troubleshooting password synchronization for a
single object:

The rest of this section describes specific results returned by the cmdlet and corresponding issues.
The Active Directory object isn't exported to Azure AD
Password synchronization for this on-premises Active Directory account fails because there is no corresponding
object in the Azure AD tenant. The following error is returned:

User has a temporary password


Currently, Azure AD Connect does not support synchronizing temporary passwords with Azure AD. A password is
considered to be temporary if the Change password at next logon option is set on the on-premises Active
Directory user. The following error is returned:

Results of last attempt to synchronize password aren't available


By default, Azure AD Connect stores the results of password synchronization attempts for seven days. If there are
no results available for the selected Active Directory object, the following warning is returned:

No passwords are synchronized: troubleshoot by using the diagnostic


cmdlet
You can use the Invoke-ADSyncDiagnostics cmdlet to figure out why no passwords are synchronized.

NOTE
The Invoke-ADSyncDiagnostics cmdlet is available only for Azure AD Connect version 1.1.524.0 or later.

Run the diagnostics cmdlet


To troubleshoot issues where no passwords are synchronized:
1. Open a new Windows PowerShell session on your Azure AD Connect server with the Run as
Administrator option.
2. Run Set-ExecutionPolicy RemoteSigned or Set-ExecutionPolicy Unrestricted .
3. Run Import-Module ADSyncDiagnostics .
4. Run Invoke-ADSyncDiagnostics -PasswordSync .

One object is not synchronizing passwords: troubleshoot by using the


diagnostic cmdlet
You can use the Invoke-ADSyncDiagnostics cmdlet to determine why one object is not synchronizing passwords.

NOTE
The Invoke-ADSyncDiagnostics cmdlet is available only for Azure AD Connect version 1.1.524.0 or later.

Run the diagnostics cmdlet


To troubleshoot issues where no passwords are synchronized for a user:
1. Open a new Windows PowerShell session on your Azure AD Connect server with the Run as
Administrator option.
2. Run Set-ExecutionPolicy RemoteSigned or Set-ExecutionPolicy Unrestricted .
3. Run Import-Module ADSyncDiagnostics .
4. Run the following cmdlet:

Invoke-ADSyncDiagnostics -PasswordSync -ADConnectorName <Name-of-AD-Connector> -DistinguishedName


<DistinguishedName-of-AD-object>
For example:

Invoke-ADSyncDiagnostics -PasswordSync -ADConnectorName "contoso.com" -DistinguishedName


"CN=TestUserCN=Users,DC=contoso,DC=com"

No passwords are synchronized: manual troubleshooting steps


Follow these steps to determine why no passwords are synchronized:
1. Is the Connect server in staging mode? A server in staging mode does not synchronize any passwords.
2. Run the script in the Get the status of password sync settings section. It gives you an overview of the
password sync configuration.

3. If the feature is not enabled in Azure AD or if the sync channel status is not enabled, run the Connect
installation wizard. Select Customize synchronization options, and unselect password sync. This change
temporarily disables the feature. Then run the wizard again and re-enable password sync. Run the script
again to verify that the configuration is correct.
4. Look in the event log for errors. Look for the following events, which would indicate a problem:
Source: "Directory synchronization" ID: 0, 611, 652, 655 If you see these events, you have a connectivity
problem. The event log message contains forest information where you have a problem. For more
information, see Connectivity problem.
5. If you see no heartbeat or if nothing else worked, run Trigger a full sync of all passwords. Run the script only
once.
6. See the Troubleshoot one object that is not synchronizing passwords section.
Connectivity problems
Do you have connectivity with Azure AD?
Does the account have required permissions to read the password hashes in all domains? If you installed Connect
by using Express settings, the permissions should already be correct.
If you used custom installation, set the permissions manually by doing the following:
1. To find the account used by the Active Directory connector, start Synchronization Service Manager.
2. Go to Connectors, and then search for the on-premises Active Directory forest you are troubleshooting.
3. Select the connector, and then click Properties.
4. Go to Connect to Active Directory Forest.
Note the username and the domain where the account is located.
5. Start Active Directory Users and Computers, and then verify that the account you found earlier has the
follow permissions set at the root of all domains in your forest:
Replicate Directory Changes
Replicate Directory Changes All
6. Are the domain controllers reachable by Azure AD Connect? If the Connect server cannot connect to all
domain controllers, configure Only use preferred domain controller.

7. Go back to Synchronization Service Manager and Configure Directory Partition.


8. Select your domain in Select directory partitions, select the Only use preferred domain controllers
check box, and then click Configure.
9. In the list, enter the domain controllers that Connect should use for password sync. The same list is used for
import and export as well. Do these steps for all your domains.
10. If the script shows that there is no heartbeat, run the script in Trigger a full sync of all passwords.

One object is not synchronizing passwords: manual troubleshooting


steps
You can easily troubleshoot password synchronization issues by reviewing the status of an object.
1. In Active Directory Users and Computers, search for the user, and then verify that the User must
change password at next logon check box is cleared.
If the check box is selected, ask the user to sign in and change the password. Temporary passwords are not
synchronized with Azure AD.
2. If the password looks correct in Active Directory, follow the user in the sync engine. By following the user
from on-premises Active Directory to Azure AD, you can see whether there is a descriptive error on the
object.
a. Start the Synchronization Service Manager.
b. Click Connectors.
c. Select the Active Directory Connector where the user is located.
d. Select Search Connector Space.
e. In the Scope box, select DN or Anchor, and then enter the full DN of the user you are troubleshooting.

f. Locate the user you are looking for, and then click Properties to see all the attributes. If the user is not in
the search result, verify your filtering rules and make sure that you run Apply and verify changes for the
user to appear in Connect.
g. To see the password sync details of the object for the past week, click Log.
If the object log is empty, Azure AD Connect has been unable to read the password hash from Active
Directory. Continue your troubleshooting with Connectivity Errors. If you see any other value than success,
refer to the table in Password sync log.
h. Select the lineage tab, and make sure that at least one sync rule in the PasswordSync column is True. In
the default configuration, the name of the sync rule is In from AD - User AccountEnabled.

i. Click Metaverse Object Properties to display a list of user attributes.

Verify that there is no cloudFiltered attribute present. Make sure that the domain attributes (domainFQDN
and domainNetBios) have the expected values.
j. Click the Connectors tab. Make sure that you see connectors to both on-premises Active Directory and
Azure AD.
k. Select the row that represents Azure AD, click Properties, and then click the Lineage tab. The connector
space object should have an outbound rule in the PasswordSync column set to True. In the default
configuration, the name of the sync rule is Out to AAD - User Join.

Password sync log


The status column can have the following values:

STATUS DESCRIPTION

Success Password has been successfully synchronized.

FilteredByTarget Password is set to User must change password at next


logon. Password has not been synchronized.

NoTargetConnection No object in the metaverse or in the Azure AD connector


space.

SourceConnectorNotPresent No object found in the on-premises Active Directory


connector space.
STATUS DESCRIPTION

TargetNotExportedToDirectory The object in the Azure AD connector space has not yet been
exported.

MigratedCheckDetailsForMoreInfo Log entry was created before build 1.0.9125.0 and is shown in
its legacy state.

Error Service returned an unknown error.

Unknown An error occurred while trying to process a batch of password


hashes.

MissingAttribute Specific attributes (for example, Kerberos hash) required by


Azure AD Domain Services are not available.

RetryRequestedByTarget Specific attributes (for example, Kerberos hash) required by


Azure AD Domain Services were not available previously. An
attempt to resynchronize the user's password hash is made.

Scripts to help troubleshooting


Get the status of password sync settings
Import-Module ADSync
$connectors = Get-ADSyncConnector
$aadConnectors = $connectors | Where-Object {$_.SubType -eq "Windows Azure Active Directory (Microsoft)"}
$adConnectors = $connectors | Where-Object {$_.ConnectorTypeName -eq "AD"}
if ($aadConnectors -ne $null -and $adConnectors -ne $null)
{
if ($aadConnectors.Count -eq 1)
{
$features = Get-ADSyncAADCompanyFeature -ConnectorName $aadConnectors[0].Name
Write-Host
Write-Host "Password sync feature enabled in your Azure AD directory: " $features.PasswordHashSync
foreach ($adConnector in $adConnectors)
{
Write-Host
Write-Host "Password sync channel status BEGIN ---------------------------------------------------
---- "
Write-Host
Get-ADSyncAADPasswordSyncConfiguration -SourceConnector $adConnector.Name
Write-Host
$pingEvents =
Get-EventLog -LogName "Application" -Source "Directory Synchronization" -InstanceId 654 -
After (Get-Date).AddHours(-3) |
Where-Object {
$_.Message.ToUpperInvariant().Contains($adConnector.Identifier.ToString("D").ToUpperInvariant()) } |
Sort-Object { $_.Time } -Descending
if ($pingEvents -ne $null)
{
Write-Host "Latest heart beat event (within last 3 hours). Time " $pingEvents[0].TimeWritten
}
else
{
Write-Warning "No ping event found within last 3 hours."
}
Write-Host
Write-Host "Password sync channel status END -----------------------------------------------------
-- "
Write-Host
}
}
else
{
Write-Warning "More than one Azure AD Connectors found. Please update the script to use the
appropriate Connector."
}
}
Write-Host
if ($aadConnectors -eq $null)
{
Write-Warning "No Azure AD Connector was found."
}
if ($adConnectors -eq $null)
{
Write-Warning "No AD DS Connector was found."
}
Write-Host

Trigger a full sync of all passwords

NOTE
Run this script only once. If you need to run it more than once, something else is the problem. To troubleshoot the problem,
contact Microsoft support.

You can trigger a full sync of all passwords by using the following script:
$adConnector = "<CASE SENSITIVE AD CONNECTOR NAME>"
$aadConnector = "<CASE SENSITIVE AAD CONNECTOR NAME>"
Import-Module adsync
$c = Get-ADSyncConnector -Name $adConnector
$p = New-Object Microsoft.IdentityManagement.PowerShell.ObjectModel.ConfigurationParameter
"Microsoft.Synchronize.ForceFullPasswordSync", String, ConnectorGlobal, $null, $null, $null
$p.Value = 1
$c.GlobalParameters.Remove($p.Name)
$c.GlobalParameters.Add($p)
$c = Add-ADSyncConnector -Connector $c
Set-ADSyncAADPasswordSyncConfiguration -SourceConnector $adConnector -TargetConnector $aadConnector -Enable
$false
Set-ADSyncAADPasswordSyncConfiguration -SourceConnector $adConnector -TargetConnector $aadConnector -Enable
$true

Next steps
Implementing password synchronization with Azure AD Connect sync
Azure AD Connect Sync: Customizing synchronization options
Integrating your on-premises identities with Azure Active Directory
Azure AD Connect sync: Handling LargeObject errors
caused by userCertificate attribute
1/17/2018 • 8 min to read • Edit Online

Azure AD enforces a maximum limit of 15 certificate values on the userCertificate attribute. If Azure AD Connect
exports an object with more than 15 values to Azure AD, Azure AD returns a LargeObject error with message:

"The provisioned object is too large. Trim the number of attribute values on this object. The operation will be
retried in the next synchronization cycle..."

The LargeObject error may be caused by other AD attributes. To confirm it is indeed caused by the userCertificate
attribute, you need to verify against the object either in on-premises AD or in the Synchronization Service Manager
Metaverse Search.
To obtain the list of objects in your tenant with LargeObject errors, use one of the following methods:
If your tenant is enabled for Azure AD Connect Health for sync, you can refer to the Synchronization Error
Report provided.
The notification email for directory synchronization errors that is sent at the end of each sync cycle has the
list of objects with LargeObject errors.
The Synchronization Service Manager Operations tab displays the list of objects with LargeObject errors if you
click the latest Export to Azure AD operation.

Mitigation options
Until the LargeObject error is resolved, other attribute changes to the same object cannot be exported to Azure AD.
To resolve the error, you can consider the following options:
Upgrade Azure AD Connect to build 1.1.524.0 or after. In Azure AD Connect build 1.1.524.0, the out-of-box
synchronization rules have been updated to not export attributes userCertificate and userSMIMECertificate if
the attributes have more than 15 values. For details on how to upgrade Azure AD Connect, refer to article
Azure AD Connect: Upgrade from a previous version to the latest.
Implement an outbound sync rule in Azure AD Connect that exports a null value instead of the actual
values for objects with more than 15 certificate values. This option is suitable if you do not require any
of the certificate values to be exported to Azure AD for objects with more than 15 values. For details on how
to implement this sync rule, refer to next section Implementing sync rule to limit export of userCertificate
attribute.
Reduce the number of certificate values on the on-premises AD object (15 or less) by removing values that
are no longer in use by your organization. This is suitable if the attribute bloat is caused by expired or
unused certificates. You can use the PowerShell script available here to help find, backup, and delete expired
certificates in your on-premises AD. Before deleting the certificates, it is recommended that you verify with
the Public-Key-Infrastructure administrators in your organization.
Configure Azure AD Connect to exclude the userCertificate attribute from being exported to Azure AD. In
general, we do not recommend this option since the attribute may be used by Microsoft Online Services to
enable specific scenarios. In particular:
The userCertificate attribute on the User object is used by Exchange Online and Outlook clients for
message signing and encryption. To learn more about this feature, refer to article S/MIME for
message signing and encryption.
The userCertificate attribute on the Computer object is used by Azure AD to allow Windows 10 on-
premises domain-joined devices to connect to Azure AD. To learn more about this feature, please
refer to article Connect domain-joined devices to Azure AD for Windows 10 experiences.

Implementing sync rule to limit export of userCertificate attribute


To resolve the LargeObject error caused by the userCertificate attribute, you can implement an outbound sync rule
in Azure AD Connect that exports a null value instead of the actual values for objects with more than 15
certificate values. This section describes the steps required to implement the sync rule for User objects. The steps
can be adapted for Contact and Computer objects.

IMPORTANT
Exporting null value removes certificate values previously exported successfully to Azure AD.

The steps can be summarized as:


1. Disable sync scheduler and verify there is no synchronization in progress.
2. Find the existing outbound sync rule for userCertificate attribute.
3. Create the outbound sync rule required.
4. Verify the new sync rule on an existing object with LargeObject error.
5. Apply the new sync rule to remaining objects with LargeObject error.
6. Verify there are no unexpected changes waiting to be exported to Azure AD.
7. Export the changes to Azure AD.
8. Re-enable sync scheduler.
Step 1. Disable sync scheduler and verify there is no synchronization in progress
Ensure no synchronization takes place while you are in the middle of implementing a new sync rule to avoid
unintended changes being exported to Azure AD. To disable the built-in sync scheduler:
1. Start PowerShell session on the Azure AD Connect server.
2. Disable scheduled synchronization by running cmdlet: Set-ADSyncScheduler -SyncCycleEnabled $false

NOTE
The preceding steps are only applicable to newer versions (1.1.xxx.x) of Azure AD Connect with the built-in scheduler. If you
are using older versions (1.0.xxx.x) of Azure AD Connect that uses Windows Task Scheduler, or you are using your own
custom scheduler (not common) to trigger periodic synchronization, you need to disable them accordingly.

1. Start the Synchronization Service Manager by going to START → Synchronization Service.


2. Go to the Operations tab and confirm there is no operation whose status is “in progress.”
Step 2. Find the existing outbound sync rule for userCertificate attribute
There should be an existing sync rule that is enabled and configured to export userCertificate attribute for User
objects to Azure AD. Locate this sync rule to find out its precedence and scoping filter configuration:
1. Start the Synchronization Rules Editor by going to START → Synchronization Rules Editor.
2. Configure the search filters with the following values:
ATTRIBUTE VALUE

Direction Outbound

MV Object Type Person

Connector name of your Azure AD connector

Connector Object Type user

MV attribute userCertificate

3. If you are using OOB (out-of-box) sync rules to Azure AD connector to export userCertficiate attribute for
User objects, you should get back the “Out to AAD – User ExchangeOnline” rule.
4. Note down the precedence value of this sync rule.
5. Select the sync rule and click Edit.
6. In the “Edit Reserved Rule Confirmation” pop-up dialog, click No. (Don’t worry, we are not going to make any
change to this sync rule).
7. In the edit screen, select the Scoping filter tab.
8. Note down the scoping filter configuration. If you are using the OOB sync rule, there should exactly be one
scoping filter group containing two clauses, including:

ATTRIBUTE OPERATOR VALUE

sourceObjectType EQUAL User

cloudMastered NOTEQUAL True

Step 3. Create the outbound sync rule required


The new sync rule must have the same scoping filter and higher precedence than the existing sync rule. This
ensures that the new sync rule applies to the same set of objects as the existing sync rule and overrides the existing
sync rule for the userCertificate attribute. To create the sync rule:
1. In the Synchronization Rules Editor, click the Add new rule button.
2. Under the Description tab, provide the following configuration:

ATTRIBUTE VALUE DETAILS

Name Provide a name E.g., “Out to AAD – Custom override


for userCertificate”

Description Provide a description E.g., “If userCertificate attribute has


more than 15 values, export NULL.”

Connected System Select the Azure AD Connector

Connected System Object Type user

Metaverse Object Type person

Link Type Join


ATTRIBUTE VALUE DETAILS

Precedence Chose a number between 1 - 99 The number chosen must not be


used by any existing sync rule and
has a lower value (and therefore,
higher precedence) than the existing
sync rule.

3. Go to the Scoping filter tab and implement the same scoping filter the existing sync rule is using.
4. Skip the Join rules tab.
5. Go to the Transformations tab to add a new transformation using following configuration:

ATTRIBUTE VALUE

Flow Type Expression

Target Attribute userCertificate

Source Attribute Use the following expression:


IIF(IsNullOrEmpty([userCertificate]), NULL,
IIF((Count([userCertificate])>
15),AuthoritativeNull,[userCertificate]))

6. Click the Add button to create the sync rule.


Step 4. Verify the new sync rule on an existing object with LargeObject error
This is to verify that the sync rule created is working correctly on an existing AD object with LargeObject error
before you apply it to other objects:
1. Go to the Operations tab in the Synchronization Service Manager.
2. Select the most recent Export to Azure AD operation and click on one of the objects with LargeObject errors.
3. In the Connector Space Object Properties pop-up screen, click on the Preview button.
4. In the Preview pop-up screen, select Full synchronization and click Commit Preview.
5. Close the Preview screen and the Connector Space Object Properties screen.
6. Go to the Connectors tab in the Synchronization Service Manager.
7. Right-click on the Azure AD Connector and select Run...
8. In the Run Connector pop-up, select Export step and click OK.
9. Wait for Export to Azure AD to complete and confirm there is no more LargeObject error on this specific object.
Step 5. Apply the new sync rule to remaining objects with LargeObject error
Once the sync rule has been added, you need to run a full synchronization step on the AD Connector:
1. Go to the Connectors tab in the Synchronization Service Manager.
2. Right-click on the AD Connector and select Run...
3. In the Run Connector pop-up, select Full Synchronization step and click OK.
4. Wait for the Full Synchronization step to complete.
5. Repeat the above steps for the remaining AD Connectors if you have more than one AD Connectors. Usually,
multiple connectors are required if you have multiple on-premises directories.
Step 6. Verify there are no unexpected changes waiting to be exported to Azure AD
1. Go to the Connectors tab in the Synchronization Service Manager.
2. Right-click on the Azure AD Connector and select Search Connector Space.
3. In the Search Connector Space pop-up:
a. Set Scope to Pending Export.
b. Check all 3 checkboxes, including Add, Modify and Delete.
c. Click Search button to return all objects with changes waiting to be exported to Azure AD.
d. Verify there are no unexpected changes. To examine the changes for a given object, double-click on the
object.
Step 7. Export the changes to Azure AD
To export the changes to Azure AD:
1. Go to the Connectors tab in the Synchronization Service Manager.
2. Right-click on the Azure AD Connector and select Run...
3. In the Run Connector pop-up, select Export step and click OK.
4. Wait for Export to Azure AD to complete and confirm there are no more LargeObject errors.
Step 8. Re -enable sync scheduler
Now that the issue is resolved, re-enable the built-in sync scheduler:
1. Start PowerShell session.
2. Re-enable scheduled synchronization by running cmdlet: Set-ADSyncScheduler -SyncCycleEnabled $true

NOTE
The preceding steps are only applicable to newer versions (1.1.xxx.x) of Azure AD Connect with the built-in scheduler. If you
are using older versions (1.0.xxx.x) of Azure AD Connect that uses Windows Task Scheduler, or you are using your own
custom scheduler (not common) to trigger periodic synchronization, you need to disable them accordingly.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect: How to recover from LocalDB 10-
GB limit
1/17/2018 • 4 min to read • Edit Online

Azure AD Connect requires a SQL Server database to store identity data. You can either use the default SQL Server
2012 Express LocalDB installed with Azure AD Connect or use your own full SQL. SQL Server Express imposes a 10-
GB size limit. When using LocalDB and this limit is reached, Azure AD Connect Synchronization Service can no
longer start or synchronize properly. This article provides the recovery steps.

Symptoms
There are two common symptoms:
Azure AD Connect Synchronization Service is running but fails to synchronize with “stopped-database-disk-
full” error.
Azure AD Connect Synchronization Service is unable to start. When you attempt to start the service, it fails
with event 6323 and error message "The server encountered an error because SQL Server is out of disk
space."

Short-term recovery steps


This section provides the steps to reclaim DB space required for Azure AD Connect Synchronization Service to
resume operation. The steps include:
1. Determine the Synchronization Service status
2. Shrink the database
3. Delete run history data
4. Shorten retention period for run history data
Determine the Synchronization Service status
First, determine whether the Synchronization Service is still running or not:
1. Log in to your Azure AD Connect server as administrator.
2. Go to Service Control Manager.
3. Check the status of Microsoft Azure AD Sync.
4. If it is running, do not stop or restart the service. Skip Shrink the database step and go to Delete run history
data step.
5. If it is not running, try to start the service. If the service starts successfully, skip Shrink the database step and
go to Delete run history data step. Otherwise, continue with Shrink the database step.
Shrink the database
Use the Shrink operation to free up enough DB space to start the Synchronization Service. It frees up DB space by
removing whitespaces in the database. This step is best-effort as it is not guaranteed that you can always recover
space. To learn more about Shrink operation, read this article Shrink a database.
IMPORTANT
Skip this step if you can get the Synchronization Service to run. It is not recommended to shrink the SQL DB as it can lead to
poor performance due to increased fragmentation.

The name of the database created for Azure AD Connect is ADSync. To perform a Shrink operation, you must log in
either as the sysadmin or DBO of the database. During Azure AD Connect installation, the following accounts are
granted sysadmin rights:
Local Administrators
The user account that was used to run Azure AD Connect installation.
The Sync Service account that is used as the operating context of Azure AD Connect Synchronization Service.
The local group ADSyncAdmins that was created during installation.
1. Back up the database by copying ADSync.mdf and ADSync_log.ldf files located under
%ProgramFiles%\Microsoft Azure AD Sync\Data to a safe location.

2. Start a new PowerShell session.


3. Navigate to folder %ProgramFiles%\Microsoft SQL Server\110\Tools\Binn .
4. Start sqlcmd utility by running the command
./SQLCMD.EXE -S “(localdb)\.\ADSync” -U <Username> -P <Password> , using the credential of a sysadmin or the
database DBO.
5. To shrink the database, at the sqlcmd prompt (1>), enter DBCC Shrinkdatabase(ADSync,1); , followed by GO in
the next line.
6. If the operation is successful, try to start the Synchronization Service again. If you can start the
Synchronization Service, go to Delete run history data step. If not, contact Support.
Delete run history data
By default, Azure AD Connect retains up to seven days’ worth of run history data. In this step, we delete the run
history data to reclaim DB space so that Azure AD Connect Synchronization Service can start syncing again.
1. Start Synchronization Service Manager by going to START → Synchronization Service.
2. Go to the Operations tab.
3. Under Actions, select Clear Runs…
4. You can either choose Clear all runs or Clear runs before… option. It is recommended that you start by
clearing run history data that are older than two days. If you continue to run into DB size issue, then choose
the Clear all runs option.
Shorten retention period for run history data
This step is to reduce the likelihood of running into the 10-GB limit issue after multiple sync cycles.
1. Open a new PowerShell session.
2. Run Get-ADSyncScheduler and take note of the PurgeRunHistoryInterval property, which specifies the current
retention period.
3. Run Set-ADSyncScheduler -PurgeRunHistoryInterval 2.00:00:00 to set the retention period to two days. Adjust
the retention period as appropriate.

Long-term solution – Migrate to full SQL


In general, the issue is indicative that 10-GB database size is no longer sufficient for Azure AD Connect to
synchronize your on-premises Active Directory to Azure AD. It is recommended that you switch to using the full
version of SQL server. You cannot directly replace the LocalDB of an existing Azure AD Connect deployment with
the database of the full version of SQL. Instead, you must deploy a new Azure AD Connect server with the full
version of SQL. It is recommended that you do a swing migration where the new Azure AD Connect server (with
SQL DB) is deployed as a staging server, next to the existing Azure AD Connect server (with LocalDB).
For instruction on how to configure remote SQL with Azure AD Connect, refer to article Custom installation of
Azure AD Connect.
For instructions on swing migration for Azure AD Connect upgrade, refer to article Azure AD Connect: Upgrade
from a previous version to the latest.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Identity synchronization and duplicate attribute
resiliency
1/17/2018 • 7 min to read • Edit Online

Duplicate Attribute Resiliency is a feature in Azure Active Directory that will eliminate friction caused by
UserPrincipalName and ProxyAddress conflicts when running one of Microsoft’s synchronization tools.
These two attributes are generally required to be unique across all User, Group, or Contact objects in a given
Azure Active Directory tenant.

NOTE
Only Users can have UPNs.

The new behavior that this feature enables is in the cloud portion of the sync pipeline, therefore it is client agnostic
and relevant for any Microsoft synchronization product including Azure AD Connect, DirSync and MIM +
Connector. The generic term “sync client” is used in this document to represent any one of these products.

Current behavior
If there is an attempt to provision a new object with a UPN or ProxyAddress value that violates this uniqueness
constraint, Azure Active Directory blocks that object from being created. Similarly, if an object is updated with a
non-unique UPN or ProxyAddress, the update fails. The provisioning attempt or update is retried by the sync client
upon each export cycle, and continues to fail until the conflict is resolved. An error report email is generated upon
each attempt and an error is logged by the sync client.

Behavior with Duplicate Attribute Resiliency


Instead of completely failing to provision or update an object with a duplicate attribute, Azure Active Directory
“quarantines” the duplicate attribute which would violate the uniqueness constraint. If this attribute is required for
provisioning, like UserPrincipalName, the service assigns a placeholder value. The format of these temporary
values is
“+<4DigitNumber>@.onmicrosoft.com”.
If the attribute is not required, like a ProxyAddress, Azure Active Directory simply quarantines the conflict
attribute and proceeds with the object creation or update.
Upon quarantining the attribute, information about the conflict is sent in the same error report email used in the
old behavior. However, this info only appears in the error report one time, when the quarantine happens, it does
not continue to be logged in future emails. Also, since the export for this object has succeeded, the sync client does
not log an error and does not retry the create / update operation upon subsequent sync cycles.
To support this behavior a new attribute has been added to the User, Group, and Contact object classes:
DirSyncProvisioningErrors
This is a multi-valued attribute that is used to store the conflicting attributes that would violate the uniqueness
constraint should they be added normally. A background timer task has been enabled in Azure Active Directory
that runs every hour to look for duplicate attribute conflicts that have been resolved, and automatically removes
the attributes in question from quarantine.
Enabling Duplicate Attribute Resiliency
Duplicate Attribute Resiliency will be the new default behavior across all Azure Active Directory tenants. It will be
on by default for all tenants that enabled synchronization for the first time on August 22nd, 2016 or later. Tenants
that enabled sync prior to this date will have the feature enabled in batches. This rollout will begin in September
2016, and an email notification will be sent to each tenant's technical notification contact with the specific date
when the feature will be enabled.

NOTE
Once Duplicate Attribute Resiliency has been turned on it cannot be disabled.

To check if the feature is enabled for your tenant, you can do so by downloading the latest version of the Azure
Active Directory PowerShell module and running:
Get-MsolDirSyncFeatures -Feature DuplicateUPNResiliency

Get-MsolDirSyncFeatures -Feature DuplicateProxyAddressResiliency

NOTE
You can no longer use Set-MsolDirSyncFeature cmdlet to proactively enable the Duplicate Attribute Resiliency feature before
it is turned on for your tenant. To be able to test the feature, you will need to create a new Azure Active Directory tenant.

Identifying Objects with DirSyncProvisioningErrors


There are currently two methods to identify objects that have these errors due to duplicate property conflicts,
Azure Active Directory PowerShell and the Office 365 Admin Portal. There are plans to extend to additional portal
based reporting in the future.
Azure Active Directory PowerShell
For the PowerShell cmdlets in this topic, the following is true:
All of the following cmdlets are case sensitive.
The –ErrorCategory PropertyConflict must always be included. There are currently no other types of
ErrorCategory, but this may be extended in the future.
First, get started by running Connect-MsolService and entering credentials for a tenant administrator.
Then, use the following cmdlets and operators to view errors in different ways:
1. See All
2. By Property Type
3. By Conflicting Value
4. Using a String Search
5. Sorted
6. In a Limited Quantity or All
See all
Once connected, to see a general list of attribute provisioning errors in the tenant run:
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict

This produces a result like the following:


By property type
To see errors by property type, add the -PropertyName flag with the UserPrincipalName or ProxyAddresses
argument:
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -PropertyName UserPrincipalName

Or
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -PropertyName ProxyAddresses

By conflicting value
To see errors relating to a specific property add the -PropertyValue flag (-PropertyName must be used as well
when adding this flag):
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -PropertyValue User@domain.com -PropertyName
UserPrincipalName

Using a string search


To do a broad string search use the -SearchString flag. This can be used independently from all of the above
flags, with the exception of -ErrorCategory PropertyConflict, which is always required:
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -SearchString User

In a limited quantity or all


1. MaxResults can be used to limit the query to a specific number of values.
2. All can be used to ensure all results are retrieved in the case that a large number of errors exists.
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -MaxResults 5

Office 365 admin portal


You can view directory synchronization errors in the Office 365 admin center. The report in the Office 365 portal
only displays User objects that have these errors. It does not show info about conflicts between Groups and
Contacts.
For instructions on how to view directory synchronization errors in the Office 365 admin center, see Identify
directory synchronization errors in Office 365.
Identity synchronization error report
When an object with a duplicate attribute conflict is handled with this new behavior a notification is included in the
standard Identity Synchronization Error Report email that is sent to the Technical Notification contact for the
tenant. However, there is an important change in this behavior. In the past, information about a duplicate attribute
conflict would be included in every subsequent error report until the conflict was resolved. With this new behavior,
the error notification for a given conflict does only appear once- at the time the conflicting attribute is quarantined.
Here is an example of what the email notification looks like for a ProxyAddress conflict:

Resolving conflicts
Troubleshooting strategy and resolution tactics for these errors should not differ from the way duplicate attribute
errors were handled in the past. The only difference is that the timer task sweeps through the tenant on the
service-side to automatically add the attribute in question to the proper object once the conflict is resolved.
The following article outlines various troubleshooting and resolution strategies: Duplicate or invalid attributes
prevent directory synchronization in Office 365.

Known issues
None of these known issues causes data loss or service degradation. Several of them are aesthetic, others cause
standard “pre-resiliency” duplicate attribute errors to be thrown instead of quarantining the conflict attribute, and
another causes certain errors to require extra manual fix-up.
Core behavior:
1. Objects with specific attribute configurations continue to receive export errors as opposed to the duplicate
attribute(s) being quarantined.
For example:
a. New user is created in AD with a UPN of Joe@contoso.com and ProxyAddress
smtp:Joe@contoso.com
b. The properties of this object conflict with an existing Group, where ProxyAddress is
SMTP:Joe@contoso.com.
c. Upon export, a ProxyAddress conflict error is thrown instead of having the conflict attributes
quarantined. The operation is retried upon each subsequent sync cycle, as it would have been before the
resiliency feature was enabled.
2. If two Groups are created on-premises with the same SMTP address, one fails to provision on the first attempt
with a standard duplicate ProxyAddress error. However, the duplicate value is properly quarantined upon the
next sync cycle.
Office Portal Report:
1. The detailed error message for two objects in a UPN conflict set is the same. This indicates that they have both
had their UPN changed / quarantined, when in fact only a one of them had any data changed.
2. The detailed error message for a UPN conflict shows the wrong displayName for a user who has had their
UPN changed/quarantined. For example:
a. User A syncs up first with UPN = User@contoso.com.
b. User B is attempted to be synced up next with UPN = User@contoso.com.
c. User B’s UPN is changed to User1234@contoso.onmicrosoft.com and User@contoso.com is added
to DirSyncProvisioningErrors.
d. The error message for User B should indicate that User A already has User@contoso.com as a UPN,
but it shows User B’s own displayName.
Identity synchronization error report:
The link for steps on how to resolve this issue is incorrect:

It should point to https://aka.ms/duplicateattributeresiliency.

See also
Azure AD Connect sync
Integrating your on-premises identities with Azure Active Directory
Identify directory synchronization errors in Office 365
Hybrid Identity Required Ports and Protocols
12/11/2017 • 3 min to read • Edit Online

The following document is a technical reference on the required ports and protocols for implementing a hybrid
identity solution. Use the following illustration and refer to the corresponding table.

Table 1 - Azure AD Connect and On-premises AD


This table describes the ports and protocols that are required for communication between the Azure AD Connect
server and on-premises AD.

PROTOCOL PORTS DESCRIPTION

DNS 53 (TCP/UDP) DNS lookups on the destination forest.

Kerberos 88 (TCP/UDP) Kerberos authentication to the AD


forest.

MS-RPC 135 (TCP/UDP) Used during the initial configuration of


the Azure AD Connect wizard when it
binds to the AD forest, and also during
Password synchronization.

LDAP 389 (TCP/UDP) Used for data import from AD. Data is
encrypted with Kerberos Sign & Seal.

RPC 445 (TCP/UDP) Used by Seamless SSO to create a


computer account in the AD forest.

LDAP/SSL 636 (TCP/UDP) Used for data import from AD. The data
transfer is signed and encrypted. Only
used if you are using SSL.
PROTOCOL PORTS DESCRIPTION

RPC 49152- 65535 (Random high RPC Port) Used during the initial configuration of
(TCP/UDP) Azure AD Connect when it binds to the
AD forests, and during Password
synchronization. See KB929851,
KB832017, and KB224196 for more
information.

Table 2 - Azure AD Connect and Azure AD


This table describes the ports and protocols that are required for communication between the Azure AD Connect
server and Azure AD.

PROTOCOL PORTS DESCRIPTION

HTTP 80 (TCP/UDP) Used to download CRLs (Certificate


Revocation Lists) to verify SSL
certificates.

HTTPS 443(TCP/UDP) Used to synchronize with Azure AD.

For a list of URLs and IP addresses you need to open in your firewall, see Office 365 URLs and IP address ranges.

Table 3 - Azure AD Connect and AD FS Federation Servers/WAP


This table describes the ports and protocols that are required for communication between the Azure AD Connect
server and AD FS Federation/WAP servers.

PROTOCOL PORTS DESCRIPTION

HTTP 80 (TCP/UDP) Used to download CRLs (Certificate


Revocation Lists) to verify SSL
certificates.

HTTPS 443(TCP/UDP) Used to synchronize with Azure AD.

WinRM 5985 WinRM Listener

Table 4 - WAP and Federation Servers


This table describes the ports and protocols that are required for communication between the Federation servers
and WAP servers.

PROTOCOL PORTS DESCRIPTION

HTTPS 443(TCP/UDP) Used for authentication.

Table 5 - WAP and Users


This table describes the ports and protocols that are required for communication between users and the WAP
servers.
PROTOCOL PORTS DESCRIPTION

HTTPS 443(TCP/UDP) Used for device authentication.

TCP 49443 (TCP) Used for certificate authentication.

Table 6a & 6b - Pass-through Authentication with Single Sign On


(SSO) and Password Hash Sync with Single Sign On (SSO)
The following tables describes the ports and protocols that are required for communication between the Azure AD
Connect and Azure AD.
Table 6a - Pass-through Authentication with SSO
PROTOCOL PORT NUMBER DESCRIPTION

HTTP 80 Enable outbound HTTP traffic for


security validation such as SSL. Also
needed for the connector auto-update
capability to function properly.

HTTPS 443 Enable outbound HTTPS traffic for


operations such as enabling and
disabling of the feature, registering
connectors, downloading connector
updates, and handling all user sign-in
requests.

In addition, Azure AD Connect needs to be able to make direct IP connections to the Azure data center IP ranges.
Table 6b - Password Hash Sync with SSO
PROTOCOL PORT NUMBER DESCRIPTION

HTTPS 443 Enable SSO registration (required only


for the SSO registration process).

In addition, Azure AD Connect needs to be able to make direct IP connections to the Azure data center IP ranges.
Again, this is only required for the SSO registration process.

Table 7a & 7b - Azure AD Connect Health agent for (AD FS/Sync) and
Azure AD
The following tables describe the endpoints, ports, and protocols that are required for communication between
Azure AD Connect Health agents and Azure AD
Table 7a - Ports and Protocols for Azure AD Connect Health agent for (AD FS/Sync) and Azure AD
This table describes the following outbound ports and protocols that are required for communication between the
Azure AD Connect Health agents and Azure AD.

PROTOCOL PORTS DESCRIPTION

HTTPS 443(TCP/UDP) Outbound

Azure Service Bus 5671 (TCP/UDP) Outbound


PROTOCOL PORTS DESCRIPTION

7b - Endpoints for Azure AD Connect Health agent for (AD FS/Sync) and Azure AD
For a list of endpoints, see the Requirements section for the Azure AD Connect Health agent.
More details about features in preview
2/21/2018 • 1 min to read • Edit Online

This topic describes how to use features currently in preview.

Group writeback
The option for group writeback in optional features allows you to writeback Office 365 Groups to a forest with
Exchange installed. This is a group that is always mastered in the cloud. If you have Exchange on-premises, then
you can write back these groups to on-premises so users with an on-premises Exchange mailbox can send and
receive emails from these groups.
More information about Office 365 Groups and how to use them can be found here.
An Office 365 group is represented as a distribution group in on-premises AD DS. Your on-premises Exchange
server must be on Exchange 2013 cumulative update 8 (released in March 2015) or Exchange 2016 to recognize
this new group type.
Notes during the preview
The address book attribute is currently not populated in the preview. Without this attribute, the group is not
visible in the GAL. The easiest way to populate this attribute is to use the Exchange PowerShell cmdlet
update-recipient .
Only forests with the Exchange schema are valid targets for groups. If no Exchange was detected, then group
writeback is not possible to enable.
Only single-forest Exchange organization deployments are currently supported. If you have more than one
Exchange organization on-premises, then you need an on-premises GALSync solution for these groups to
appear in your other forests.
The Group writeback feature does not handle security groups or distribution groups.

NOTE
A subscription to Azure AD Premium is required for group writeback.

User writeback
IMPORTANT
The user writeback preview feature was removed in the August 2015 update to Azure AD Connect. If you have enabled it,
then you should disable this feature.

Next steps
Continue your Custom installation of Azure AD Connect.
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect: Version release history
3/12/2018 • 59 min to read • Edit Online

The Azure Active Directory (Azure AD) team regularly updates Azure AD Connect with new features and
functionality. Not all additions are applicable to all audiences.
This article is designed to help you keep track of the versions that have been released, and to understand whether
you need to update to the newest version or not.
This is a list of related topics:

TOPIC DETAILS

Steps to upgrade from Azure AD Connect Different methods to upgrade from a previous version to the
latest Azure AD Connect release.

Required permissions For permissions required to apply an update, see accounts and
permissions.

Download| Download Azure AD Connect.

1.1.750.0
Status: Released to select customers This release is currently distributed to a small and random selection of
AADConnect tenants that have enabled auto-upgrade. We will expand this group of tenants in the coming weeks
until 100% of our auto-upgrade customers have received this release. After that we will post the build for general
download on the above download link.

NOTE
When the upgrade to this new version completes, it will automatically trigger a full sync and full import for the Azure AD
connector and a full sync for the AD connector. Since this may take some time, depending on the size of your Azure AD
Connect environment, make sure that you have taken the necessary steps to support this or hold off on upgrading until you
have found a convenient moment to do so.

Azure AD Connect
Fixed issues
Set-ADSyncAutoUpgrade cmdlet would previously block Autoupgrade if auto-upgrade state is set to Suspended.
This is now changed so it does not block AutoUpgrade of future builds.

1.1.749.0
Status: Released to select customers

NOTE
When the upgrade to this new version completes, it will automatically trigger a full sync and full import for the Azure AD
connector and a full sync for the AD connector. Since this may take some time, depending on the size of your Azure AD
Connect environment, please make sure that you have taken the necessary steps to support this or hold off on upgrading
until you have found a convenient moment to do so.
Azure AD Connect
Fixed issues
Fix timing window on background tasks for Partition Filtering page when switching to next page.
Fixed a bug that caused Access violation during the ConfigDB custom action.
Fixed a bug to recover from SQL connection timeout.
Fixed a bug where certificates with SAN wildcards failed a prerequisite check.
Fixed a bug which causes miiserver.exe to crash during an Azure AD connector export.
Fixed a bug which bad password attempt logged on DC when running the Azure AD Connect wizard to
change configuration.
New features and improvements
Adding Privacy Settings for the General Data Protection Regulation (GDPR). For GDPR we are required to
indicate the kinds of customer data that are shared with Microsoft (telemetry, health, etc.), have links to
detailed online documentation, and provide a way to our customers to change their preferences. This check-
in adds the following:
Data sharing and privacy notification on the clean install EULA page.
Data sharing and privacy notification on the upgrade page.
A new additional task "Privacy Settings" where the user can change their preferences.
application telemetry - admin can switch this class of data on/off at will
Azure AD Health data - admin must visit the health portal to control their health settings. Once the service
policy has been changed, the agents will read and enforce it.
Added device write-back configuration actions and a progress bar for page initialization
Improved General Diagnostics with HTML report and full data collection in a ZIP-Text / HTML Report
Improved the reliability of auto upgrade and added additional telemetry to ensure the health of the server
can be determined
Restrict permissions available to privileged accounts on AD Connector account
For new installations, the wizard will restrict the permissions that privileged accounts have on the MSOL
account after creating the MSOL account.
The changes will take care of following:
1. Express Installations
2. Custom Installations with Auto-Create account
Changed the installer so it doesn't require SA privilege on clean install of Azure AD Connect
Added a new utility to troubleshoot synchronization issues for a specific object. It is available under
'Troubleshoot Object Synchronization' option of Azure AD Connect Wizard Troubleshoot Additional Task.
Currently, the utility checks for the following:
UserPrincipalName mismatch between synchronized user object and the user account in Azure AD
Tenant.
If the object is filtered from synchronization due to domain filtering
If the object is filtered from synchronization due to organizational unit (OU) filtering
Added a new utility to synchronize the current password hash stored in the on-premises Active Directory for
a specific user account.
The utility does not require a password change. It is available under 'Troubleshoot Password Hash Synchronization'
option of Azure AD Connect Wizard Troubleshoot Additional Task.

1.1.654.0
Status: December 12th, 2017

NOTE
This is a security related hotfix for Azure AD Connect

Azure AD Connect
An improvement has been added to Azure AD Connect version 1.1.654.0 (and after) to ensure that the
recommended permission changes described under section Lock down access to the AD DS account are
automatically applied when Azure AD Connect creates the AD DS account.
When setting up Azure AD Connect, the installing administrator can either provide an existing AD DS account, or
let Azure AD Connect automatically create the account. The permission changes are automatically applied to the
AD DS account that is created by Azure AD Connect during setup. They are not applied to existing AD DS
account provided by the installing administrator.
For customers who have upgraded from an older version of Azure AD Connect to 1.1.654.0 (or after), the
permission changes will not be retroactively applied to existing AD DS accounts created prior to the upgrade.
They will only be applied to new AD DS accounts created after the upgrade. This occurs when you are adding
new AD forests to be synchronized to Azure AD.

NOTE
This release only removes the vulnerability for new installations of Azure AD Connect where the service account is created by
the installation process. For existing installations, or in cases where you provide the account yourself, you should ensure that
this vulnerability does not exist.

Lock down access to the AD DS account


Lock down access to the AD DS account by implementing the following permission changes in the on-premises AD:
Disable inheritance on the specified object
Remove all ACEs on the specific object, except ACEs specific to SELF. We want to keep the default permissions
intact when it comes to SELF.
Assign these specific permissions:

TYPE NAME ACCESS APPLIES TO

Allow SYSTEM Full Control This object

Allow Enterprise Admins Full Control This object

Allow Domain Admins Full Control This object

Allow Administrators Full Control This object

Allow Enterprise Domain List Contents This object


Controllers
TYPE NAME ACCESS APPLIES TO

Allow Enterprise Domain Read All Properties This object


Controllers

Allow Enterprise Domain Read Permissions This object


Controllers

Allow Authenticated Users List Contents This object

Allow Authenticated Users Read All Properties This object

Allow Authenticated Users Read Permissions This object

To tighten the settings for the AD DS account you can run this PowerShell script. The PowerShell script will assign
the permissions mentioned above to the AD DS account.
PowerShell script to tighten a pre-existing service account
To use the PowerShell script, to apply these settings, to a pre-existing AD DS account, (ether provided by your
organization or created by a previous installation of Azure AD Connect, please download the script from the
provided link above.
U sa g e :

Set-ADSyncRestrictedPermissions -ObjectDN <$ObjectDN> -Credential <$Credential>

Where
$ObjectDN = The Active Directory account whose permissions need to be tightened.
$Credential = Administrator credential that has the necessary privileges to restrict the permissions on $ObjectDN
account. This is typically the Enterprise or Domain administrator. Use the fully qualified domain name of the
administrator account to avoid account lookup failures. Example: contoso.com\admin.

NOTE
$credential.UserName should be in FQDN\username format. Example: contoso.com\admin

Ex a m p l e :

Set-ADSyncRestrictedPermissions -ObjectDN "CN=TestAccount1,CN=Users,DC=bvtadwbackdc,DC=com" -Credential


$credential

Was this vulnerability used to gain unauthorized access?


To see if this vulnerability was used to compromise your Azure AD Connect configuration you should verify the last
password reset date of the service account. If the timestamp in unexpected, further investigation, via the event log,
for that password reset event, should be undertaken.
For more information, see Microsoft Security Advisory 4056318

1.1.649.0
Status: October 27 2017
NOTE
This build is not available to customers through the Azure AD Connect Auto Upgrade feature.

Azure AD Connect
Fixed issue
Fixed a version compatibility issue between Azure AD Connect and Azure AD Connect Health Agent (for sync).
This issue affects customers who are performing Azure AD Connect in-place upgrade to version 1.1.647.0, but
currently has Health Agent version 3.0.127.0. After the upgrade, the Health Agent can no longer send health data
about Azure AD Connect Synchronization Service to Azure AD Health Service. With this fix, Health Agent version
3.0.129.0 is installed during Azure AD Connect in-place upgrade. Health Agent version 3.0.129.0 does not have
compatibility issue with Azure AD Connect version 1.1.649.0.

1.1.647.0
Status: October 19 2017

IMPORTANT
There is a known compatibility issue between Azure AD Connect version 1.1.647.0 and Azure AD Connect Health Agent (for
sync) version 3.0.127.0. This issue prevents the Health Agent from sending health data about the Azure AD Connect
Synchronization Service (including object synchronization errors and run history data) to Azure AD Health Service. Before
manually upgrading your Azure AD Connect deployment to version 1.1.647.0, please verify the current version of Azure AD
Connect Health Agent installed on your Azure AD Connect server. You can do so by going to Control Panel → Add Remove
Programs and look for application Microsoft Azure AD Connect Health Agent for Sync. If its version is 3.0.127.0, it is
recommended that you wait for the next Azure AD Connect version to be available before upgrade. If the Health Agent
version isn't 3.0.127.0, it is fine to proceed with the manual, in-place upgrade. Note that this issue does not affect swing
upgrade or customers who are performing new installation of Azure AD Connect.

Azure AD Connect
Fixed issues
Fixed an issue with the Change user sign-in task in Azure AD Connect wizard:
The issue occurs when you have an existing Azure AD Connect deployment with Password
Synchronization enabled, and you are trying to set the user sign-in method as Pass-through
Authentication. Before the change is applied, the wizard incorrectly shows the "Disable Password
Synchronization" prompt. However, Password Synchronization remains enabled after the change is
applied. With this fix, the wizard no longer shows the prompt.
By design, the wizard does not disable Password Synchronization when you update the user sign-in
method using the Change user sign-in task. This is to avoid disruption to customers who want to keep
Password Synchronization, even though they are enabling Pass-through Authentication or federation
as their primary user sign-in method.
If you wish to disable Password Synchronization after updating the user sign-in method, you must
execute the Customize Synchronization Configuration task in the wizard. When you navigate to the
Optional features page, uncheck the Password Synchronization option.
Note that the same issue also occurs if you try to enable/disable Seamless Single Sign-On.
Specifically, you have an existing Azure AD Connect deployment with Password Synchronization
enabled and the user sign-in method is already configured as Pass-through Authentication. Using the
Change user sign-in task, you try to check/uncheck the Enable Seamless Single Sign-On option while
the user sign-in method remains configured as "Pass-through Authentication". Before the change is
applied, the wizard incorrectly shows the "Disable Password Synchronization" prompt. However,
Password Synchronization remains enabled after the change is applied. With this fix, the wizard no
longer shows the prompt.
Fixed an issue with the Change user sign-in task in Azure AD Connect wizard:
The issue occurs when you have an existing Azure AD Connect deployment with Password
Synchronization disabled, and you are trying to set the user sign-in method as Pass-through
Authentication. When the change is applied, the wizard enables both Pass-through Authentication and
Password Synchronization. With this fix, the wizard no longer enables Password Synchronization.
Previously, Password Synchronization was a pre-requisite for enabling Pass-through Authentication.
When you set the user sign-in method as Pass-through Authentication, the wizard would enable both
Pass-through Authentication and Password Synchronization. Recently, Password Synchronization was
removed as a pre-requisite. As part of Azure AD Connect version 1.1.557.0, a change was made to
Azure AD Connect to not enable Password Synchronization when you set the user sign-in method as
Pass-through Authentication. However, the change was only applied to Azure AD Connect installation.
With this fix, the same change is also applied to the Change user sign-in task.
Note that the same issue also occurs if you try to enable/disable Seamless Single Sign-On.
Specifically, you have an existing Azure AD Connect deployment with Password Synchronization
disabled and the user sign-in method is already configured as Pass-through Authentication. Using the
Change user sign-in task, you try to check/uncheck the Enable Seamless Single Sign-On option while
the user sign-in method remains configured as "Pass-through Authentication". When the change is
applied, the wizard enables Password Synchronization. With this fix, the wizard no longer enables
Password Synchronization.
Fixed an issue that caused Azure AD Connect upgrade to fail with error "Unable to upgrade the
Synchronization Service". Further, the Synchronization Service can no longer start with event error "The
service was unable to start because the version of the database is newer than the version of the binaries
installed". The issue occurs when the administrator performing the upgrade does not have sysadmin
privilege to the SQL server that is being used by Azure AD Connect. With this fix, Azure AD Connect only
requires the administrator to have db_owner privilege to the ADSync database during upgrade.
Fixed an Azure AD Connect Upgrade issue that affected customers who have enabled Seamless Single Sign-
On. After Azure AD Connect is upgraded, Seamless Single Sign-On incorrectly appears as disabled in Azure
AD Connect wizard, even though the feature remains enabled and fully functional. With this fix, the feature
now appears correctly as enabled in the wizard.
Fixed an issue that caused Azure AD Connect wizard to always show the “Configure Source Anchor” prompt
on the Ready to Configure page, even if no changes related to Source Anchor were made.
When performing manual in-place upgrade of Azure AD Connect, the customer is required to provide the
Global Administrator credentials of the corresponding Azure AD tenant. Previously, upgrade could proceed
even though the Global Administrator credentials provided belongs to a different Azure AD tenant. While
upgrade appears to complete successfully, certain configurations are not correctly persisted with the
upgrade. With this change, the wizard will not allow upgrade to proceed if the credentials provided do not
match the Azure AD tenant.
Removed redundant logic that unnecessarily restarted Azure AD Connect Health service at the beginning of
a manual upgrade.
New features and improvements
Added logic to simplify the steps required to set up Azure AD Connect with Microsoft Germany Cloud.
Previously, you are required to update specific registry keys on the Azure AD Connect server for it to work
correctly with Microsoft Germany Cloud, as described in this article. Now, Azure AD Connect can automatically
detect if your tenant is in Microsoft Germany Cloud based on the global administrator credentials provided
during setup.
Azure AD Connect Sync

NOTE
Note: The Synchronization Service has a WMI interface that lets you develop your own custom scheduler. This interface is
now deprecated and will be removed from future versions of Azure AD Connect shipped after June 30, 2018. Customers who
want to customize synchronization schedule should use the [built-in scheduler (https://docs.microsoft.com/azure/active-
directory/connect/active-directory-aadconnectsync-feature-scheduler).

Fixed issues
When Azure AD Connect wizard creates the AD Connector account required to synchronize changes from
on-premises Active Directory, it does not correctly assign the account the permission required to read
PublicFolder objects. This issue affects both Express installation and Custom installation. This change fixes
the issue.
Fixed an issue that caused the Azure AD Connect Wizard troubleshooting page to not render correctly for
administrators running from Windows Server 2016.
New features and improvements
When troubleshooting Password Synchronization using the Azure AD Connect wizard troubleshooting page,
the troubleshooting page now returns domain-specific status.
Previously, if you tried to enable Password Hash Synchronization, Azure AD Connect does not verify whether
the AD Connector account has required permissions to synchronize password hashes from on-premises AD.
Now, Azure AD Connect wizard will verify and warn you if the AD Connector account does not have
sufficient permissions.
AD FS Management
Fixed issue
Fixed an issue related to the use of msDS-ConsistencyGuid as Source Anchor feature. This issue affects
customers who have configured Federation with AD FS as the user sign-in method. When you execute
Configure Source Anchor task in the wizard, Azure AD Connect switches to using ms-DS-ConsistencyGuid as
source attribute for immutableId. As part of this change, Azure AD Connect attempts to update the claim rules
for ImmutableId in AD FS. However, this step failed because Azure AD Connect did not have the administrator
credentials required to configure AD FS. With this fix, Azure AD Connect now prompts you to enter the
administrator credentials for AD FS when you execute the *Configure Source Anchor task.

1.1.614.0
Status: September 05 2017
Azure AD Connect
Known issues
There is a known issue that is causing Azure AD Connect upgrade to fail with error "Unable to upgrade the
Synchronization Service". Further, the Synchronization Service can no longer start with event error "The
service was unable to start because the version of the database is newer than the version of the binaries
installed". The issue occurs when the administrator performing the upgrade does not have sysadmin
privilege to the SQL server that is being used by Azure AD Connect. Dbo permissions are not sufficient.
There is a known issue with Azure AD Connect Upgrade that is affecting customers who have enabled
Seamless Single Sign-On. After Azure AD Connect is upgraded, the feature appears as disabled in the wizard,
even though the feature remains enabled. A fix for this issue will be provided in future release. Customers
who are concerned about this display issue can manually fix it by enabling Seamless Single Sign-On in the
wizard.
Fixed issues
Fixed an issue that prevented Azure AD Connect from updating the claims rules in on-premises ADFS while
enabling the msDS-ConsistencyGuid as Source Anchor feature. The issue occurs if you try to enable the feature
for an existing Azure AD Connect deployment that has ADFS configured as the sign-in method. The issue occurs
because the wizard does not prompt for ADFS credentials before trying to update the claims rules in ADFS.
Fixed an issue that caused Azure AD Connect to fail installation if the on-premises AD forest has NTLM disabled.
The issue is due to Azure AD Connect wizard not providing fully qualified credentials when creating the security
contexts required for Kerberos authentication. This causes Kerberos authentication to fail and Azure AD Connect
wizard to fall back to using NTLM.
Azure AD Connect Sync
Fixed issues
Fixed an issue where new synchronization rule cannot be created if the Tag attribute isn’t populated.
Fixed an issue that caused Azure AD Connect to connect to on-premises AD for Password Synchronization using
NTLM, even though Kerberos is available. This issue occurs if the on-premises AD topology has one or more
domain controllers that was restored from a backup.
Fixed an issue that caused full synchronization steps to occur unnecessarily after upgrade. In general, running
full synchronization steps is required after upgrade if there are changes to out-of-box synchronization rules. The
issue was due to an error in the change detection logic that incorrectly detected a change when encountering
synchronization rule expression with newline characters. Newline characters are inserted into sync rule
expression to improve readability.
Fixed an issue that can cause the Azure AD Connect server to not work correctly after Automatic Upgrade. This
issue affects Azure AD Connect servers with version 1.1.443.0 (or earlier). For details about the issue, refer to
article Azure AD Connect is not working correctly after an automatic upgrade.
Fixed an issue that can cause Automatic Upgrade to be retried every 5 minutes when errors are encountered.
With the fix, Automatic Upgrade retries with exponential back-off when errors are encountered.
Fixed an issue where password synchronization event 611 is incorrectly shown in Windows Application Event
logs as informational instead of error. Event 611 is generated whenever password synchronization encounters
an issue.
Fixed an issue in the Azure AD Connect wizard that allows Group writeback feature to be enabled without
selecting an OU required for Group writeback.
New features and improvements
Added a Troubleshoot task to Azure AD Connect wizard under Additional Tasks. Customers can leverage this
task to troubleshoot issues related to password synchronization and collect general diagnostics. In the future,
the Troubleshoot task will be extended to include other directory synchronization-related issues.
Azure AD Connect now supports a new installation mode called Use Existing Database. This installation mode
allows customers to install Azure AD Connect that specifies an existing ADSync database. For more information
about this feature, refer to article Use an existing database.
For improved security, Azure AD Connect now defaults to using TLS1.2 to connect to Azure AD for directory
synchronization. Previously, the default was TLS1.0.
When Azure AD Connect Password Synchronization Agent starts up, it tries to connect to Azure AD well-known
endpoint for password synchronization. Upon successful connection, it is redirected to a region-specific
endpoint. Previously, the Password Synchronization Agent caches the region-specific endpoint until it is
restarted. Now, the agent clears the cache and retries with the well-known endpoint if it encounters connection
issue with the region-specific endpoint. This change ensures that password synchronization can failover to a
different region-specific endpoint when the cached region-specific endpoint is no longer available.
To synchronize changes from an on-premises AD forest, an AD DS account is required. You can either (i) create
the AD DS account yourself and provide its credential to Azure AD Connect, or (ii) provide an Enterprise Admin
credentials and let Azure AD Connect create the AD DS account for you. Previously, (i) is the default option in the
Azure AD Connect wizard. Now, (ii) is the default option.
Azure AD Connect Health
New features and improvements
Added support for Microsoft Azure Government Cloud and Microsoft Cloud Germany.
AD FS Management
Fixed issues
The Initialize-ADSyncNGCKeysWriteBack cmdlet in the AD prep powershell module was incorrectly ACL’ing the
device registration container and would therefore only inherit existing permissions. This was updated so that the
sync service account has the correct permissions.
New features and improvements
The AAD Connect Verify ADFS Login task was updated so that it verifies logins against Microsoft Online and not
just token retrieval from ADFS.
When setting up a new ADFS farm using AAD Connect, the page asking for ADFS credentials was moved so that
it now occurs before the user is asked to provide ADFS and WAP servers. This allows AAD Connect to check that
the account specified has the correct permissions.
During AAD Connect upgrade, we will no longer fail an upgrade if the ADFS AAD Trust fails to update. If that
happens, the user will be shown an appropriate warning message and should proceed to reset the trust via the
AAD Connect additional task.
Seamless Single Sign-On
Fixed issues
Fixed an issue that caused Azure AD Connect wizard to return an error if you try to enable Seamless Single Sign-
On. The error message is “Configuration of Microsoft Azure AD Connect Authentication Agent failed.” This issue
affects existing customers who had manually upgraded the preview version of the Authentication Agents for
Pass-through Authentication based on the steps described in this article.

1.1.561.0
Status: July 23 2017
Azure AD Connect
Fixed issue
Fixed an issue that caused the out-of-box synchronization rule “Out to AD - User ImmutableId” to be
removed:
The issue occurs when Azure AD Connect is upgraded, or when the task option Update
Synchronization Configuration in the Azure AD Connect wizard is used to update Azure AD Connect
synchronization configuration.
This synchronization rule is applicable to customers who have enabled the msDS-ConsistencyGuid as
Source Anchor feature. This feature was introduced in version 1.1.524.0 and after. When the
synchronization rule is removed, Azure AD Connect can no longer populate on-premises AD ms-DS-
ConsistencyGuid attribute with the ObjectGuid attribute value. It does not prevent new users from
being provisioned into Azure AD.
The fix ensures that the synchronization rule will no longer be removed during upgrade, or during
configuration change, as long as the feature is enabled. For existing customers who have been
affected by this issue, the fix also ensures that the synchronization rule is added back after upgrading
to this version of Azure AD Connect.
Fixed an issue that causes out-of-box synchronization rules to have precedence value that is less than 100:
In general, precedence values 0 - 99 are reserved for custom synchronization rules. During upgrade,
the precedence values for out-of-box synchronization rules are updated to accommodate sync rule
changes. Due to this issue, out-of-box synchronization rules may be assigned precedence value that is
less than 100.
The fix prevents the issue from occurring during upgrade. However, it does not restore the
precedence values for existing customers who have been affected by the issue. A separate fix will be
provided in the future to help with the restoration.
Fixed an issue where the Domain and OU Filtering screen in the Azure AD Connect wizard is showing Sync
all domains and OUs option as selected, even though OU-based filtering is enabled.
Fixed an issue that caused the Configure Directory Partitions screen in the Synchronization Service Manager
to return an error if the Refresh button is clicked. The error message is “An error was encountered while
refreshing domains: Unable to cast object of type ‘System.Collections.ArrayList’ to type
‘Microsoft.DirectoryServices.MetadirectoryServices.UI.PropertySheetBase.MaPropertyPages.PartitionObject.”
The error occurs when new AD domain has been added to an existing AD forest and you are trying to update
Azure AD Connect using the Refresh button.
New features and improvements
Automatic Upgrade feature has been expanded to support customers with the following configurations:
You have enabled the device writeback feature.
You have enabled the group writeback feature.
The installation is not an Express settings or a DirSync upgrade.
You have more than 100,000 objects in the metaverse.
You are connecting to more than one forest. Express setup only connects to one forest.
The AD Connector account is not the default MSOL_ account anymore.
The server is set to be in staging mode.
You have enabled the user writeback feature.

NOTE
The scope expansion of the Automatic Upgrade feature affects customers with Azure AD Connect build 1.1.105.0 and
after. If you do not want your Azure AD Connect server to be automatically upgraded, you must run following cmdlet
on your Azure AD Connect server: Set-ADSyncAutoUpgrade -AutoUpgradeState disabled . For more information
about enabling/disabling Automatic Upgrade, refer to article Azure AD Connect: Automatic upgrade.

1.1.558.0
Status: Will not be released. Changes in this build are included in version 1.1.561.0.
Azure AD Connect
Fixed issue
Fixed an issue that caused the out-of-box synchronization rule “Out to AD - User ImmutableId” to be
removed when OU-based filtering configuration is updated. This synchronization rule is required for the
msDS-ConsistencyGuid as Source Anchor feature.
Fixed an issue where the Domain and OU Filtering screen in the Azure AD Connect wizard is showing Sync
all domains and OUs option as selected, even though OU-based filtering is enabled.
Fixed an issue that caused the Configure Directory Partitions screen in the Synchronization Service Manager
to return an error if the Refresh button is clicked. The error message is “An error was encountered while
refreshing domains: Unable to cast object of type ‘System.Collections.ArrayList’ to type
‘Microsoft.DirectoryServices.MetadirectoryServices.UI.PropertySheetBase.MaPropertyPages.PartitionObject.”
The error occurs when new AD domain has been added to an existing AD forest and you are trying to update
Azure AD Connect using the Refresh button.
New features and improvements
Automatic Upgrade feature has been expanded to support customers with the following configurations:
You have enabled the device writeback feature.
You have enabled the group writeback feature.
The installation is not an Express settings or a DirSync upgrade.
You have more than 100,000 objects in the metaverse.
You are connecting to more than one forest. Express setup only connects to one forest.
The AD Connector account is not the default MSOL_ account anymore.
The server is set to be in staging mode.
You have enabled the user writeback feature.

NOTE
The scope expansion of the Automatic Upgrade feature affects customers with Azure AD Connect build 1.1.105.0 and
after. If you do not want your Azure AD Connect server to be automatically upgraded, you must run following cmdlet
on your Azure AD Connect server: Set-ADSyncAutoUpgrade -AutoUpgradeState disabled . For more information
about enabling/disabling Automatic Upgrade, refer to article Azure AD Connect: Automatic upgrade.

1.1.557.0
Status: July 2017

NOTE
This build is not available to customers through the Azure AD Connect Auto Upgrade feature.

Azure AD Connect
Fixed issue
Fixed an issue with the Initialize-ADSyncDomainJoinedComputerSync cmdlet that caused the verified domain
configured on the existing service connection point object to be changed even if it is still a valid domain. This
issue occurs when your Azure AD tenant has more than one verified domains that can be used for configuring
the service connection point.
New features and improvements
Password writeback is now available for preview with Microsoft Azure Government cloud and Microsoft
Cloud Germany. For more information about Azure AD Connect support for the different service instances,
refer to article Azure AD Connect: Special considerations for instances.
The Initialize-ADSyncDomainJoinedComputerSync cmdlet now has a new optional parameter named
AzureADDomain. This parameter lets you specify which verified domain to be used for configuring the
service connection point.
Pass-through Authentication
New features and improvements
The name of the agent required for Pass-through Authentication has been changed from Microsoft Azure AD
Application Proxy Connector to Microsoft Azure AD Connect Authentication Agent.
Enabling Pass-through Authentication no longer enables Password Hash Synchronization by default.

1.1.553.0
Status: June 2017
IMPORTANT
There are schema and sync rule changes introduced in this build. Azure AD Connect Synchronization Service will trigger Full
Import and Full Synchronization steps after upgrade. Details of the changes are described below. To temporarily defer Full
Import and Full Synchronization steps after upgrade, refer to article How to defer full synchronization after upgrade.

Azure AD Connect Sync


Known issue
There is an issue that affects customers who are using OU-based filtering with Azure AD Connect sync. When
you navigate to the Domain and OU Filtering page in the Azure AD Connect wizard, the following behavior is
expected:
If OU-based filtering is enabled, the Sync selected domains and OUs option is selected.
Otherwise, the Sync all domains and OUs option is selected.
The issue that arises is that the Sync all domains and OUs option is always selected when you run the Wizard.
This occurs even if OU-based filtering was previously configured. Before saving any AAD Connect configuration
changes, make sure the Sync selected domains and OUs option is selected and confirm that all OUs that need
to synchronize are enabled again. Otherwise, OU-based filtering will be disabled.
Fixed issues
Fixed an issue with Password writeback that allows an Azure AD Administrator to reset the password of an
on-premises AD privileged user account. The issue occurs when Azure AD Connect is granted the Reset
Password permission over the privileged account. The issue is addressed in this version of Azure AD Connect
by not allowing an Azure AD Administrator to reset the password of an arbitrary on-premises AD privileged
user account unless the administrator is the owner of that account. For more information, refer to Security
Advisory 4033453.
Fixed an issue related to the msDS-ConsistencyGuid as Source Anchor feature where Azure AD Connect
does not writeback to on-premises AD msDS-ConsistencyGuid attribute. The issue occurs when there are
multiple on-premises AD forests added to Azure AD Connect and the User identities exist across multiple
directories option is selected. When such configuration is used, the resultant synchronization rules do not
populate the sourceAnchorBinary attribute in the Metaverse. The sourceAnchorBinary attribute is used as the
source attribute for msDS-ConsistencyGuid attribute. As a result, writeback to the ms-DSConsistencyGuid
attribute does not occur. To fix the issue, following sync rules have been updated to ensure that the
sourceAnchorBinary attribute in the Metaverse is always populated:
In from AD - InetOrgPerson AccountEnabled.xml
In from AD - InetOrgPerson Common.xml
In from AD - User AccountEnabled.xml
In from AD - User Common.xml
In from AD - User Join SOAInAAD.xml
Previously, even if the msDS-ConsistencyGuid as Source Anchor feature isn’t enabled, the “Out to AD – User
ImmutableId” synchronization rule is still added to Azure AD Connect. The effect is benign and does not
cause writeback of msDS-ConsistencyGuid attribute to occur. To avoid confusion, logic has been added to
ensure that the sync rule is only added when the feature is enabled.
Fixed an issue that caused password hash synchronization to fail with error event 611. This issue occurs after
one or more domain controllers have been removed from on-premises AD. At the end of each password
synchronization cycle, the synchronization cookie issued by on-premises AD contains Invocation IDs of the
removed domain controllers with USN (Update Sequence Number) value of 0. The Password
Synchronization Manager is unable to persist synchronization cookie containing USN value of 0 and fails
with error event 611. During the next synchronization cycle, the Password Synchronization Manager reuses
the last persisted synchronization cookie that does not contain USN value of 0. This causes the same
password changes to be resynchronized. With this fix, the Password Synchronization Manager persists the
synchronization cookie correctly.
Previously, even if Automatic Upgrade has been disabled using the Set-ADSyncAutoUpgrade cmdlet, the
Automatic Upgrade process continues to check for upgrade periodically, and relies on the downloaded
installer to honor disablement. With this fix, the Automatic Upgrade process no longer checks for upgrade
periodically. The fix is automatically applied when upgrade installer for this Azure AD Connect version is
executed once.
New features and improvements
Previously, the msDS-ConsistencyGuid as Source Anchor feature was available to new deployments only.
Now, it is available to existing deployments. More specifically:
To access the feature, start the Azure AD Connect wizard and choose the Update Source Anchor option.
This option is only visible to existing deployments that are using objectGuid as sourceAnchor attribute.
When configuring the option, the wizard validates the state of the msDS-ConsistencyGuid attribute in
your on-premises Active Directory. If the attribute isn't configured on any user object in the directory, the
wizard uses the msDS-ConsistencyGuid as the sourceAnchor attribute. If the attribute is configured on
one or more user objects in the directory, the wizard concludes the attribute is being used by other
applications and is not suitable as sourceAnchor attribute and does not permit the Source Anchor change
to proceed. If you are certain that the attribute isn't used by existing applications, you need to contact
Support for information on how to suppress the error.
Specific to userCertificate attribute on Device objects, Azure AD Connect now looks for certificates values
required for Connecting domain-joined devices to Azure AD for Windows 10 experience and filters out the
rest before synchronizing to Azure AD. To enable this behavior, the out-of-box sync rule “Out to AAD -
Device Join SOAInAD” has been updated.
Azure AD Connect now supports writeback of Exchange Online cloudPublicDelegates attribute to on-
premises AD publicDelegates attribute. This enables the scenario where an Exchange Online mailbox can
be granted SendOnBehalfTo rights to users with on-premises Exchange mailbox. To support this feature, a
new out-of-box sync rule “Out to AD – User Exchange Hybrid PublicDelegates writeback” has been added.
This sync rule is only added to Azure AD Connect when Exchange Hybrid feature is enabled.
Azure AD Connect now supports synchronizing the altRecipient attribute from Azure AD. To support this
change, following out-of-box sync rules have been updated to include the required attribute flow:
In from AD – User Exchange
Out to AAD – User ExchangeOnline
The cloudSOAExchMailbox attribute in the Metaverse indicates whether a given user has Exchange Online
mailbox or not. Its definition has been updated to include additional Exchange Online RecipientDisplayTypes
as such Equipment and Conference Room mailboxes. To enable this change, the definition of the
cloudSOAExchMailbox attribute, which is found under out-of-box sync rule “In from AAD – User Exchange
Hybrid”, has been updated from:

CBool(IIF(IsNullOrEmpty([cloudMSExchRecipientDisplayType]),NULL,BitAnd([cloudMSExchRecipientDisplayType],&amp;H
FF) = 0))

... to the following:


CBool(
IIF(IsPresent([cloudMSExchRecipientDisplayType]),(
IIF([cloudMSExchRecipientDisplayType]=0,True,(
IIF([cloudMSExchRecipientDisplayType]=2,True,(
IIF([cloudMSExchRecipientDisplayType]=7,True,(
IIF([cloudMSExchRecipientDisplayType]=8,True,(
IIF([cloudMSExchRecipientDisplayType]=10,True,(
IIF([cloudMSExchRecipientDisplayType]=16,True,(
IIF([cloudMSExchRecipientDisplayType]=17,True,(
IIF([cloudMSExchRecipientDisplayType]=18,True,(
IIF([cloudMSExchRecipientDisplayType]=1073741824,True,(
IF([cloudMSExchRecipientDisplayType]=1073741840,True,False)))))))))))))))))))),False))

Added the following set of X509Certificate2-compatible functions for creating synchronization rule
expressions to handle certificate values in the userCertificate attribute:

CertSubject CertIssuer CertKeyAlgorithm

CertSubjectNameDN CertIssuerOid CertNameInfo

CertSubjectNameOid CertIssuerDN IsCert

CertFriendlyName CertThumbprint CertExtensionOids

CertFormat CertNotAfter CertPublicKeyOid

CertSerialNumber CertNotBefore CertPublicKeyParametersOid

CertVersion CertSignatureAlgorithmOid Select

CertKeyAlgorithmParams CertHashString Where

With

Following schema changes have been introduced to allow customers to create custom synchronization rules
to flow sAMAccountName, domainNetBios, and domainFQDN for Group objects, as well as
distinguishedName for User objects:
Following attributes have been added to MV schema:
Group: AccountName
Group: domainNetBios
Group: domainFQDN
Person: distinguishedName
Following attributes have been added to Azure AD Connector schema:
Group: OnPremisesSamAccountName
Group: NetBiosName
Group: DnsDomainName
User: OnPremisesDistinguishedName
The ADSyncDomainJoinedComputerSync cmdlet script now has a new optional parameter named
AzureEnvironment. The parameter is used to specify which region the corresponding Azure Active Directory
tenant is hosted in. Valid values include:
AzureCloud (default)
AzureChinaCloud
AzureGermanyCloud
USGovernment
Updated Sync Rule Editor to use Join (instead of Provision) as the default value of link type during sync rule
creation.
AD FS management
Issues fixed
Following URLs are new WS-Federation endpoints introduced by Azure AD to improve resiliency against
authentication outage and will be added to on-premises AD FS replying party trust configuration:
https://ests.login.microsoftonline.com/login.srf
https://stamp2.login.microsoftonline.com/login.srf
https://ccs.login.microsoftonline.com/login.srf
https://ccs-sdf.login.microsoftonline.com/login.srf
Fixed an issue that caused AD FS to generate incorrect claim value for IssuerID. The issue occurs if there are
multiple verified domains in the Azure AD tenant and the domain suffix of the userPrincipalName attribute
used to generate the IssuerID claim is at least 3-levels deep (for example, johndoe@us.contoso.com). The
issue is resolved by updating the regex used by the claim rules.
New features and improvements
Previously, the ADFS Certificate Management feature provided by Azure AD Connect can only be used with
ADFS farms managed through Azure AD Connect. Now, you can use the feature with ADFS farms that are not
managed using Azure AD Connect.

1.1.524.0
Released: May 2017

IMPORTANT
There are schema and sync rule changes introduced in this build. Azure AD Connect Synchronization Service will trigger Full
Import and Full Sync steps after upgrade. Details of the changes are described below.

Fixed issues:
Azure AD Connect sync
Fixed an issue that causes Automatic Upgrade to occur on the Azure AD Connect server even if customer has
disabled the feature using the Set-ADSyncAutoUpgrade cmdlet. With this fix, the Automatic Upgrade process on
the server still checks for upgrade periodically, but the downloaded installer honors the Automatic Upgrade
configuration.
During DirSync in-place upgrade, Azure AD Connect creates an Azure AD service account to be used by the
Azure AD connector for synchronizing with Azure AD. After the account is created, Azure AD Connect
authenticates with Azure AD using the account. Sometimes, authentication fails because of transient issues,
which in turn causes DirSync in-place upgrade to fail with error “An error has occurred executing Configure AAD
Sync task: AADSTS50034: To sign into this application, the account must be added to the xxx.onmicrosoft.com
directory.” To improve the resiliency of DirSync upgrade, Azure AD Connect now retries the authentication step.
There was an issue with build 443 that causes DirSync in-place upgrade to succeed but run profiles required for
directory synchronization are not created. Healing logic is included in this build of Azure AD Connect. When
customer upgrades to this build, Azure AD Connect detects missing run profiles and creates them.
Fixed an issue that causes Password Synchronization process to fail to start with Event ID 6900 and error “An
item with the same key has already been added”. This issue occurs if you update OU filtering configuration to
include AD configuration partition. To fix this issue, Password Synchronization process now synchronizes
password changes from AD domain partitions only. Non-domain partitions such as configuration partition are
skipped.
During Express installation, Azure AD Connect creates an on-premises AD DS account to be used by the AD
connector to communicate with on-premises AD. Previously, the account is created with the
PASSWD_NOTREQD flag set on the user-Account-Control attribute and a random password is set on the
account. Now, Azure AD Connect explicitly removes the PASSWD_NOTREQD flag after the password is set on
the account.
Fixed an issue that causes DirSync upgrade to fail with error “a deadlock occurred in sql server which trying to
acquire an application lock” when the mailNickname attribute is found in the on-premises AD schema, but is
not bounded to the AD User object class.
Fixed an issue that causes Device writeback feature to automatically be disabled when an administrator is
updating Azure AD Connect sync configuration using Azure AD Connect wizard. This is caused by the wizard
performing pre-requisite check for the existing Device writeback configuration in on-premises AD and the check
fails. The fix is to skip the check if Device writeback is already enabled previously.
To configure OU filtering, you can either use the Azure AD Connect wizard or the Synchronization Service
Manager. Previously, if you use the Azure AD Connect wizard to configure OU filtering, new OUs created
afterwards are included for directory synchronization. If you do not want new OUs to be included, you must
configure OU filtering using the Synchronization Service Manager. Now, you can achieve the same behavior
using Azure AD Connect wizard.
Fixed an issue that causes stored procedures required by Azure AD Connect to be created under the schema of
the installing admin, instead of under the dbo schema.
Fixed an issue that causes the TrackingId attribute returned by Azure AD to be omitted in the AAD Connect
Server Event Logs. The issue occurs if Azure AD Connect receives a redirection message from Azure AD and
Azure AD Connect is unable to connect to the endpoint provided. The TrackingId is used by Support Engineers to
correlate with service side logs during troubleshooting.
When Azure AD Connect receives LargeObject error from Azure AD, Azure AD Connect generates an event with
EventID 6941 and message “The provisioned object is too large. Trim the number of attribute values on this
object.” At the same time, Azure AD Connect also generates a misleading event with EventID 6900 and message
“Microsoft.Online.Coexistence.ProvisionRetryException: Unable to communicate with the Windows Azure Active
Directory service.” To minimize confusion, Azure AD Connect no longer generates the latter event when
LargeObject error is received.
Fixed an issue that causes the Synchronization Service Manager to become unresponsive when trying to update
the configuration for Generic LDAP connector.
New features/improvements:
Azure AD Connect sync
Sync Rule Changes – The following sync rule changes have been implemented:
Updated default sync rule set to not export attributes userCertificate and userSMIMECertificate if the
attributes have more than 15 values.
AD attributes employeeID and msExchBypassModerationLink are now included in the default sync
rule set.
AD attribute photo has been removed from default sync rule set.
Added preferredDataLocation to the Metaverse schema and AAD Connector schema. Customers who
want to update either attributes in Azure AD can implement custom sync rules to do so.
Added userType to the Metaverse schema and AAD Connector schema. Customers who want to update
either attributes in Azure AD can implement custom sync rules to do so.
Azure AD Connect now automatically enables the use of ConsistencyGuid attribute as the Source Anchor
attribute for on-premises AD objects. Further, Azure AD Connect populates the ConsistencyGuid attribute
with the objectGuid attribute value if it is empty. This feature is applicable to new deployment only. To find
out more about this feature, refer to article section Azure AD Connect: Design concepts - Using msDS-
ConsistencyGuid as sourceAnchor.
New troubleshooting cmdlet Invoke-ADSyncDiagnostics has been added to help diagnose Password Hash
Synchronization related issues. For information about using the cmdlet, refer to article Troubleshoot password
synchronization with Azure AD Connect sync.
Azure AD Connect now supports synchronizing Mail-Enabled Public Folder objects from on-premises AD to
Azure AD. You can enable the feature using Azure AD Connect wizard under Optional Features. To find out more
about this feature, refer to article Office 365 Directory Based Edge Blocking support for on-premises Mail
Enabled Public Folders.
Azure AD Connect requires an AD DS account to synchronize from on-premises AD. Previously, if you installed
Azure AD Connect using the Express mode, you could provide the credentials of an Enterprise Admin account
and Azure AD Connect would create the AD DS account required. However, for a custom installation and adding
forests to an existing deployment, you were required to provide the AD DS account instead. Now, you also have
the option to provide the credentials of an Enterprise Admin account during a custom installation and let Azure
AD Connect create the AD DS account required.
Azure AD Connect now supports SQL AOA. You must enable SQL AOA before installing Azure AD Connect.
During installation, Azure AD Connect detects whether the SQL instance provided is enabled for SQL AOA or
not. If SQL AOA is enabled, Azure AD Connect further figures out if SQL AOA is configured to use synchronous
replication or asynchronous replication. When setting up the Availability Group Listener, it is recommended that
you set the RegisterAllProvidersIP property to 0. This is because Azure AD Connect currently uses SQL Native
Client to connect to SQL and SQL Native Client does not support the use of MultiSubNetFailover property.
If you are using LocalDB as the database for your Azure AD Connect server and has reached its 10-GB size limit,
the Synchronization Service no longer starts. Previously, you need to perform ShrinkDatabase operation on the
LocalDB to reclaim enough DB space for the Synchronization Service to start. After which, you can use the
Synchronization Service Manager to delete run history to reclaim more DB space. Now, you can use Start-
ADSyncPurgeRunHistory cmdlet to purge run history data from LocalDB to reclaim DB space. Further, this
cmdlet supports an offline mode (by specifying the -offline parameter) which can be used when the
Synchronization Service is not running. Note: The offline mode can only be used if the Synchronization Service
is not running and the database used is LocalDB.
To reduce the amount of storage space required, Azure AD Connect now compresses sync error details before
storing them in LocalDB/SQL databases. When upgrading from an older version of Azure AD Connect to this
version, Azure AD Connect performs a one-time compression on existing sync error details.
Previously, after updating OU filtering configuration, you must manually run Full import to ensure existing
objects are properly included/excluded from directory synchronization. Now, Azure AD Connect automatically
triggers Full import during the next sync cycle. Further, Full import is only be applied to the AD connectors
affected by the update. Note: this improvement is applicable to OU filtering updates made using the Azure AD
Connect wizard only. It is not applicable to OU filtering update made using the Synchronization Service
Manager.
Previously, Group-based filtering supports Users, Groups, and Contact objects only. Now, Group-based filtering
also supports Computer objects.
Previously, you can delete Connector Space data without disabling Azure AD Connect sync scheduler. Now, the
Synchronization Service Manager blocks the deletion of Connector Space data if it detects that the scheduler is
enabled. Further, a warning is returned to inform customers about potential data loss if the Connector space
data is deleted.
Previously, you must disable PowerShell transcription for Azure AD Connect wizard to run correctly. This issue is
partially resolved. You can enable PowerShell transcription if you are using Azure AD Connect wizard to manage
sync configuration. You must disable PowerShell transcription if you are using Azure AD Connect wizard to
manage ADFS configuration.
1.1.486.0
Released: April 2017
Fixed issues:
Fixed the issue where Azure AD Connect will not install successfully on localized version of Windows Server.

1.1.484.0
Released: April 2017
Known issues:
This version of Azure AD Connect will not install successfully if the following conditions are all true:
1. You are performing either DirSync in-place upgrade or fresh installation of Azure AD Connect.
2. You are using a localized version of Windows Server where the name of built-in Administrator group on
the server isn't "Administrators".
3. You are using the default SQL Server 2012 Express LocalDB installed with Azure AD Connect instead of
providing your own full SQL.
Fixed issues:
Azure AD Connect sync
Fixed an issue where the sync scheduler skips the entire sync step if one or more connectors are missing run
profile for that sync step. For example, you manually added a connector using the Synchronization Service
Manager without creating a Delta Import run profile for it. This fix ensures that the sync scheduler continues to
run Delta Import for other connectors.
Fixed an issue where the Synchronization Service immediately stops processing a run profile when it is
encounters an issue with one of the run steps. This fix ensures that the Synchronization Service skips that run
step and continues to process the rest. For example, you have a Delta Import run profile for your AD connector
with multiple run steps (one for each on-premises AD domain). The Synchronization Service will run Delta
Import with the other AD domains even if one of them has network connectivity issues.
Fixed an issue that causes the Azure AD Connector update to be skipped during Automatic Upgrade.
Fixed an issue that causes Azure AD Connect to incorrectly determine whether the server is a domain controller
during setup, which in turn causes DirSync upgrade to fail.
Fixed an issue that causes DirSync in-place upgrade to not create any run profile for the Azure AD Connector.
Fixed an issue where the Synchronization Service Manager user interface becomes unresponsive when trying to
configure Generic LDAP Connector.
AD FS management
Fixed an issue where the Azure AD Connect wizard fails if the AD FS primary node has been moved to another
server.
Desktop SSO
Fixed an issue in the Azure AD Connect wizard where the Sign-In screen does not let you enable Desktop SSO
feature if you chose Password Synchronization as your Sign-In option during new installation.
New features/improvements:
Azure AD Connect sync
Azure AD Connect Sync now supports the use of Virtual Service Account, Managed Service Account and Group
Managed Service Account as its service account. This applies to new installation of Azure AD Connect only.
When installing Azure AD Connect:
By default, Azure AD Connect wizard will create a Virtual Service Account and uses it as its service
account.
If you are installing on a domain controller, Azure AD Connect falls back to previous behavior where it
will create a domain user account and uses it as its service account instead.
You can override the default behavior by providing one of the following:
A Group Managed Service Account
A Managed Service Account
A domain user account
A local user account
Previously, if you upgrade to a new build of Azure AD Connect containing connectors update or sync rule
changes, Azure AD Connect will trigger a full sync cycle. Now, Azure AD Connect selectively triggers Full Import
step only for connectors with update, and Full Synchronization step only for connectors with sync rule changes.
Previously, the Export Deletion Threshold only applies to exports which are triggered through the sync
scheduler. Now, the feature is extended to include exports manually triggered by the customer using the
Synchronization Service Manager.
On your Azure AD tenant, there is a service configuration which indicates whether Password Synchronization
feature is enabled for your tenant or not. Previously, it is easy for the service configuration to be incorrectly
configured by Azure AD Connect when you have an active and a staging server. Now, Azure AD Connect will
attempt to keep the service configuration consistent with your active Azure AD Connect server only.
Azure AD Connect wizard now detects and returns a warning if on-premises AD does not have AD Recycle Bin
enabled.
Previously, Export to Azure AD times out and fails if the combined size of the objects in the batch exceeds certain
threshold. Now, the Synchronization Service will reattempt to resend the objects in separate, smaller batches if
the issue is encountered.
The Synchronization Service Key Management application has been removed from Windows Start Menu.
Management of encryption key will continue to be supported through command-line interface using
miiskmu.exe. For information about managing encryption key, refer to article Abandoning the Azure AD Connect
Sync encryption key.
Previously, if you change the Azure AD Connect sync service account password, the Synchronization Service will
not be able start correctly until you have abandoned the encryption key and reinitialized the Azure AD Connect
sync service account password. Now, this is no longer required.
Desktop SSO
Azure AD Connect wizard no longer requires port 9090 to be opened on the network when configuring Pass-
through Authentication and Desktop SSO. Only port 443 is required. 

1.1.443.0
Released: March 2017
Fixed issues:
Azure AD Connect sync
Fixed an issue which causes Azure AD Connect wizard to fail if the display name of the Azure AD Connector does
not contain the initial onmicrosoft.com domain assigned to the Azure AD tenant.
Fixed an issue which causes Azure AD Connect wizard to fail while making connection to SQL database when
the password of the Sync Service Account contains special characters such as apostrophe, colon and space.
Fixed an issue which causes the error “The dimage has an anchor that is different than the image” to occur on an
Azure AD Connect server in staging mode, after you have temporarily excluded an on-premises AD object from
syncing and then included it again for syncing.
Fixed an issue which causes the error “The object located by DN is a phantom” to occur on an Azure AD Connect
server in staging mode, after you have temporarily excluded an on-premises AD object from syncing and then
included it again for syncing.
AD FS management
Fixed an issue where Azure AD Connect wizard does not update AD FS configuration and set the right claims on
the relying party trust after Alternate Login ID is configured.
Fixed an issue where Azure AD Connect wizard is unable to correctly handle AD FS servers whose service
accounts are configured using userPrincipalName format instead of sAMAccountName format.
Pass-through Authentication
Fixed an issue which causes Azure AD Connect wizard to fail if Pass Through Authentication is selected but
registration of its connector fails.
Fixed an issue which causes Azure AD Connect wizard to bypass validation checks on sign-in method selected
when Desktop SSO feature is enabled.
Password Reset
Fixed an issue which may cause the Azure AAD Connect server to not attempt to re-connect if the connection
was killed by a firewall or proxy.
New features/improvements:
Azure AD Connect sync
Get-ADSyncScheduler cmdlet now returns a new Boolean property named SyncCycleInProgress. If the returned
value is true, it means that there is a scheduled synchronization cycle in progress.
Destination folder for storing Azure AD Connect installation and setup logs has been moved from
%localappdata%\AADConnect to %programdata%\AADConnect to improve accessibility to the log files.
AD FS management
Added support for updating AD FS Farm SSL Certificate.
Added support for managing AD FS 2016.
You can now specify existing gMSA (Group Managed Service Account) during AD FS installation.
You can now configure SHA-256 as the signature hash algorithm for Azure AD relying party trust.
Password Reset
Introduced improvements to allow the product to function in environments with more stringent firewall rules.
Improved connection reliability to Azure Service Bus.

1.1.380.0
Released: December 2016
Fixed issue:
Fixed the issue where the issuerid claim rule for Active Directory Federation Services (AD FS) is missing in this
build.

NOTE
This build is not available to customers through the Azure AD Connect Auto Upgrade feature.
1.1.371.0
Released: December 2016
Known issue:
The issuerid claim rule for AD FS is missing in this build. The issuerid claim rule is required if you are federating
multiple domains with Azure Active Directory (Azure AD). If you are using Azure AD Connect to manage your
on-premises AD FS deployment, upgrading to this build removes the existing issuerid claim rule from your AD
FS configuration. You can work around the issue by adding the issuerid claim rule after the installation/upgrade.
For details on adding the issuerid claim rule, refer to this article on Multiple domain support for federating with
Azure AD.
Fixed issue:
If Port 9090 is not opened for the outbound connection, the Azure AD Connect installation or upgrade fails.

NOTE
This build is not available to customers through the Azure AD Connect Auto Upgrade feature.

1.1.370.0
Released: December 2016
Known issues:
The issuerid claim rule for AD FS is missing in this build. The issuerid claim rule is required if you are federating
multiple domains with Azure AD. If you are using Azure AD Connect to manage your on-premises AD FS
deployment, upgrading to this build removes the existing issuerid claim rule from your AD FS configuration.
You can work around the issue by adding the issuerid claim rule after installation/upgrade. For details on adding
issuerid claim rule, refer to this article on Multiple domain support for federating with Azure AD.
Port 9090 must be open outbound to complete installation.
New features:
Pass-through Authentication (Preview).

NOTE
This build is not available to customers through the Azure AD Connect Auto Upgrade feature.

1.1.343.0
Released: November 2016
Known issue:
The issuerid claim rule for AD FS is missing in this build. The issuerid claim rule is required if you are federating
multiple domains with Azure AD. If you are using Azure AD Connect to manage your on-premises AD FS
deployment, upgrading to this build removes the existing issuerid claim rule from your AD FS configuration.
You can work around the issue by adding the issuerid claim rule after installation/upgrade. For details on adding
issuerid claim rule, refer to this article on Multiple domain support for federating with Azure AD.
Fixed issues:
Sometimes, installing Azure AD Connect fails because it is unable to create a local service account whose
password meets the level of complexity specified by the organization's password policy.
Fixed an issue where join rules are not reevaluated when an object in the connector space simultaneously
becomes out-of-scope for one join rule and become in-scope for another. This can happen if you have two or
more join rules whose join conditions are mutually exclusive.
Fixed an issue where inbound synchronization rules (from Azure AD), which do not contain join rules, are not
processed if they have lower precedence values than those containing join rules.
Improvements:
Added support for installing Azure AD Connect on Windows Server 2016 Standard or higher.
Added support for using SQL Server 2016 as the remote database for Azure AD Connect.

1.1.281.0
Released: August 2016
Fixed issues:
Changes to sync interval do not take place until after the next sync cycle is complete.
Azure AD Connect wizard does not accept an Azure AD account whose username starts with an underscore (_).
Azure AD Connect wizard fails to authenticate the Azure AD account if the account password contains too many
special characters. Error message "Unable to validate credentials. An unexpected error has occurred." is returned.
Uninstalling staging server disables password synchronization in Azure AD tenant and causes password
synchronization to fail with active server.
Password synchronization fails in uncommon cases when there is no password hash stored on the user.
When Azure AD Connect server is enabled for staging mode, password writeback is not temporarily disabled.
Azure AD Connect wizard does not show the actual password synchronization and password writeback
configuration when server is in staging mode. It always shows them as disabled.
Configuration changes to password synchronization and password writeback are not persisted by Azure AD
Connect wizard when server is in staging mode.
Improvements:
Updated the Start-ADSyncSyncCycle cmdlet to indicate whether it is able to successfully start a new sync cycle
or not.
Added the Stop-ADSyncSyncCycle cmdlet to terminate sync cycle and operation, which are currently in
progress.
Updated the Stop-ADSyncScheduler cmdlet to terminate sync cycle and operation, which are currently in
progress.
When configuring Directory extensions in Azure AD Connect wizard, the Azure AD attribute of type "Teletex
string" can now be selected.

1.1.189.0
Released: June 2016
Fixed issues and improvements:
Azure AD Connect can now be installed on a FIPS-compliant server.
For password synchronization, see Password sync and FIPS.
Fixed an issue where a NetBIOS name could not be resolved to the FQDN in the Active Directory Connector.
1.1.180.0
Released: May 2016
New features:
Warns and helps you verify domains if you didn’t do it before running Azure AD Connect.
Added support for Microsoft Cloud Germany.
Added support for the latest Microsoft Azure Government cloud infrastructure with new URL requirements.
Fixed issues and improvements:
Added filtering to the Sync Rule Editor to make it easy to find sync rules.
Improved performance when deleting a connector space.
Fixed an issue when the same object was both deleted and added in the same run (called delete/add).
A disabled sync rule no longer re-enables included objects and attributes on upgrade or directory schema
refresh.

1.1.130.0
Released: April 2016
New features:
Added support for multi-valued attributes to Directory extensions.
Added support for more configuration variations for automatic upgrade to be considered eligible for upgrade.
Added some cmdlets for custom scheduler.

1.1.119.0
Released: March 2016
Fixed issues:
Made sure Express installation cannot be used on Windows Server 2008 (pre-R2) because password sync is not
supported on this operating system.
Upgrade from DirSync with a custom filter configuration did not work as expected.
When upgrading to a newer release and there are no changes to the configuration, a full import/synchronization
should not be scheduled.

1.1.110.0
Released: February 2016
Fixed issues:
Upgrade from earlier releases does not work if the installation is not in the default C:\Program Files folder.
If you install and clear Start the synchronization process at the end of the installation wizard, running the
installation wizard a second time will not enable the scheduler.
The scheduler doesn't work as expected on servers where the US-en date/time format is not used. It will also
block Get-ADSyncScheduler to return correct times.
If you installed an earlier release of Azure AD Connect with AD FS as the sign-in option and upgrade, you cannot
run the installation wizard again.

1.1.105.0
Released: February 2016
New features:
Automatic upgrade feature for Express settings customers.
Support for the global admin by using Azure Multi-Factor Authentication and Privileged Identity Management in
the installation wizard.
You need to allow your proxy to also allow traffic to https://secure.aadcdn.microsoftonline-p.com if you
use Multi-Factor Authentication.
You need to add https://secure.aadcdn.microsoftonline-p.com to your trusted sites list for Multi-Factor
Authentication to properly work.
Allow changing the user's sign-in method after initial installation.
Allow Domain and OU filtering in the installation wizard. This also allows connecting to forests where not all
domains are available.
Scheduler is built in to the sync engine.
Features promoted from preview to GA:
Device writeback.
Directory extensions.
New preview features:
The new default sync cycle interval is 30 minutes. Used to be three hours for all earlier releases. Adds support to
change the scheduler behavior.
Fixed issues:
The verify DNS domains page didn't always recognize the domains.
Prompts for domain admin credentials when configuring AD FS.
The on-premises AD accounts are not recognized by the installation wizard if located in a domain with a
different DNS tree than the root domain.

1.0.9131.0
Released: December 2015
Fixed issues:
Password sync might not work when you change passwords in Active Directory Domain Services (AD DS), but
works when you do set a password.
When you have a proxy server, authentication to Azure AD might fail during installation, or if an upgrade is
canceled on the configuration page.
Updating from a previous release of Azure AD Connect with a full SQL Server instance fails if you are not a SQL
Server system administrator (SA).
Updating from a previous release of Azure AD Connect with a remote SQL Server shows the “Unable to access
the ADSync SQL database” error.

1.0.9125.0
Released: November 2015
New features:
Can reconfigure AD FS to Azure AD trust.
Can refresh the Active Directory schema and regenerate sync rules.
Can disable a sync rule.
Can define "AuthoritativeNull" as a new literal in a sync rule.
New preview features:
Azure AD Connect Health for sync.
Support for Azure AD Domain Services password synchronization.
New supported scenario:
Supports multiple on-premises Exchange organizations. For more information, see Hybrid deployments with
multiple Active Directory forests.
Fixed issues:
Password synchronization issues:
An object moved from out-of-scope to in-scope will not have its password synchronized. This includes
both OU and attribute filtering.
Selecting a new OU to include in sync does not require a full password sync.
When a disabled user is enabled the password does not sync.
The password retry queue is infinite and the previous limit of 5,000 objects to be retired has been
removed.
Not able to connect to Active Directory with Windows Server 2016 forest-functional level.
Not able to change the group that is used for group filtering after the initial installation.
No longer creates a new user profile on the Azure AD Connect server for every user doing a password change
with password writeback enabled.
Not able to use Long Integer values in sync rules scopes.
The check box "device writeback" remains disabled if there are unreachable domain controllers.

1.0.8667.0
Released: August 2015
New features:
The Azure AD Connect installation wizard is now localized to all Windows Server languages.
Added support for account unlock when using Azure AD password management.
Fixed issues:
Azure AD Connect installation wizard crashes if another user continues installation rather than the person who
first started the installation.
If a previous uninstallation of Azure AD Connect fails to uninstall Azure AD Connect sync cleanly, it is not
possible to reinstall.
Cannot install Azure AD Connect using Express installation if the user is not in the root domain of the forest or if
a non-English version of Active Directory is used.
If the FQDN of the Active Directory user account cannot be resolved, a misleading error message “Failed to
commit the schema” is shown.
If the account used on the Active Directory Connector is changed outside the wizard, the wizard fails on
subsequent runs.
Azure AD Connect sometimes fails to install on a domain controller.
Cannot enable and disable “Staging mode” if extension attributes have been added.
Password writeback fails in some configurations because of a bad password on the Active Directory Connector.
DirSync cannot be upgraded if a distinguished name (DN) is used in attribute filtering.
Excessive CPU usage when using password reset.
Removed preview features:
The preview feature User writeback was temporarily removed based on feedback from our preview customers.
It will be added again later after we have addressed the provided feedback.

1.0.8641.0
Released: June 2015
Initial release of Azure AD Connect.
Changed name from Azure AD Sync to Azure AD Connect.
New features:
Express settings installation
Can configure AD FS
Can upgrade from DirSync
Prevent accidental deletes
Introduced staging mode
New preview features:
User writeback
Group writeback
Device writeback
Directory extensions

1.0.494.0501
Released: May 2015
New Requirement:
Azure AD Sync now requires the .NET Framework version 4.5.1 to be installed.
Fixed issues:
Password writeback from Azure AD is failing with an Azure Service Bus connectivity error.

1.0.491.0413
Released: April 2015
Fixed issues and improvements:
The Active Directory Connector does not process deletes correctly if the recycle bin is enabled and there are
multiple domains in the forest.
The performance of import operations has been improved for the Azure Active Directory Connector.
When a group has exceeded the membership limit (by default, the limit is set to 50,000 objects), the group was
deleted in Azure Active Directory. With the new behavior, the group is not deleted, an error is thrown, and new
membership changes are not exported.
A new object cannot be provisioned if a staged delete with the same DN is already present in the connector
space.
Some objects are marked for synchronization during a delta sync even though there's no change staged on the
object.
Forcing a password sync also removes the preferred DC list.
CSExportAnalyzer has problems with some objects states.
New features:
A join can now connect to “ANY” object type in the MV.

1.0.485.0222
Released: February 2015
Improvements:
Improved import performance.
Fixed issues:
Password Sync honors the cloudFiltered attribute that is used by attribute filtering. Filtered objects are no longer
in scope for password synchronization.
In rare situations where the topology had many domain controllers, password sync doesn’t work.
“Stopped-server” when importing from the Azure AD Connector after device management has been enabled in
Azure AD/Intune.
Joining Foreign Security Principals (FSPs) from multiple domains in same forest causes an ambiguous-join
error.

1.0.475.1202
Released: December 2014
New features:
Password synchronization with attribute-based filtering is now supported. For more information, see Password
synchronization with filtering.
The msDS-ExternalDirectoryObjectID attribute is written back to Active Directory. This feature adds support for
Office 365 applications. It uses OAuth2 to access Online and On-Premises mailboxes in a Hybrid Exchange
Deployment.
Fixed upgrade issues:
A newer version of the sign-in assistant is available on the server.
A custom installation path was used to install Azure AD Sync.
An invalid custom join criterion blocks the upgrade.
Other fixes:
Fixed the templates for Office Pro Plus.
Fixed installation issues caused by user names that start with a dash.
Fixed losing the sourceAnchor setting when running the installation wizard a second time.
Fixed ETW tracing for password synchronization.

1.0.470.1023
Released: October 2014
New features:
Password synchronization from multiple on-premises Active Directory to Azure AD.
Localized installation UI to all Windows Server languages.
Upgrading from AADSync 1.0 GA
If you already have Azure AD Sync installed, there is one additional step you have to take in case you have changed
any of the out-of-box synchronization rules. After you have upgraded to the 1.0.470.1023 release, the
synchronization rules you have modified are duplicated. For each modified sync rule, do the following:
1. Locate the sync rule you have modified and take a note of the changes.
2. Delete the sync rule.
3. Locate the new sync rule that is created by Azure AD Sync and then reapply the changes.
Permissions for the Active Directory account
The Active Directory account must be granted additional permissions to be able to read the password hashes from
Active Directory. The permissions to grant are named “Replicating Directory Changes” and “Replicating Directory
Changes All.” Both permissions are required to be able to read the password hashes.

1.0.419.0911
Released: September 2014
Initial release of Azure AD Sync.

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect: Accounts and permissions
2/23/2018 • 11 min to read • Edit Online

The Azure AD Connect installation wizard offers two different paths:


In Express Settings, the wizard requires more privileges. This is so that it can set up your configuration easily,
without requiring you to create users or configure permissions.
In Custom Settings, the wizard offers you more choices and options. However, there are some situations in
which you need to ensure you have the correct permissions yourself.

Related documentation
If you did not read the documentation on Integrating your on-premises identities with Azure Active Directory, the
following table provides links to related topics.

TOPIC LINK

Download Azure AD Connect Download Azure AD Connect

Install using Express settings Express installation of Azure AD Connect

Install using Customized settings Custom installation of Azure AD Connect

Upgrade from DirSync Upgrade from Azure AD sync tool (DirSync)

After installation Verify the installation and assign licenses

Express settings installation


In Express settings, the installation wizard asks for AD DS Enterprise Admin credentials. This is so your on-
premises Active Directory can be configured with required permissions for Azure AD Connect. If you are
upgrading from DirSync, the AD DS Enterprise Admins credentials are used to reset the password for the account
used by DirSync. You also need Azure AD Global Administrator credentials.

WIZARD PAGE CREDENTIALS COLLECTED PERMISSIONS REQUIRED USED FOR

N/A User running the installation Administrator of the local Creates the local account
wizard server that is used as the sync
engine service account.

Connect to Azure AD Azure AD directory Global administrator role in Enabling sync in the Azure
credentials Azure AD AD directory.
Creation of the Azure AD
account that is used for on-
going sync operations in
Azure AD.
WIZARD PAGE CREDENTIALS COLLECTED PERMISSIONS REQUIRED USED FOR

Connect to AD DS On-premises Active Member of the Enterprise Creates an account in


Directory credentials Admins (EA) group in Active Active Directory and grants
Directory permissions to it. This
created account is used to
read and write directory
information during
synchronization.

Enterprise Admin credentials


These credentials are only used during the installation and are not used after the installation has completed. The
Enterprise Admin, not the Domain Admin should make sure the permissions in Active Directory can be set in all
domains.
Global Admin credentials
These credentials are only used during the installation and are not used after the installation has completed. It is
used to create the Azure AD account used for synchronizing changes to Azure AD. The account also enables sync
as a feature in Azure AD.
Permissions for the created AD DS account for express settings
The account created for reading and writing to AD DS have the following permissions when created by express
settings:

PERMISSION USED FOR

Replicate Directory Changes Password sync


Replicate Directory Changes All

Read/Write all properties User Import and Exchange hybrid

Read/Write all properties iNetOrgPerson Import and Exchange hybrid

Read/Write all properties Group Import and Exchange hybrid

Read/Write all properties Contact Import and Exchange hybrid

Reset password Preparation for enabling password writeback

Custom settings installation


Azure AD Connect version 1.1.524.0 and later has the option to let the Azure AD Connect wizard create the
account used to connect to Active Directory. Earlier versions require that the account is created before the
installation. The permissions you must grant this account can be found in create the AD DS account.

WIZARD PAGE CREDENTIALS COLLECTED PERMISSIONS REQUIRED USED FOR

N/A User running the installation Administrator of the local By default, creates the local
wizard server account that is used as the
If using a full SQL Server, sync engine service account.
the user must be System The account is only created
Administrator (SA) in SQL when the admin does not
specify a particular account.
WIZARD PAGE CREDENTIALS COLLECTED PERMISSIONS REQUIRED USED FOR

Install synchronization AD or local user account User, permissions are If the admin specifies an
services, Service account credentials granted by the installation account, this account is used
option wizard as the service account for
the sync service.

Connect to Azure AD Azure AD directory Global administrator role in Enabling sync in the Azure
credentials Azure AD AD directory.
Creation of the Azure AD
account that is used for on-
going sync operations in
Azure AD.

Connect your directories On-premises Active The permissions depend on This account is used to read
Directory credentials for which features you enable and write directory
each forest that is connected and can be found in Create information during
to Azure AD the AD DS account synchronization.

AD FS Servers For each server in the list, Domain Administrator Installation and
the wizard collects configuration of the AD FS
credentials when the logon server role.
credentials of the user
running the wizard are
insufficient to connect

Web application proxy For each server in the list, Local admin on the target Installation and
servers the wizard collects machine configuration of WAP server
credentials when the logon role.
credentials of the user
running the wizard are
insufficient to connect

Proxy trust credentials Federation service trust Domain account that is a Initial enrollment of FS-WAP
credentials (the credentials local administrator of the AD trust certificate.
the proxy uses to enroll for a FS server
trust certificate from the FS

AD FS Service Account page, AD user account credentials Domain user The AD user account whose
"Use a domain user account credentials are provided is
option" used as the logon account
of the AD FS service.

Create the AD DS account


The account you specify on the Connect your directories page must be present in Active Directory prior to
installation. It must also have the required permissions granted. The installation wizard does not verify the
permissions and any issues are only found during synchronization.
Which permissions you require depends on the optional features you enable. If you have multiple domains, the
permissions must be granted for all domains in the forest. If you do not enable any of these features, the default
Domain User permissions are sufficient.

FEATURE PERMISSIONS

msDS-ConsistencyGuid feature Write permissions to the msDS-ConsistencyGuid attribute


documented in Design Concepts - Using msDS-
ConsistencyGuid as sourceAnchor.
FEATURE PERMISSIONS

Password sync Replicate Directory Changes


Replicate Directory Changes All

Exchange hybrid deployment Write permissions to the attributes documented in Exchange


hybrid writeback for users, groups, and contacts.

Exchange Mail Public Folder Read permissions to the attributes documented in Exchange
Mail Public Folder for public folders.

Password writeback Write permissions to the attributes documented in Getting


started with password management for users.

Device writeback Permissions granted with a PowerShell script as described in


device writeback.

Group writeback Read, Create, Update, and Delete group objects for
synchronized Office 365 groups. For more information see
Group Writeback.

Upgrade
When you upgrade from one version of Azure AD Connect to a new release, you need the following permissions:

IMPORTANT
Starting with build 1.1.484, Azure AD Connect introduced a regression bug which requires sysadmin permissions to upgrade
the SQL database. This bug is corrected in build 1.1.647. If you are upgrading to this build, you will need sysadmin
permissions. Dbo permissions are not sufficient. If you attempt to upgrade Azure AD Connect without having sysadmin
permissions, the upgrade will fail and Azure AD Connect will no longer function correctly afterwards. Microsoft is aware of
this and is working to correct this.

PRINCIPAL PERMISSIONS REQUIRED USED FOR

User running the installation wizard Administrator of the local server Update binaries.

User running the installation wizard Member of ADSyncAdmins Make changes to Sync Rules and other
configuration.

User running the installation wizard If you use a full SQL server: DBO (or Make database level changes, such as
similar) of the sync engine database updating tables with new columns.

More about the created accounts


Active Directory account
If you use express settings, then an account is created in Active Directory that is used for synchronization. The
created account is located in the forest root domain in the Users container and has its name prefixed with MSOL_.
The account is created with a long complex password that does not expire. If you have a password policy in your
domain, make sure long and complex passwords would be allowed for this account.

If you use custom settings, then you are responsible for creating the account before you start the installation.
Azure AD Connect sync service account
The sync service can run under different accounts. It can run under a Virtual Service Account (VSA), a Group
Managed Service Account (gMSA/sMSA), or a regular user account. The supported options were changed with
the 2017 April release of Connect when you do a fresh installation. If you upgrade from an earlier release of Azure
AD Connect, these additional options are not available.

TYPE OF ACCOUNT INSTALLATION OPTION DESCRIPTION

Virtual Service Account Express and custom, 2017 April and This is the option used for all express
later installations, except for installations on
a Domain Controller. For custom, it is
the default option unless another
option is used.

Group Managed Service Account Custom, 2017 April and later If you use a remote SQL server, then
we recommend to use a group
managed service account.

User account Express and custom, 2017 April and A user account prefixed with AAD_ is
later only created during installation when
installed on Windows Server 2008 and
when installed on a Domain Controller.

User account Express and custom, 2017 March and A local account prefixed with AAD_ is
earlier created during installation. When using
custom installation, another account
can be specified.

If you use Connect with a build from 2017 March or earlier, then you should not reset the password on the service
account since Windows destroys the encryption keys for security reasons. You cannot change the account to any
other account without reinstalling Azure AD Connect. If you upgrade to a build from 2017 April or later, then it is
supported to change the password on the service account but you cannot change the account used.

IMPORTANT
You can only set the service account on first installation. It is not supported to change the service account after the
installation has completed.

This is a table of the default, recommended, and supported options for the sync service account.
Legend:
Bold indicates the default option and in most cases the recommended option.
Italic indicates the recommended option when it is not the default option.
2008 - Default option when installed on Windows Server 2008
Non-bold - Supported option
Local account - Local user account on the server
Domain account - Domain user account
sMSA - standalone Managed Service account
gMSA - group Managed Service account
LOCALDB LOCALDB/LOCALSQL REMOTE SQL
EXPRESS CUSTOM CUSTOM

standalone/workgroup Not supported VSA Not supported


machine Local account (2008)
Local account

domain-joined machine VSA VSA gMSA


Local account (2008) Local account (2008) Domain account
Local account
Domain account
sMSA,gMSA

Domain Controller Domain account gMSA gMSA


Domain account Domain account
sMSA

Virtual service account


A virtual service account is a special type of account that does not have a password and is managed by Windows.

The VSA is intended to be used with scenarios where the sync engine and SQL are on the same server. If you use
remote SQL, then we recommend to use a Group Managed Service Account instead.
This feature requires Windows Server 2008 R2 or later. If you install Azure AD Connect on Windows Server 2008,
then the installation falls back to using a user account instead.
Group managed service account
If you use a remote SQL server, then we recommend to using a group managed service account. For more
information on how to prepare your Active Directory for Group Managed Service account, see Group Managed
Service Accounts Overview.
To use this option, on the Install required components page, select Use an existing service account, and select
Managed Service Account.

It is also supported to use a standalone managed service account. However, these can only be used on the local
machine and there is no benefit to use them over the default virtual service account.
This feature requires Windows Server 2012 or later. If you need to use an older operating system and use remote
SQL, then you must use a user account.
User account
A local service account is created by the installation wizard (unless you specify the account to use in custom
settings). The account is prefixed AAD_ and used for the actual sync service to run as. If you install Azure AD
Connect on a Domain Controller, the account is created in the domain. The AAD_ service account must be located
in the domain if:
you use a remote server running SQL server
you use a proxy that requires authentication
The account is created with a long complex password that does not expire.
This account is used to store the passwords for the other accounts in a secure way. These other accounts
passwords are stored encrypted in the database. The private keys for the encryption keys are protected with the
cryptographic services secret-key encryption using Windows Data Protection API (DPAPI).
If you use a full SQL Server, then the service account is the DBO of the created database for the sync engine. The
service will not function as intended with any other permissions. A SQL login is also created.
The account is also granted permissions to files, registry keys, and other objects related to the Sync Engine.
Azure AD service account
An account in Azure AD is created for the sync service's use. This account can be identified by its display name.

The name of the server the account is used on can be identified in the second part of the user name. In the picture,
the server name is FABRIKAMCON. If you have staging servers, each server has its own account.
The service account is created with a long complex password that does not expire. It is granted a special role
Directory Synchronization Accounts that has only permissions to perform directory synchronization tasks. This
special built-in role cannot be granted outside of the Azure AD Connect wizard. The Azure portal shows this
account with the role User.
There is a limit of 20 sync service accounts in Azure AD. To get the list of existing Azure AD service accounts in
your Azure AD, run the following Azure AD PowerShell cmdlet:
Get-AzureADDirectoryRole | where {$_.DisplayName -eq "Directory Synchronization Accounts"} | Get-
AzureADDirectoryRoleMember

To remove unused Azure AD service accounts, run the following Azure AD PowerShell cmdlet:
Remove-AzureADUser -ObjectId <ObjectId-of-the-account-you-wish-to-remove>

Next steps
Learn more about Integrating your on-premises identities with Azure Active Directory.
Azure AD Connect sync: Attributes synchronized to
Azure Active Directory
3/6/2018 • 12 min to read • Edit Online

This topic lists the attributes that are synchronized by Azure AD Connect sync.
The attributes are grouped by the related Azure AD app.

Attributes to synchronize
A common question is what is the list of minimum attributes to synchronize. The default and recommended
approach is to keep the default attributes so a full GAL (Global Address List) can be constructed in the cloud and to
get all features in Office 365 workloads. In some cases, there are some attributes that your organization does not
want synchronized to the cloud since these attributes contain sensitive or PII (Personally identifiable information)
data, like in this example:

In this case, start with the list of attributes in this topic and identify those attributes that would contain sensitive or
PII data and cannot be synchronized. Then deselect those attributes during installation using Azure AD app and
attribute filtering.

WARNING
When deselecting attributes, you should be cautious and only deselect those attributes absolutely not possible to
synchronize. Unselecting other attributes might have a negative impact on features.

Office 365 ProPlus


ATTRIBUTE NAME USER COMMENT

accountEnabled X Defines if an account is enabled.

cn X

displayName X

objectSID X mechanical property. AD user identifier


used to maintain sync between Azure
AD and AD.
ATTRIBUTE NAME USER COMMENT

pwdLastSet X mechanical property. Used to know


when to invalidate already issued
tokens. Used by both password sync
and federation.

sourceAnchor X mechanical property. Immutable


identifier to maintain relationship
between ADDS and Azure AD.

usageLocation X mechanical property. The user’s country.


Used for license assignment.

userPrincipalName X UPN is the login ID for the user. Most


often the same as [mail] value.

Exchange Online
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

assistant X X

altRecipient X Requires Azure AD


Connect build
1.1.552.0 or after.

authOrig X X X

c X X

cn X X

co X X

company X X

countryCode X X

department X X

description X X X

displayName X X X

dLMemRejectPerms X X X

dLMemSubmitPerms X X X

extensionAttribute1 X X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

extensionAttribute10 X X X

extensionAttribute11 X X X

extensionAttribute12 X X X

extensionAttribute13 X X X

extensionAttribute14 X X X

extensionAttribute15 X X X

extensionAttribute2 X X X

extensionAttribute3 X X X

extensionAttribute4 X X X

extensionAttribute5 X X X

extensionAttribute6 X X X

extensionAttribute7 X X X

extensionAttribute8 X X X

extensionAttribute9 X X X

facsimiletelephonenu X X
mber

givenName X X

homePhone X X

info X X X This attribute is


currently not
consumed for groups.

Initials X X

l X X

legacyExchangeDN X X X

mailNickname X X X

managedBy X

manager X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

member X

mobile X X

msDS- X X X
HABSeniorityIndex

msDS- X X X
PhoneticDisplayName

msExchArchiveGUID X

msExchArchiveName X

msExchAssistantName X X

msExchAuditAdmin X

msExchAuditDelegate X

msExchAuditDelegate X
Admin

msExchAuditOwner X

msExchBlockedSender X X
sHash

msExchBypassAudit X

msExchBypassModera X Available in Azure AD


tionLink Connect version
1.1.524.0

msExchCoManagedBy X
Link

msExchDelegateListLi X
nk

msExchELCExpirySusp X
ensionEnd

msExchELCExpirySusp X
ensionStart

msExchELCMailboxFla X
gs

msExchEnableModera X X
tion
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

msExchExtensionCust X X X This attribute is


omAttribute1 currently not
consumed by
Exchange Online.

msExchExtensionCust X X X This attribute is


omAttribute2 currently not
consumed by
Exchange Online.

msExchExtensionCust X X X This attribute is


omAttribute3 currently not
consumed by
Exchange Online.

msExchExtensionCust X X X This attribute is


omAttribute4 currently not
consumed by
Exchange Online.

msExchExtensionCust X X X This attribute is


omAttribute5 currently not
consumed by
Exchange Online.

msExchHideFromAddr X X X
essLists

msExchImmutableID X

msExchLitigationHold X X X
Date

msExchLitigationHold X X X
Owner

msExchMailboxAuditE X
nable

msExchMailboxAuditL X
ogAgeLimit

msExchMailboxGuid X

msExchModeratedByL X X X
ink

msExchModerationFla X X X
gs

msExchRecipientDispl X X X
ayType

msExchRecipientType X X X
Details
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

msExchRemoteRecipie X
ntType

msExchRequireAuthTo X X X
SendTo

msExchResourceCapa X
city

msExchResourceDispl X
ay

msExchResourceMeta X
Data

msExchResourceSearc X
hProperties

msExchRetentionCom X X X
ment

msExchRetentionURL X X X

msExchSafeRecipients X X
Hash

msExchSafeSendersHa X X
sh

msExchSenderHintTra X X X
nslations

msExchTeamMailboxE X
xpiration

msExchTeamMailbox X
Owners

msExchTeamMailboxS X
harePointUrl

msExchUserHoldPolici X
es

msOrg- X
IsOrganizational
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

objectSID X X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.

oOFReplyToOriginato X
r

otherFacsimileTelepho X X
ne

otherHomePhone X X

otherTelephone X X

pager X X

physicalDeliveryOffice X X
Name

postalCode X X

proxyAddresses X X X

publicDelegates X X X

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens. Used
by both password
sync and federation.

reportToOriginator X

reportToOwner X

securityEnabled X Derived from


groupType

sn X X

sourceAnchor X X X mechanical property.


Immutable identifier
to maintain
relationship between
ADDS and Azure AD.

st X X

streetAddress X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

targetAddress X X

telephoneAssistant X X

telephoneNumber X X

thumbnailphoto X X

title X X

unauthOrig X X X

usageLocation X mechanical property.


The user’s country.
Used for license
assignment.

userCertificate X X

userPrincipalName X UPN is the login ID


for the user. Most
often the same as
[mail] value.

userSMIMECertificate X X
s

wWWHomePage X X

SharePoint Online
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

authOrig X X X

c X X

cn X X

co X X

company X X

countryCode X X

department X X

description X X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

displayName X X X

dLMemRejectPerms X X X

dLMemSubmitPerms X X X

extensionAttribute1 X X X

extensionAttribute10 X X X

extensionAttribute11 X X X

extensionAttribute12 X X X

extensionAttribute13 X X X

extensionAttribute14 X X X

extensionAttribute15 X X X

extensionAttribute2 X X X

extensionAttribute3 X X X

extensionAttribute4 X X X

extensionAttribute5 X X X

extensionAttribute6 X X X

extensionAttribute7 X X X

extensionAttribute8 X X X

extensionAttribute9 X X X

facsimiletelephonenu X X
mber

givenName X X

hideDLMembership X

homephone X X

info X X X

initials X X

ipPhone X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

l X X

mail X X X

mailnickname X X X

managedBy X

manager X X

member X

middleName X X

mobile X X

msExchTeamMailboxE X
xpiration

msExchTeamMailbox X
Owners

msExchTeamMailboxS X
harePointLinkedBy

msExchTeamMailboxS X
harePointUrl

objectSID X X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.

oOFReplyToOriginato X
r

otherFacsimileTelepho X X
ne

otherHomePhone X X

otherIpPhone X X

otherMobile X X

otherPager X X

otherTelephone X X

pager X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

physicalDeliveryOffice X X
Name

postalCode X X

postOfficeBox X X This attribute is


currently not
consumed by
SharePoint Online.

preferredLanguage X

proxyAddresses X X X

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens. Used
by both password
sync and federation.

reportToOriginator X

reportToOwner X

securityEnabled X Derived from


groupType

sn X X

sourceAnchor X X X mechanical property.


Immutable identifier
to maintain
relationship between
ADDS and Azure AD.

st X X

streetAddress X X

targetAddress X X

telephoneAssistant X X

telephoneNumber X X

thumbnailphoto X X

title X X

unauthOrig X X X

url X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

usageLocation X mechanical property.


The user’s country.
Used for license
assignment.

userPrincipalName X UPN is the login ID


for the user. Most
often the same as
[mail] value.

wWWHomePage X X

Lync Online (subsequently known as Skype for Business)


ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

c X X

cn X X

co X X

company X X

department X X

description X X X

displayName X X X

facsimiletelephonenu X X X
mber

givenName X X

homephone X X

ipPhone X X

l X X

mail X X X

mailNickname X X X

managedBy X

manager X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

member X

mobile X X

msExchHideFromAddr X X X
essLists

msRTCSIP- X
ApplicationOptions

msRTCSIP- X X
DeploymentLocator

msRTCSIP-Line X X

msRTCSIP- X X
OptionFlags

msRTCSIP-OwnerUrn X

msRTCSIP- X X
PrimaryUserAddress

msRTCSIP- X X
UserEnabled

objectSID X X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.

otherTelephone X X

physicalDeliveryOffice X X
Name

postalCode X X

preferredLanguage X

proxyAddresses X X X

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens. Used
by both password
sync and federation.

securityEnabled X Derived from


groupType
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

sn X X

sourceAnchor X X X mechanical property.


Immutable identifier
to maintain
relationship between
ADDS and Azure AD.

st X X

streetAddress X X

telephoneNumber X X

thumbnailphoto X X

title X X

usageLocation X mechanical property.


The user’s country.
Used for license
assignment.

userPrincipalName X UPN is the login ID


for the user. Most
often the same as
[mail] value.

wWWHomePage X X

Azure RMS
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

cn X X Common name or
alias. Most often the
prefix of [mail] value.

displayName X X X A string that


represents the name
often shown as the
friendly name (first
name last name).

mail X X X full email address.

member X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

objectSID X X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.

proxyAddresses X X X mechanical property.


Used by Azure AD.
Contains all
secondary email
addresses for the
user.

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens.

securityEnabled X Derived from


groupType.

sourceAnchor X X X mechanical property.


Immutable identifier
to maintain
relationship between
ADDS and Azure AD.

usageLocation X mechanical property.


The user’s country.
Used for license
assignment.

userPrincipalName X This UPN is the login


ID for the user. Most
often the same as
[mail] value.

Intune
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

c X X

cn X X

description X X X

displayName X X X

mail X X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

mailnickname X X X

member X

objectSID X X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.

proxyAddresses X X X

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens. Used
by both password
sync and federation.

securityEnabled X Derived from


groupType

sourceAnchor X X X mechanical property.


Immutable identifier
to maintain
relationship between
ADDS and Azure AD.

usageLocation X mechanical property.


The user’s country.
Used for license
assignment.

userPrincipalName X UPN is the login ID


for the user. Most
often the same as
[mail] value.

Dynamics CRM
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

c X X

cn X X

co X X

company X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

countryCode X X

description X X X

displayName X X X

facsimiletelephonenu X X
mber

givenName X X

l X X

managedBy X

manager X X

member X

mobile X X

objectSID X X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.

physicalDeliveryOffice X X
Name

postalCode X X

preferredLanguage X

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens. Used
by both password
sync and federation.

securityEnabled X Derived from


groupType

sn X X

sourceAnchor X X X mechanical property.


Immutable identifier
to maintain
relationship between
ADDS and Azure AD.

st X X
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

streetAddress X X

telephoneNumber X X

title X X

usageLocation X mechanical property.


The user’s country.
Used for license
assignment.

userPrincipalName X UPN is the login ID


for the user. Most
often the same as
[mail] value.

3rd party applications


This group is a set of attributes used as the minimal attributes needed for a generic workload or application. It can
be used for a workload not listed in another section or for a non-Microsoft app. It is explicitly used for the
following:
Yammer (only User is consumed)
Hybrid Business-to-Business (B2B) cross-org collaboration scenarios offered by resources like SharePoint
This group is a set of attributes that can be used if the Azure AD directory is not used to support Office 365,
Dynamics, or Intune. It has a small set of core attributes.

ATTRIBUTE NAME USER CONTACT GROUP COMMENT

accountEnabled X Defines if an account


is enabled.

cn X X

displayName X X X

givenName X X

mail X X

managedBy X

mailNickName X X X

member X

objectSID X mechanical property.


AD user identifier
used to maintain sync
between Azure AD
and AD.
ATTRIBUTE NAME USER CONTACT GROUP COMMENT

proxyAddresses X X X

pwdLastSet X mechanical property.


Used to know when
to invalidate already
issued tokens. Used