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 | |
| 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
Note
You can also copy the file C:\Program Files\Microsoft Entra Connect\AdSyncConfig\ADSyncConfig.psm1 to a Domain Controller which already has RSAT for AD DS installed and use this PowerShell module from there. Be aware that some of the cmdlets can only be run on the computer that is hosting Microsoft Entra Connect.
To start using the ADSyncConfig you need to load the module in a Windows PowerShell window:
Import-Module "C:\Program Files\Microsoft 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 |