Office 365: Challenges with Distribution Groups for Migrated Mailboxes and a Script Based Solution ( Script Version 1.4 )

In script version 1.3 we began the introduction of logic that allowed administrators to convert the distribution group to a mail enabled contact post migration.  It was extremely simplistic in that the function utilized retained as many attributes of the distribution list, deleted the distribution list, and created a mail enabled contact utilizing the retained attributes.  On the surface this functionality worked well for preserving mail flow and allowing an object to be represented in the global address list. 

The simplistic logic introduced several potential issues.

  • The deleted distribution list could be members of other distribution lists or groups.
  • The deleted distribution list could have exceptions on other groups – for example managedBy, AcceptMessagesOnlyFromSendersOrMembers, RejectMessagesFromSendersOrMembers, etc.
  • When the distribution list is deleted all of the other dependencies on that list are lost.

In addition to the concerns of what is lost when deleting the distribution group this version also attempts to address a concern brought forth by a customer utilizing the script for migration.  In version 1.4 the default behavior was to move the distribution group to an organizational unit that does not synchronize through Azure Active Directory Connect.  This method is utilized to ensure that the group object on premises does not collide with the group object created directly in Office 365.  In this customers instance the organizational unit that was intentionally excluded from synchronization was accidentally selected for synchronization.  When the groups were detected – Azure Active Directory Connect soft matches the on-premises group to the migrated group and changes the source of authority to on-premises.  In addition any changes that were processed directly in the cloud were overwritten with old data retained on-premises.

With the background what changed in version 1.4.

Changing default convert to contact logic:

In prior versions the conversion to contact was optional.  It continues to be optional but the default behavior has changed.  Instead of moving the group to the non-sync OU and leaving it – it is now deleted and converted to a mail enabled contact by default.

Changing domain controller logic:

In prior versions a specific domain controller was not specified by the administrator for directory operations.  Using the Exchange Management Shell logic – a domain controller local to the connected Exchange Server was utilized.  In multi-site environments it was possible that the endpoint processing the Exchange commands and the Azure Active Directory Connect server would be utilizing different sets of domain controller.  The scripts logic for dealing with this was to perform a global Active Directory replication which was inefficient.  The script now requires the administrator to specify a specific domain controller for operations.  Inbound and outbound replication is triggered from this specific domain controller.  The domain controller specified should be in the same site as the Azure Active Directory Connect Server.  When utilizing a domain controller in the same site as the ADConnect server we cut down on overall time waiting for ADConnect to replicate the distribution group removal from Office 365.

Tracking migrated distribution group settings for on-premises objects:

To facilitate a lossless migration new logic was implemented to track permissions and settings of the migrated group.  Specifically we do the following:

  • Record all distribution lists where the migrated distribution group has managedBy rights.
  • Record all distribution lists where the migrated distribution group has BypassModerationFromSendersOrMembers rights.
  • Record all distribution lists where the migrated distribution list has AcceptMessagesFromSendersOrMembers rights.
  • Record all distribution lists where the migrated distribution lists has RejectMessagesFromSendersOrMembers rights.
  • Record all groups in the Active Directory where the migrated distribution list is a member.

It should be noted that this process does introduce some inefficiency into the overall scripts.  Unfortunately BypassModerationFromSendersOrMembers is not a filterable property of get-distributionGroup.  This requires scanning all distribution groups in the organization in order to determine if the migrated DL has this right.  Depending on the number of on-premises distribution group this could add significant time to the migration process.

Changed the convert to mail enabled contact logic:

In order to facilitate changing the distribution list to a mail enabled contact several logic items needed to change.  The first logic change that needed to occur was provisioning the mail enabled contact.  When the on-premises distribution list is deleted a mail enabled contact is created in the original OU where the distribution list originally resided.  The script utilizes a name prefix specified in the script by the administrator, and is appended to the distribution groups name, to create  random contact name.  The remote routing address on the contact is set to the *.onmicrosoft.com email address of the migrated distribution list.  When a mail enabled contact is created the remote routing address is added as a proxy address to the proxy addresses attribute.  This causes proxy address collisions with the migrated distribution list since the object is created in a synchronized OU.  The script removes these email addresses from the proxy addresses attribute to prevent any collision – they are not required to be present.  The last customizations to the mail enabled contact are to set custom attribute 1 of the object to a migration string for easy location and customer attribute 2 to the original primary SMTP address.  This is required to retain mail flow from on premises to Office 365.  The mail contact is replicated to ensure that group membership and distribution list rights settings can be retained from on-premises to Office 365. 

The second logic change that need to occur was preserving an object on premises that allowed for cross premises mail flow.  The object needed to not replicate or have the ability to replicate and be soft matched to the migrated group in the event of an accident.  A dynamic distribution group is the perfect object.  A dynamic distribution list can be created, will appear in the global address list, but in no way can be replicated to Exchange Online.  The script provisions a dynamic distribution group in the organizational unit specified for converted distribution groups.  The settings of the original distribution group are preserved on the dynamic distribution group.  These include name, alias, and proxy addresses.   In addition the X500 address of the migrated distribution list is stamped on the dynamic distribution group to ensure that reply to and nickname functionality works.  The dynamic distribution list is scoped to look for mail enabled contacts in the distribution groups original organizational unit where custom attribute 2 equals the original primary SMTP address.  I will outline the mail flow scenarios later in the article.

