Microsoft Entra Connect: Configure AD DS Connector Account Permissions

The PowerShell module named ADSyncConfig.psm1 was introduced with build 1.1.880.0 (released in August 2018) that includes a collection of cmdlets to help you configure the correct Active Directory permissions for your Microsoft Entra Connect deployment.

Overview

The following PowerShell cmdlets can be used to setup Active Directory permissions of the AD DS Connector account, for each feature that you select to enable in Microsoft Entra Connect. To prevent any issues, you should prepare Active Directory permissions in advance whenever you want to install Microsoft Entra Connect using a custom domain account to connect to your forest. This ADSyncConfig module can also be used to configure permissions after Microsoft Entra Connect is deployed.

For Microsoft Entra Connect Express installation, an automatically generated account (MSOL_nnnnnnnnnn) is created in Active Directory with all the necessary permissions, so there’s no need to use this ADSyncConfig module unless you have blocked permissions inheritance on organizational units or on specific Active Directory objects that you want to synchronize to Microsoft Entra ID.

Permissions summary

The following table provides a summary of the permissions required on AD objects:

Feature	Permissions
ms-DS-ConsistencyGuid feature	Read and Write permissions to the ms-DS-ConsistencyGuid attribute documented in Design Concepts - Using ms-DS-ConsistencyGuid as sourceAnchor.
Password hash sync	Replicate Directory Changes - required for basic read only Replicate Directory Changes All
Exchange hybrid deployment	Read and 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	Read and Write permissions to the attributes documented in Getting started with password management for users.
Device writeback	Read and Write permissions to device objects and containers documented in device writeback.
Group writeback	Read, Create, Update, and Delete group objects for synchronized Office 365 groups.

Using the ADSyncConfig PowerShell module

The ADSyncConfig module requires the Remote Server Administration Tools (RSAT) for AD DS since it depends on the AD DS PowerShell module and tools. To install RSAT for AD DS, open a Windows PowerShell window with ‘Run As Administrator’ and execute:

Install-WindowsFeature RSAT-AD-Tools 

To start using the ADSyncConfig you need to load the module in a Windows PowerShell window:

Import-Module "C:\Program Files\Azure Active Directory Connect\AdSyncConfig\AdSyncConfig.psm1" 

To check all the cmdlets included in this module you can type:

Get-Command -Module AdSyncConfig  

Each cmdlet has the same parameters to input the AD DS Connector Account and an AdminSDHolder switch. To specify your AD DS Connector Account, you can provide the account name and domain, or just the account Distinguished Name (DN),

e.g., :

Set-ADSyncPasswordHashSyncPermissions -ADConnectorAccountName <ADAccountName> -ADConnectorAccountDomain <ADDomainName>

Or;

Set-ADSyncPasswordHashSyncPermissions -ADConnectorAccountDN <ADAccountDN>

Make sure to replace <ADAccountName>, <ADDomainName> and <ADAccountDN> with the proper values for your environment.

In case you want to modify permissions on the AdminSDHolder container, use the switch -IncludeAdminSdHolders. Note that this is not recommended.

By default, all the set permissions cmdlets will try to set AD DS permissions on the root of each Domain in the Forest, meaning that the user running the PowerShell session requires Domain Administrator rights on each domain in the Forest. Because of this requirement, it is recommended to use an Enterprise Administrator from the Forest root. If your Microsoft Entra Connect deployment has multiple AD DS Connectors, it will be required to run the same cmdlet on each forest that has an AD DS Connector.

You can also set permissions on a specific OU or AD DS object by using the parameter -ADobjectDN followed by the DN of the target object where you want to set permissions. When using a target ADobjectDN, the cmdlet will set permissions on this object only and not on the domain root or AdminSDHolder container. This parameter can be useful when you have certain OUs or AD DS objects that have permission inheritance disabled (see Locate AD DS objects with permission inheritance disabled)

