Keeping SharePoint happy during your domain migration

We’ve seen a few of different problems occur in SharePoint (2013, 2016, 2019) when users are being migrated from one domain to another. They usually come up in one of the following areas:

  • People Picker
  • User Profiles
  • Site permissions
    • If you allow your users to log in to the SharePoint sites using their “new” account before their “old” account is migrated to the new one, you’re going to have a bad time.
      • Doing so creates a new user record within the site collection for the “new” account. When the “old” account is then migrated to the “new” one, there is no “merging” of records. Instead, what happens is the “old” record is overwritten with the new account name, and the “new” record is simply deleted. This means that if the users new account had been given any new permission prior to the migration, that permission is lost after the migration.
      • This situation gets worse if the user then logs back in as their “old” account. If the “old” account has permission to the site via AD group, the “old” account will get access and another new record for the user will be added to the site. If that “old” account gets migrated to the new one again, the original record that had all the permissions and was added to numerous ‘person or group’ list columns throughout the site is deleted, causing permission loss.
    • There is code within the SharePoint profile sync process that is designed to detect when a user has been migrated in Active Directory. That code takes it upon itself to then call a migration for that user within SharePoint so that all site permissions and list columns show the correct account name. This can be a major problem if the user has not been cut-over and is not ready to use their new account.
      • Also, the process has no knowledge of which account is “old” or “new”, so if you’re importing both accounts, it can migrate the user back and forth, causing all kinds of problems.

 

What causes this?

Nearly all of these problems occur when both the “old” and “new” accounts are active in Active Directory at the same time, and the account has been migrated with SID History.

When you fail to simply cut-over the “old” account to the “new” account, and attempt to operate in a state of ‘account limbo’ for a period of time, that’s when things can get ugly.

 

How should I complete a domain migration keeping SharePoint interests in mind?

Do not allow the new accounts to be synched via User Profile Import, added to site permissions via People Picker, or log into any sites until after the migration within SharePoint is complete.

The way to accomplish that is: For a given user, only have a single account active in Active Directory at any given time (have the other account disabled).

In fact, if SID History must be preserved, this is the only supported option, as noted here: https://docs.microsoft.com/en-us/sharepoint/support/sharing-and-permissions/identity-and-permission-issues-in-two-way-domain-trust

Ideally, a user would continue to use their “old” account to access SharePoint until a certain date when the “old” account is then disabled in AD, the “new” account is enabled, and their account has been migrated within SharePoint (Move-SPUser). From that time forward, the user would only use their “new” account to log in and access SharePoint.

As long as we’re talking about the “ideal” situation, ideally, you would migrate all of your AD users at the same time so that they can all be migrated within SharePoint at the same time using a PowerShell script that calls Move-SPUser for each account. If you’re in a situation where you need to migrate AD users in batches, that’s when you should look into the “less than ideal workarounds” below.

Note: even in the “ideal” scenario, you can still run into the people picker issue I posted about.

 

Less than ideal workarounds:

If for some reason (usually due to a dependency from some legacy app) you really must have the “old” and “new” accounts active in AD at the same time, then you need to take some manual steps to (at least attempt to) keep SharePoint happy. You can use some arbitrary Active Directory attribute to control which account is imported by Profile Sync and shown in People Picker. For example, we’ve had some customers use the “carLicense” Active Directory attribute to signify which account is the one that SharePoint should find. A value of “A” would mean SharePoint should use that account while a value of “I” means it’s inactive and SharePoint should ignore it. So you set that value to “A” for the old account and “I” for the new account, and then when you’re ready to cut the user over in SharePoint, you swap the values.

If you’re going to do something like this, you may have to tweak your AD Schema. Whichever attribute you choose, both “Replicate this attribute to the Global Catalog” and “Index this attribute” should be selected within Active Directory Schema.

  • Configure People Picker:
  • Configure Profile Sync connections:
    • You want to be careful to only import a single copy of a given user at any given time.  If you set your Sync connections to filter out disabled accounts, and you only have one account active at any given time in AD like you’re suppose to, this should not be a problem.   This is one of the reasons that leaving both accounts active with SID History is not supported.  Importing both accounts can result in the Sync process automatically migrating (as in move-spuser) one account to the other and then back again, which can lead to permission loss, as described above.
    • As a less ideal alternative, you could filter out user profiles using the same method that you’re using to filter People Picker results. Continuing with the “carLicense” example, you would simply create Profile Sync connection filters that only include users where carLicense = A.
    • Keep in mind that user profiles can be created automatically just by a user logging in to a SharePoint site and accessing something user profile-related. These are known as unmanaged profiles. So if your user is able to log in to their client machine with their “new” account, but you’re not ready to cut them over to their new account within SharePoint, then you must take some steps to ensure that they are not able to authenticate to the SharePoint site using their new account.