Migrating SharePoint To Office 365: Orphaned Users

One thing you may need to address when migrating from an onsite version of SharePoint to Office 365 is how to handle “orphaned users”.

An orphaned user is one that is referenced in a SharePoint list or library in the onsite SharePoint environment, but who is not active in Azure Active Directory in Office 365. When migrating content, documents and items that contain references to an orphaned user cannot be migrated because when the content is added to Office 365, it fails field validation because the user is not active in the cloud AD.

It’s a pretty common situation and we recently encountered it again with a client that we were migrating to Office 365. Some migration tools like ShareGate provide mechanisms to work around the orphan situation. These mechanisms are easy to use and greatly help in mitigating the migration content with references to orphans, but don’t result in a “full-fidelity” migration of the original content. However, with ShareGate’s help, we recently figured out a new approach that results in a clean migration of content with no loss of user data.

Before we describe the OOB mechanisms and the new approach we came up with, let’s review a typical scenario that results in orphaned users:

Imagine Acme is a company that has onsite (on-premise) SharePoint, Exchange, and Active Directory. Let’s say there’s a user named Bob Smith with login of ACME\bsmith and email of bsmith@acme.com . Over time, Bob logs in and uploads documents and creates list items. Other people may also create list items that contain a “person” field and add Bob as a valid value in one of those list items. Then, Bob leaves to pursue other opportunities. After Bob leaves, Acme, like most companies, disables Bob’s AD account so that he can’t log in anymore. They typically do that for some amount of time and then eventually delete the account. So far, so good.

Some time later, Acme decides to migrate SharePoint and Exchange to Office 365. To start, Acme decides on DirSync to keep their onprem and cloud Active Directory synchronized. Once DirSync is up and running, Acme attempts to migrate content from onprem to the cloud but any document or list that contains a reference to Bob fails to copy over cleanly. Yup … Bob’s an orphan!

Obviously, for mid-size or larger companies with a normal amount of employee “churn” and have been using Exchange and SharePoint for years, the number of orphaned users continues to grow and grow over time and can be a surprisingly large number relative to current employee population. And consequently, the amount of content that can be affected by orphaned users can also be surprisingly large.

When migrating content using ShareGate, depending on the type of field in which an orphaned user is found, you may encounter one of the following responses:

Notice the difference in how the above fields are treated (btw, some of what happens is configurable, but this is default behavior). The list item with the orphaned Author property actually migrates but gives a warning because ShareGate replaced the Author field with the ID of the current user (this is a default action for this type of property). On the other hand, the custom person property called Host caused that list item not to be migrated over at all. Instead this scenario gives an error. One of the things I like about ShareGate is the quality of the documentation and how it’s integrated throughout the product. When you get an error or warning, ShareGate provides a link to the specific help page for that error.

When you click on “How to solve this issue” for the errors shown in the image above, the following help page is displayed: A Person or Group field contains an invalid value.

Two Out-Of-The-Box Options

The above help page provides 2 possible solutions to the orphaned user issue:

  1. SET A DEFAULT VALUE … Through the ShareGate UI you can set a default value (which can be a blank, or a valid user). When ShareGate finds an orphan while migrating content, it replaced the orphan with the default. Of course, doing this results in the loss of the original data in that field. To help preserve the data, you can create an extra column in the target list (a plain text field) and copy the name or email of the orphan into the text field. Because it’s a text field, it doesn’t need to validate the orphan against Active Directory. This is great for some situations, but it does require you to modify the target list to capture orphan data. And now you have two fields to search in for the same logical data element.
  2. MAP USERS AND GROUPS … ShareGate provides the ability to set up user and group maps that make it easy to replace one user with another. This provides a finer level of granularity and enables you to set specific replacements for specific users (or groups). This also is great for some scenarios, but still results in the loss of the original user data in its original context.

While both of the above solutions are viable for getting the documents and list items migrated, they require a change of data and/or structure during the migration, so this is not what I would call a “full-fidelity” solution.

Another Option

Since the problem with orphans (actually, the definition of orphans) is that they don’t exist in the target environment, I wondered if we could just temporarily add the orphans to AAD for the duration of the migration. After contacting ShareGate and they confirmed that in theory it should work, I did some initial testing and a couple false starts, it worked! All the data came through intact in its original context with no mapping required and no loss of data.

Here are the high level steps we used:

  1. Run the ShareGate Orphaned Users report and export the results to Excel.
  2. Modify the report to conform with the input format for Bulk Adding Users into Azure Active Directory.
    1. First Row should be these headers (this line might wrap, but it’s all on one line … headers are tab separated):
      User Name    First Name    Last Name    Name    Job Title    Department    Office Number    Office Phone    Mobile Phone    Fax    Address    City    State or Province    ZIP or Postal Code    Country or Region
    2. Only the first 4 fields are required to create the users:
      1. User Name is the person’s email address, e.g. bsmith@acme.com (note … this field doesn’t come back from the ShareGate orphan report, so you’ll have to find a way to add the email addresses into the CSV file. If your company has a standard format for email addresses, you can often automate most of it with a script or Excel formula that creates the email from manipulating first and last names. It’s not perfect, but it can save you a lot of work.
      2. First Name, Last Name, and Name are just normal text.
  3. Bulk add the orphans to AAD:
    1. Don’t assign them an Office 365 license. They don’t need a license … they just need to be in AAD.
    2. Don’t send the users a notification email (remember, they’re no longer employees).
    3. Make sure they are in an active (unblocked) state.
  4. Handle blocked users in AAD. Some orphans may fail to get added because they are actually already in AAD, but in a blocked state. (In our scenario, these were users who may have left the company more recently and were disabled in onprem AD but not yet deleted).
    1. Locate the orphans in this state.
    2. Reset their password and don’t send them the email notification (again, these are ex-employees).
    3. Unblock these orphans.
  5. Run the migration.
  6. Remove temporary accounts. Using the orphan list as a source document, delete and/or re-block the AAD accounts.
    1. PowerShell can be used to delete the users.

Also, note that for this to work, the user values don’t need to be an active user account in the source AD … it can be disabled or even non-existent. The core requirement, is to have an Active AND ALSO UNBLOCKED account on the target O365 tenant … just for the duration of the migration. And also they don’t need to be assigned an O365 license. They just have to be there during migration and then they can be re-blocked (or deleted) afterwards.

Using this technique, we were able to migrate all the content to Office 365 with full fidelity and not losing any data or context in the process.

Good luck with your digital transformation!

Best regards,

David A. Remillard
President & SharePoint Strategist
Future Technology Group, Inc.

Further Reading

Here is some extra information about some of the tools and concepts mentioned in this post:


Author: David Remillard

Our best projects are those which become a partnership between our client and FTG. I enjoy learning the details about our client's businesses and what each client wants to achieve with Office 365. Also enjoy brainstorming about client's pain points and business challenges and different ways that SharePoint might be used to help achieve your goals. We help you understand what is easy and what is hard in SharePoint and how to design solutions for maximum value. We create a shared vision, and build it out in increments with frequent project touch points, ensuring high-value business solutions that are closely aligned with your specific business environment (size, culture, budget constraints, tech comfort level, remote offices, etc). We live on repeat business and grow our business with clients who value practical business insight as well as technical skill.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s