The third logic change was to change how membership lists were built during the migration process.  A function of the script is to scan all settings of the DL to be migrated and convert attributes lists into primary SMTP address lists.  In the case of the mail enabled contact we do not want to include it as the member where we should be adding another migrated DL.  The script looks at each object and if it is a mail enabled contact where custom attribute 1 is the migration string – the recorded SMTP address to the array is custom attribute 2 which is the original DLs primary SMTP address.  This ensures that when attributes are reset within Office 365 the migrated group is added back with permissions or membership and not the mail enabled contact that also exists.

The forth logic change was to preserve group membership.  Distribution groups can be nested into any number of other security and distribution groups in the organization.  If we simply deleted the original distribution list this membership would be lost.  The script will go through and reset the mail enabled contact to be members of the groups that the migrated DL was originally a member of.  In the case of security groups on premises this DOES NOT preserve permissions as a mail enabled contact is not a security context for shares or other resources.  Retaining the membership also ensures that as other distribution lists are migrated the membership can be converted and retained in Office 365.

The fifth logic change is to handle any other settings that the migrated distribution list could have on other distribution groups.  These include managedBy, BypassModerationFromSendersOrMembers, AcceptMessagesFromSendersOrMembers, and RejectMessagesFromSendersOrMembers.  The script tracks arrays of all of these settings and then steps through the remaining groups on premises to add the mail enabled contact to the lists.  This allows the contact to be detected when future distribution list migrations occur and for the group permission to be added to those lists in Office 365 post migration. 

On-Premises Mail Flow:

To ensure full migrated group access to on premises the script has implemented logic that changes the message flow.  Here is how messages will flow after the DL migration has completed.

  • Message enters receive connector to on-premises Exchange Server.  Sample address migratedDL@contoso.com.
  • Transport matches the address migratedDL@contoso.com to the script created dynamic distribution group migratedDL@contoso.com.
  • Transport expands the distribution group searching for a mail enabled contact in the migrated distribution lists original organizational unit where custom attribute 2 equals the primary SMTP address.
  • The mail enabled contact is located and has a remote routing address of migratedDL@mail.domain.onmicrosoft.com.  The email is then converted to migratedDL@mail.contoso.onmicrosoft.com.
  • The message is transferred through the hybrid connector to Office 365.
  • The message arrives in Office 365 addressed to migratedDL@mail.contoso.onmicrosoft.com.  The message address is converted to migratedDL@contoso.com.
  • The message delivers to the migrated distribution list where it is expanded and sent to the recipients.

Script Performance:

I wanted to provide some sample script performance values.  In this test we have the following:

  • A distribution list to migrate that has 10,000 members comprised of mailboxes, remote mailboxes, mail enabled users, and mail enabled contacts.
  • The distribution list is a member of 10,000 other groups within the Active Directory.
  • The distribution list to be migrated is set as managedBy to 5,000 other distribution groups.
  • The distribution list to be migrated is set as BypassModerationFromSendersOrMembers to 5,000 other distribution groups.
  • The distribution list to be migrated is set as AcceptMessagesFromSendersOrMembers on 5,000 other distribution groups.
  • The distribution list to be migrated is set as RejectMessagesFromSendersOrMembers on 5,000 other distribution groups.

Here is the performance statistics given those values.

Days : 0

Hours : 6

Minutes : 19

Seconds : 32

Milliseconds : 34

Ticks : 227720349894

TotalDays : 0.263565219784722

TotalHours : 6.32556527483333

TotalMinutes : 379.53391649

TotalSeconds : 22772.0349894

TotalMilliseconds : 22772034.9894

The distribution list took short of 7 hours to migrate in that configuration.

A more reasonable test was performed with the following characteristics:

  • A distribution list to migrate that has 1,000 members
    comprised of mailboxes, remote mailboxes, mail enabled users, and mail enabled
    contacts.
  • The distribution list is a member of 1,000 other groups
    within the Active Directory.
  • The distribution list to be migrated is set as managedBy to 100 other distribution groups.
  • The distribution list to be migrated is set as
    BypassModerationFromSendersOrMembers to 100 other distribution
    groups.
  • The distribution list to be migrated is set as
    AcceptMessagesFromSendersOrMembers on 100 other distribution
    groups.
  • The distribution list to be migrated is set as
    RejectMessagesFromSendersOrMembers on 100 other distribution
    groups.

Days : 0

Hours : 0

Minutes : 21

Seconds : 58

Milliseconds : 822

Ticks : 13188223153

TotalDays : 0.0152641471678241

TotalHours : 0.366339532027778

TotalMinutes : 21.9803719216667

TotalSeconds : 1318.8223153

TotalMilliseconds : 1318822.3153

In this instance the distribution group took 21 minutes to finalize and sync. 

For factors affecting overall time please review the additional blog posts on prior script revisions.

Happy migrating!