How to Migrate On-Premises Distribution Lists in Active Directory to Azure AD using PowerShell

January 5th, 2020

written by Adam El-Gerbi

1429289775

Requirements:

  • On-premises server with Azure AD Connect
  • PowerShell Script run from machine connected to domain controller with Active Directory module

We’ve been migrating ourclients to increasingly leverage most Office 365 services. However, for e-mail managementwewere split onboarding and managing mailboxes and distribution groups using either AD or Azure AD. I don’t need to tell most system administrators why this becomes an administrative nightmare over time. But suffice to say, eventually whenever changing mail objects,we must ask ourselves if it’s synced from on-prem or in Azure.

To standardize our distribution groups, I created a script that generates a list of all distribution groups and a list of all members of those groups. The script just iterates through these lists and recreates the groups in Azure.

I suggest following the procedure in two segments as I manually deleted the groups myself once I generated the inventory of on-premises distribution groups.

Disclaimer: This script is provided for your convenience, but  every environment varies. You accept all risk when running this in a production environment.

Generate two CSV files: distribution groups and distribution group members

After this is done you should have 2 CSV files: membersAD.csv and groupsAD.csv. Inspect them and verify you can see the DL groups you want to migrate. Also verify that in the members group you can seethe expected data (should contain all members for all groups). Note that distribution groups without e-mail addresses are skipped since it’s possible to create them without this information in AD.

Manual steps after lists are generated:

  1. Schedule maintenance window as changes from this point onward will temporarily remove all AD distribution groups.
  2. Delete all DL groups inyour on-premises ADbased on groupsAD.csv report.
  3. Run a manual sync with Azure AD connectso the objects deleted on prem are removed from Azure AD.

Once the directory synced objects are gone from Azure AD, you can proceed to recreate the groups again.

Script to connect to Office365 and recreate DL groups based on membersAD.csv and groupsAD.csv reports:

And that’s it! These scripts are not a guarantee as your environment may differ from ours but may help you migrate your distribution lists to the cloud for easier management moving forward.

If you are facing trouble doing migrations or integrating Office365 within your business, you can always work with our professional services team.