It may become necessary to purge an object an Entra Connect connector space. A connector space exists for each directory that is added to an Entra Connect installation. Typical installations have two connector spaces, one for the local Active Directory and the other for Entra ID. More complex installations may have more than one connector space for Active Director.
When a user object is synchronized to Entra ID the Active Directory attributes are read into the Active Directory connector space. When the object is successfully written to Entra ID, the Entra ID attributes are read into the Entra ID connector space.
In some instances, it becomes necessary to purge the information within a connector space in order to fix a synchronization issue. Purging an object from a connector space allows the Entra Connect process to re-read the objects properties from the directory where the deletion occurred. For example, purging an object from the Active Directory and Entra ID connector spaces will force the object to be re-read from both directories and sync operation performed on the refreshed attributes. It is also possible to remove an object from either of the connector spaces without removing it from both.
To facilitate this process, I have released a script to the Powershell Gallery that automates the remove of the object from one or both connector spaces. The script offers several options to execute.
To save this script to your entra connect server perform the following:
Install-Script Reset-EntraConnectObjectThis saves the scripts to the local path.
The script provides a variety of options for execution each performing slightly different functions.
Option 1:
This option is used when the Active Directory and Entra Connect distinguished names are both known. This information is generally obtained from a metaverse search and copying the respective distinguished names from the connector spaces. When executed the connector space objects are extracted by distinguished name and a deletion from the connector spaces is processed. A single item synchronization is automatically triggered to refresh each connector space with the objects properies.
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -EntraDN "CN={4272736E37395A7742456D3474535578366A746558413D3D}" -ADObjectDN "CN=Tim McMichael,OU=Users,OU=Objects,DC=home,DC=domain,DC=com"Option 2
This option is used when only Active Directory information is known, and an object deletion should occur from both the Active Directory and Entra connector spaces. When executed an Active Directory call is made to locate the user by either distinguished name, objectGUID, or mail attribute. This call is made using the specified domain controller and credentials. When the user is located the sourceAnchor for the Entra Connect installation is determined and the Entra ID distinguished name is automatically calculated. A deletion from each connector space is processed. A single item synchronization is automatically triggered to refresh each connector space with the object properties. This is helpful if you only have access to the Active Directory information or are unable to perform a metaverse search to determine distinguished name values.
#If get-credential returns an error message "Get-Credential : Cannot process command because of one or more missing mandatory parameters: Credential" do the following:
Set-ItemProperty "HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds" -Name "ConsolePrompting" -Value $TrueOption 2A: Remove object by Active Directory Distinguished Name
#The following instructions locate the object by Active Directory Distinguished Name
$cred = get-credential #Provide credential of person with rights to read attributes from active directory
$globalCatalogServer = "DC.domain.com" #FQDN of a global catalog server
$DN = "CN=Tim McMichael,OU=Users,OU=Objects,DC=home,DC=domain,DC=com"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectDN $dn -globalCatalogServer $globalCatalogServer -activeDirectoryCredential $credOption 2B: Remove object by Active Directory Mail Attribute
#The following instructions locate the object by Active Directory Mail Attribute
$cred = get-credential #Provide credential of person with rights to read attributes from active directory
$mail = "tim@domain.com" #Active directory mail attribute
$globalCatalogServer = "DC.Domain.com"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectmail $mail -activeDirectoryCredential $cred -globalCatalogServer $globalCatalogServerOption 2C: Remove object by Active Directory ObjectGUID
#The following instructions locate the object by Active Directory objectGUID
$cred = get-credential #Provide credential of person with rights to read attributes from active directory
$globalCatalogServer = "DC.domain.com" #FQDN of a global catalog server
$objectGUID = "ef27bb06-70d6-4904-b8b5-2531ea3b5e5c"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectGUID $objectGUID -activeDirectoryCredential $cred -globalCatalogServer $globalCatalogServerOption 3
This option is utilized when you only want to purge information from the Active Directory connector space. Generally, this is reserved for specific scenarios under the guidance of support. It functions in the same manner as Option 2 with the exception that no Entra ID distinguished name is calculated.
Option 3A: Remove object by Active Directory Distinguished Name
#The following instructions locate the object by Active Directory Distinguished Name
$cred = get-credential #Provide credential of person with rights to read attributes from active directory
$globalCatalogServer = "DC.domain.com" #FQDN of a global catalog server
$DN = "CN=Tim McMichael,OU=Users,OU=Objects,DC=home,DC=domain,DC=com"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectDN $dn -globalCatalogServer $globalCatalogServer -activeDirectoryCredential $cred -calculateEntraDN:$FALSEOption 3B: Remove object by Active Directory Mail Attribute
#The following instructions locate the object by Active Directory Mail Attribute
$cred = get-credential #Provide credential of person with rights to read attributes from active directory
$mail = "tim@domain.com" #Active directory mail attribute
$globalCatalogServer = "DC.Domain.com"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectmail $mail -activeDirectoryCredential $cred -globalCatalogServer $globalCatalogServer -calculateEntraDN:$FALSEOption 3C: Remove object by Active Directory ObjectGUID
#The following instructions locate the object by Active Directory objectGUID
$cred = get-credential #Provide credential of person with rights to read attributes from active directory
$globalCatalogServer = "DC.domain.com" #FQDN of a global catalog server
$objectGUID = "ef27bb06-70d6-4904-b8b5-2531ea3b5e5c"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectGUID $objectGUID -activeDirectoryCredential $cred -globalCatalogServer $globalCatalogServer -calculateEntraDN:$FALSEOption 4
This option is utilized when you only want to purge information from the Entra ID connector space. Generally, this is reserved for specific scenarios under the guidance of support. The Entra ID distinguished name is determined by locating the object in the connector space and copying the distinguished name value. Note that this option triggers a delta synchronization when the process is complete.
$dn = "CN={4272736E37395A7742456D3474535578366A746558413D3D}"
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -EntraDN $dnOption 5
This option is utilized when more than one Active Directory connector space is present. If the script detects the presence of more than on Active Directory connector space an error is returned. The connector space name must be specified when running the command to ensure that the desired object is deleted. Depending on the scenario it may be necessary to not perform the single item sync until an object is deleted from all connector spaces.
In this example the user exists in the Active Directory home.domain.com and domain.local. (This is typical for example in a resource forest scenario). To complete purge this object the object must be purged from three connector spaces. The distinguished names were obtained through a metaverse search.
The first command purges the object from one Active Directory connector space and the Entra ID connector space. Note that single object sync is not performed as the object still exists in the second Active Directory connector space.
The second command purges the object from the second Active Directory connector space. At the conclusion of this command the full object sync should be allowed to run (which is the default).
I recommend running these as a single code block to eliminate the possibility that a sync cycle could occur inbetween.
#Establish the DN for the first forest.
$adDN = "CN=Tim McMichael,OU=Users,OU=Objects,DC=home,DC=domain,DC=com"
#Establish the DN for the second forest.
$otherADDN = "CN=Tim McMichael,OU=Users,OU=Objects,DC=domain,DC=local"
#Establish the EntraDN from the metaverse search.
$entraDN = "CN={4272736E37395A7742456D3474535578366A746558413D3D}"
#Provide the connector name for the first forest.
$adConnectorName = "domain.com"
#Provide the connector name for the second forest.
$otherADConnectorName = "domain.local"
#Remove the object from the entra connector space
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -entraDN $entraDN
#Remove the object from the first active directory forest.
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectDN $adDN -skipSingleItemSync:$TRUE -ADConnectorName $adConnectorName -calculateEntraDN:$FALSE
#Remove the object from the second active directory forest and perform a single object sync.
reset-EntraConnectObject.ps1 -logFolderPath c:\temp -ADObjectDN $otherADDN -CalculateEntraDN:$FALSE -ADConnectorName $otherADConnectorNameOther information…
For each operation run a folder is created in the log path directory specified. The folder is a file date time stamp. Inside this folder is the operation log file and XML file extractions of all objects discovered during the connector space deletions. If a full single item sync was executed a JSONsummary file of the sync operation is also included in this directory.
I hope this script allows administrators to purge objects from connector spaces for troubleshooting or issue resolution easily.
TIMMCMIC 