The scenario here is that you have an M365 tenant which has multiple Active Directory forests synced to it, and you need to move a user's identity from its current forest into a different forest.
This isn't a very common occurence, but one that can come as part of a merger or acquisition situation where an employee transfers to a different business unit which has a disconnected forest and is being synced to the same tenant.
This post assumes that you have the MSOnline PowerShell Module installed and that you can connect to it and that you are using a topology similar to this with Azure AD Connect and Azure AD Connect Cloud Sync:
Convert from Directory-Synced to Cloud User Object
First, we need to convert the user object into a Cloud identity so that it is not being directory-synced from Active Directory.
Here, we have user 'John Doe' who is a directory-synced user:
- Move the user object such that it is out of scope from Azure AD Connect. Generally, this would be accomplished by moving the object to a non-syncing OU:
- Force Azure AD Connect to sync by logging into your Azure AD Connect server and entering the following in an elevated PowerShell terminal:
Start-ADSyncSyncCycle -PolicyType Delta
The user object will now be in a soft-deleted state in M365:
- Run a second sync cycle:
Start-ADSyncSyncCycle -PolicyType Delta. There is not a clear technical explanation I have come across as to why this is necessary, but just save yourself the headache and run it a second time. I spent many hours going down a troubleshooting rabbit hole on a Sev A case with Microsoft and they recommended this themselves.
- Restore the user account:
Restore-MsolUser -UserPrincipalName email@example.com
- Reset the user object's Immutable ID:
Set-MsolUser -UserPrincipalName firstname.lastname@example.org -ImmutableId "$null"
The user's identity will now be managed exclusively by Azure AD and is no longer directory-synced:
Perform Matching Process to Link to Active Directory
Now that the user identity is Cloud-managed, we can link it to the other Active Directory forest so that it becomes managed there. To do this, there are two options - either the soft matching or the hard matching process.
A soft match occurs when both the Primary SMTP Address and UserPrincipalName of the Cloud-managed object are the same as an on-premises object. A hard match occurs when the Immutable ID of a Cloud-managed object is equal to the Base64-encoded objectGuid of an on-premises object. This process is covered in more detail here.
When the match occurs, the attributes in Azure AD (as well as the account's password, if password hash sync is enabled) will be overwritten by whatever is in Active Directory for the user account. Ensure the desired information is in Active Directory for this user before matching.
For the purposes of this post we will be doing a soft match.
- Ensure that there is a user account in the other AD forest that has the same UserPrincipalName and proxyAddresses (just the primary SMTP) attributes as the Cloud-managed account.
- Add the on-premises user account to the scope of what Azure AD Connect Cloud Sync is configured to sync (OU or Security Group). During the next sync cycle, the match will occur and the previously Cloud-managed account will become on-premises managed.