Recently I came across a scenario where a customer had been running two on premises AD forests. Each domain contained users from different sections of the organisation with both synced to the same Entra tenant. Over time the administrative overhead of maintaining two forests became increasingly cumbersome, prompting the customer to investigate merging the two.
While the process of moving users between AD forests using the AD migration tool is relatively straightforward, I had struggled to find any documentation on how to ensure the migrated users would continue to match up with their Entra ID counterparts.
How Entra Connect Identifies Users
When the synchronization service identifies a new user account in Active Directory it will pass the user attributes to Entra ID to create a new user. One of these attributes is “sourceAnchor” which by default is a base64 encoded copy of the on premises user’s GUID.
While the sourceAnchor is based on the user’s GUID, it does not map directly to the GUID. This will be useful later as it will allow us to match up the account with a new on premises account. Instead, the sourceAnchor maps to “mS-DS-ConsistencyGuid” in on premises AD. The value here does not exactly match that in “sourceAnchor” as the “sourceAnchor” is base64 encoded and “mS-DS-ConsistencyGuid” is hex encoded but if converted to the same format they will be the same. Note, “mS-DS-ConsistencyGuid” is only populated after the second sync cycle so for the below process to work, the user must have existed for at least 2 sync cycles. This will be true for almost all production cases but is worth bearing in mind for testing.
One other important factor to note about the second sync is that for the on premises delta import, we also see an Add operation corresponding to our user account. If we look in the attributes for this sync we see that the object does not contain “mS-DS-ConsistencyGuid”. This is because the purpose of this operation is not to write data back to AD, it is to confirm to the sync service that the previous add operation has been successful. If it does not see the original object returned it will assume that the original export has failed and attempt it again.
Migrating a User
As we have seen, when the Entra Sync Service runs it will match on premises and cloud users based on their “mS-DS-ConsistencyGuid”. This means that if we want to sync an Entra ID user with a different on premises user we simply need to ensure that the new on premises user has the same “mS-DS-ConsistencyGuid”. Our other concern is that we do not want the Synchronization Service in multiple directories to be syncing the same user. If this were to happen, each time a sync ran, that directory’s attributes would overwrite the other directory’s attributes causing the account to flip flop between two states.
Prerequisites
Prior to beginning a user migration there are some prerequisites to check. These will simplify the process and reduce the risk of errors or duplicated accounts.
The first prerequisite to check is that the source anchor is actually set to “mS-DS-ConsistencyGuid”. This is the default configuration but can be configured when Entra Sync is first set up. While there are ways to change this later they are complex and beyond the scope of this article. In Microsoft Azure Active Directory Connect, select “View or export current configuration” and click “Next”. Under Synchronization Settings you should see the source anchor attribute, this should be set to “mS-DS-ConsistencyGuid”. If it is set to something else, this migration method will likely be impossible.
In the original AD forest, you will need an OU which is not synced to Entra ID. This will allow you to remove users from the sync without deleting them. If no such OU exists, open Microsoft Azure Active Directory Connect on the sync server in the original domain and click “Customize Synchronisation Options”. Sign in when prompted and press “Next”. In “Domain and OU filtering”, ensure that at least one OU is unchecked.
You should also check that all users you wish to sync have a value set for “mS-DS-ConsistencyGuid”. If a user does not have this set it may still be possible for them to sync using soft matching based on the UPN or the proxy addresses. Such a configuration will break in a scenario like a domain move as these values would change. The following PowerShell command will identify all users with an empty “mS-DS-ConsistencyGuid”. If any of these are on the list to be synced, you will need to fix them before proceeding.
Get-ADUser -Filter * -Properties "mS-DS-ConsistencyGuid" | Where-Object "mS-DS-ConsistencyGuid" -eq $nullFinally, before making any changes I would recommend disabling the automatic sync cycle in both the source and target domains. This is not strictly necessary but it will ensure that syncs only occur when you plan for them, making sure that an object won’t be synced at an inopportune moment. To disable syncing, run the following PowerShell command:
Set-ADSyncScheduler -SyncCycleEnabled $falseWhen you are done and want to re-enable automatic syncing, run:
Set-ADSyncScheduler -SyncCycleEnabled $trueDetaching the Source User
Before creating the user in the target domain, we must break the syncing relationship between the Entra ID user and the old on premises user. To do this we can simply move the user out of a synced OU and then run a sync:
Start-ADSyncSyncCycle -PolicyType DeltaIf we now review the sync logs we can see that the user has been deleted from Entra ID.
We can also see in the Entra ID portal that the user has been soft deleted and shows up in the deleted users list.
One caveat to bear in mind here is that, as we discovered during the account creation, the Synchronisation Service will not fully trust that the user has been deleted until the next sync cycle. If we were to migrate the user now, they would be deleted again on the next sync. The trick here is to run the sync command for a second time. When we do this, we see the deletion reflected in the Delta Import, confirming that the deletion has been successful.
We will also see that if we try to view the deleted object, we get an error message.
This occurs because the Synchronisation Service has now fully removed this object from its database. As long as the object doesn’t come back in to scope, the service will not modify it again.
Creating the Target User
There are several ways that the target user can be created. For a production migration the most likely scenario is that you would be using the AD Migration Tool. While this is certainly recommended, an in depth explanation of ADMT is beyond the scope of this article. I will therefore be creating the new user manually. This method has some pitfalls which are not present in ADMT so I will point these out as we go.
Create a new user account in the target domain. The username and details can be the same as in the source domain but this is not necessary. The UPN suffix will almost certainly be different unless you have the same UPNs configured on both domains. If not using ADMT and automatic sync is enabled in the target domain, create the user in a non-synced OU.
In Active Directory Users and Computers, click “View” and ensure “Advanced Features” is checked. Open the newly created user account and go in to the “Attribute Editor” tab. Scroll down to “mS-DS-ConsistencyGuid”. This should currently be blank. Repeat the same process for the user in the source domain and you should see a hex string. Copy and paste this hex string to the new account. This is not necessary when using ADMT as it will sync the attribute automatically.
Once the source anchor is updated, we can now safely sync this account with Entra ID. If it was created in an unsynced OU, move it to a synced OU.
If we run the sync command and look in Entra ID, the user account no longer appears under deleted users. Returning to the All Users page, we see that the user has been re-added as a synced account. The account now uses the UPN suffix we selected in the target domain, confirming it has been synced from the new domain.
If we used ADMT the above process could be simplified as we wouldn’t need to manually set the source anchor. Instead we could simply migrate the user to a synced OU and run a sync.
Conclusion
Having gone through this process it turns out not to be as complex as I initially expected. The main pitfall is that the sync must be run twice on the source domain before setting the user up on the target. Another potential complication is that the user in the source domain could conflict if it were to ever become synced again. While this is unlikely to happen in a scenario where one domain is to be decommissioned, you can guard against it by clearing the “mS-DS-ConsistencyGuid” attribute. In this scenario if the user were to be synced again a new user would be created in Entra ID.
In summary, the steps to perform the process are:
- Move the user out of a synced OU
- Run the sync command once and verify that the user is soft deleted in Entra ID
- Run the sync command a second time
- Migrate the user to the new domain by whatever means you have chosen
- Ensure that the “mS-DS-ConsistencyGuid” attribute is the same for the source and target users
- Run the sync command on the target domain and verify that the Entra ID user is undeleted