Exceptions to these common parameters are the Set-ADSyncRestrictedPermissions cmdlet which is used to set the permissions on the AD DS Connector Account itself, and the Set-ADSyncPasswordHashSyncPermissions cmdlet since the permissions required for Password Hash Sync are only set at the domain root, hence this cmdlet does not include the -ObjectDN or -IncludeAdminSdHolders parameters.

Determine your AD DS Connector Account

In case Microsoft Entra Connect is already installed and you want to check what is the AD DS Connector Account currently in use by Microsoft Entra Connect, you can execute the cmdlet:

Get-ADSyncADConnectorAccount 

Locate AD DS objects with permission inheritance disabled

In case you want to check if there is any AD DS object with permission inheritance disabled, you can run:

Get-ADSyncObjectsWithInheritanceDisabled -SearchBase '<DistinguishedName>' 

By default, this cmdlet will only look for OUs with disabled inheritance, but you can specify other AD DS object classes in -ObjectClass parameter or use ‘*’ for all object classes, as follows:

Get-ADSyncObjectsWithInheritanceDisabled -SearchBase '<DistinguishedName>' -ObjectClass * 

View AD DS permissions of an object

You can use the cmdlet below to view the list of permissions currently set on an Active Directory object by providing its DistinguishedName:

Show-ADSyncADObjectPermissions -ADobjectDN '<DistinguishedName>' 

Configure AD DS Connector Account Permissions

Configure Basic Read-Only Permissions

To set basic read-only permissions for the AD DS Connector account when not using any Microsoft Entra Connect feature, run:

Set-ADSyncBasicReadPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [-IncludeAdminSdHolders] [<CommonParameters>] 

or;

Set-ADSyncBasicReadPermissions -ADConnectorAccountDN <String> [-ADobjectDN <String>] [<CommonParameters>] 

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Read all properties	Descendant device objects
Allow	AD DS Connector Account	Read all properties	Descendant InetOrgPerson objects
Allow	AD DS Connector Account	Read all properties	Descendant Computer objects
Allow	AD DS Connector Account	Read all properties	Descendant foreignSecurityPrincipal objects
Allow	AD DS Connector Account	Read all properties	Descendant Group objects
Allow	AD DS Connector Account	Read all properties	Descendant User objects
Allow	AD DS Connector Account	Read all properties	Descendant Contact objects
Allow	AD DS Connector Account	Replicating Directory Changes	This object only (Domain root)

Configure MS-DS-Consistency-Guid Permissions

To set permissions for the AD DS Connector account when using the ms-Ds-Consistency-Guid attribute as the source anchor (also known as “Let Azure manage the source anchor for me” option), run:

Set-ADSyncMsDsConsistencyGuidPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [-IncludeAdminSdHolders] [<CommonParameters>] 

or;

Set-ADSyncMsDsConsistencyGuidPermissions -ADConnectorAccountDN <String> [-ADobjectDN <String>] [<CommonParameters>] 

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Read/Write property	Descendant User objects

Permissions for Password Hash Synchronization

To set permissions for the AD DS Connector account when using Password Hash Synchronization, run:

Set-ADSyncPasswordHashSyncPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [<CommonParameters>] 

or;

Set-ADSyncPasswordHashSyncPermissions -ADConnectorAccountDN <String> [<CommonParameters>] 

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Replicating Directory Changes	This object only (Domain root)
Allow	AD DS Connector Account	Replicating Directory Changes All	This object only (Domain root)

Permissions for Password Writeback

To set permissions for the AD DS Connector account when using Password Writeback, run:

Set-ADSyncPasswordWritebackPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [-IncludeAdminSdHolders] [<CommonParameters>] 

or;

Set-ADSyncPasswordWritebackPermissions -ADConnectorAccountDN <String> [-ADobjectDN <String>] [<CommonParameters>] 

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Reset Password	Descendant User objects
Allow	AD DS Connector Account	Write property lockoutTime	Descendant User objects
Allow	AD DS Connector Account	Write property pwdLastSet	Descendant User objects

Permissions for Group Writeback

To set permissions for the AD DS Connector account when using Group Writeback, run:

Set-ADSyncUnifiedGroupWritebackPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [-IncludeAdminSdHolders] [<CommonParameters>] 

or;

Set-ADSyncUnifiedGroupWritebackPermissions -ADConnectorAccountDN <String> [-ADobjectDN <String>] [<CommonParameters>]

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Generic Read/Write	All attributes of object type group and subobjects
Allow	AD DS Connector Account	Create/Delete child object	All attributes of object type group and subobjects
Allow	AD DS Connector Account	Delete/Delete tree objects	All attributes of object type group and subobjects

Permissions for Exchange Hybrid Deployment

To set permissions for the AD DS Connector account when using Exchange Hybrid deployment, run:

Set-ADSyncExchangeHybridPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [-IncludeAdminSdHolders] [<CommonParameters>] 

or;

Set-ADSyncExchangeHybridPermissions -ADConnectorAccountDN <String> [-ADobjectDN <String>] [<CommonParameters>] 

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Read/Write all properties	Descendant User objects
Allow	AD DS Connector Account	Read/Write all properties	Descendant InetOrgPerson objects
Allow	AD DS Connector Account	Read/Write all properties	Descendant Group objects
Allow	AD DS Connector Account	Read/Write all properties	Descendant Contact objects

Permissions for Exchange Mail Public Folders

To set permissions for the AD DS Connector account when using Exchange Mail Public Folders feature, run:

Set-ADSyncExchangeMailPublicFolderPermissions -ADConnectorAccountName <String> -ADConnectorAccountDomain <String> [-IncludeAdminSdHolders] [<CommonParameters>] 

or;

Set-ADSyncExchangeMailPublicFolderPermissions -ADConnectorAccountDN <String> [-ADobjectDN <String>] [<CommonParameters>] 

This cmdlet will set the following permissions:

Type	Name	Access	Applies To
Allow	AD DS Connector Account	Read all properties	Descendant PublicFolder objects

Restrict Permissions on the AD DS Connector Account

This PowerShell script will tighten permissions for the AD Connector Account provided as a parameter. Tightening permissions involves the following steps:

• Disable inheritance on the specified object

• Remove all ACEs on the specific object, except ACEs specific to SELF as we want to keep the default permissions intact when it comes to SELF.

  The -ADConnectorAccountDN parameter is the AD account whose permissions need to be tightened. This is typically the MSOL_nnnnnnnnnnnn domain account that is configured in the AD DS Connector (see Determine your AD DS Connector Account). The -Credential parameter is necessary to specify the Administrator account that has the necessary privileges to restrict Active Directory permissions on the target AD object (this account must be different from the ADConnectorAccountDN account). This is typically the Enterprise or Domain Administrator.

Set-ADSyncRestrictedPermissions [-ADConnectorAccountDN] <String> [-Credential] <PSCredential> [-DisableCredentialValidation] [-WhatIf] [-Confirm] [<CommonParameters>] 

For Example:

$credential = Get-Credential 
Set-ADSyncRestrictedPermissions -ADConnectorAccountDN 'CN=ADConnectorAccount,OU=Users,DC=Contoso,DC=com' -Credential $credential  

This cmdlet will set the following 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 Controllers	List Contents	This object
Allow	Enterprise Domain Controllers	Read All Properties	This object
Allow	Enterprise Domain Controllers	Read Permissions	This object
Allow	Authenticated Users	List Contents	This object
Allow	Authenticated Users	Read All Properties	This object
Allow	Authenticated Users	Read Permissions	This object

Next Steps

• Microsoft Entra Connect: Accounts and permissions
• Express Installation
• Custom Installation
• ADSyncConfig Reference