Office 365 – Distribution List Migrations Version 2.0 – Part 3

Using the distribution list migration module v2 for simple migrations

With the Distribution List Migration Module V2 installed and all of the pre-requisites ready you are now ready to try a distribution list migration.

In order to accomplish a migration, you must identify the following resources and have the necessary permissions to perform the migration.

• • (Mandatory) Global catalog server in the domain where the distribution list resides.
    
    • If all resources for this distribution list are in the same domain as the group, domain administrator rights for the credential specified are required.
      
    • If the distribution list to be migrated has dependencies in other domains within the forest (for example, the group is a member of groups in other domains), then enterprise administrator rights are required.
      
    • Remote PowerShell available and configured on the global catalog server referenced. A remote PowerShell session is required for Active Directory PowerShell commands that do not support specifying a server endpoint.
      
  • (Optional) Identify the Azure Active Directory Connect server that is responsible for synchronizing objects to Office 365.
    
    • ADSyncAdmin credentials are required in order to perform delta synchronization.
      
    • The specified account must also have rights to open a remote PowerShell session to the Azure AD Connect server.
      
    • Typically, the same account used for the global catalog server is used for the Azure AD Connect server.
      
  • (Optional) Exchange on-premises server in the organization containing the distribution list.
    
    • Exchange Organization Management rights are required.
      
    • If Active Directory split permissions are enabled, the account must also have rights to any organizational units where mailbox objects reside that will be included in pre-requisite scans or where hybrid mail flow objects will be created.
      
    • If the Exchange Server URL specified is part of a load balancer it may be required to enable basic authentication on the PowerShell virtual directory.
      
    • If the Exchange Server URL specified is a backend server using the installed self-signed certificate Kerberos authentication may be used.
      
  • (Mandatory) Access to Exchange Online through the Exchange Online Management Module v2.
    
    • Authentication may be performed either in the context of a user account or through certificate-based authentication.
      
    • The specified administrator account must have the Exchange Online Management role. (This may be different from using a Global Administrator within Azure, although this is the most common configuration).
      
    • If certificate authentication will be used, ensure that all pre-requisites are met at the following link: App-only authentication | Microsoft Docs
      

• (Mandatory) Access to Azure Active Directory through the Azure Active Directory PowerShell Module.
  
  • Authentication may be performed either in the context of a user account or through certificate-based authentication.
    
  • The specified administrator account must have the Global Administrator right.
    
• Unrestricted access to domain controllers and global catalog servers in other domains.
  
  • If the group to be migrated has dependencies in other domains within the Active Directory forest, the workstation or server where the migration is performed may need access to these resources to complete the migration.
    
  • Administrators do not have control over where changes happen in this domain. The script leverages the ability of the Active Directory PowerShell command to locate the “best” domain controller or global catalog server for the operation.
    

When the servers are identified, and the required credentials available you can proceed with a distribution list migration. To begin the migration, processing the SMTP address of the group is required. The administrator has the flexibility to decide how to store credentials; for example, in a secure XML file or by specifying them as a part of another command.

Here is an example prompting the administrator for credentials:

$gcCred = get-credential

$adConnectCred = get-credential

$cloudCred = get-credential

$exchangeCred = get-credential

Here is an example of credential reuse:

$gcCred = get-credential

$adConnectCred = $gcCred

$cloudCred = get-credential

$exchangeCred = $gcCred

Here is an example of credentials stored in XML files:

Prepare the credentials:

$cred=get-credential

$cred | export-CLIXML -path c:\credentials\onPrem.xml

$cred=get-credential

$cred | export-CLIXML -path c:\credentials\cloud.xml

Use the credentials:

$gcCred = import-cliXml -path c:\credentials\onPrem.xml

$adConnectCred = $gcCred

$exchangeCred = $gcCred

$cloudCred = import-cliXML -path c:\credentials\cloud.xml

There is a great deal of flexibility in how credentials are specified. If you are not using the script to trigger Azure AD Connect, enable hybrid mail flow, or to use other Exchange-only features (including full mailbox access and send as only) the global catalog credential, Azure Active Directory, and Exchange Online credential are necessary.

The script has several parameters – we will explore what each of them does as part of the migration process.

• (Required)GroupSMTPAddress
  
  • This is the primary SMTP address of the group to be migrated.
    
  • It must match the mail field in Active Directory.
    
• (Required)GlobalCatalogServer
  
  • This is the global catalog server specified in the same domain as the distribution list to be migrated specified as a fully qualified domain name.
    
• (Required)ActiveDirectoryCredential
  
  • This is the credential for connections to the global catalog server <or> other Active Directory resources in the forest.
    
• (Optional)ActiveDirectoryAuthenticationMethod
  
  • This specifies if Kerberos or another authentication method should be utilized when connecting to Active Directory.
    
  • Default = Kerberos
    
• (Optional)AADConnectServer
  
  • This is the fully qualified domain name of the Azure AD Connect server.
    
  • If this is specified along with a credential, delta synchronization will be triggered to decrease the time to remove the distribution group from Office 365.
    
  • If the server is not specified the script will wait for the default sync cycle interval to trigger and for group removal to occur.
    
• (Optional)AADConnectCredential
  
  • Credential used to connect to the Azure AD Connect server to perform delta synchronization.
    
  • This is required if AADConnectServer is specified.
    
• (Optional)AADConnectAuthenticationMethod
  
  • This specifies if Kerberos or another authentication method should be utilized when connecting to Azure Active Directory Connect.
    
  • Default = Kerberos
    
• (Optional)ExchangeServer
  
  • This is the fully qualified domain name to the on-premises Exchange Server remote PowerShell directory.
    
  • This is required if hybrid mail flow objects for the migrated distribution lists are enabled.
    
• (Optional)ExchangeCredential
  
  • This is the credential specified for the Exchange remote PowerShell connection.
    
  • This is required if an Exchange server is specified.
    
• (Optional)ExchangeAuthenticationMethod
  
  • This is the authentication method to the on-premises Exchange server.
    
  • Values are Kerberos or Basic, with Basic being the default.
    
  • This may require enabling Basic Authentication on the Exchange server’s PowerShell virtual directory.
    
  • Default = Kerberos
    
• (Optional)ExchangeOnlineCredential
  
  • This is the credential that will be used for Exchange Online connectivity.
    
  • This credential is mandatory if certificate-based authentication is not being used.
    
• (Optional)ExchangeOnlineCertificateThumbprint
  
  • This is the thumbprint of the locally installed certificate that will be used with certificate-based authentication.
    
  • This is mandatory if an Exchange Online credential is not specified.
    
• (Optional)ExchangeOnlineEnvironmentName
  
  • This is the environment for the Exchange Online remote PowerShell connection.
    
  • This automatically defaults to the Office 365 commercial environment.
    
  • This may change for other environments like GCC.
    
  • This is required if you specify an ExchangeOnlineCertificateThumbprint.
    
• (Optional)ExchangeOnlineAppID
  
  • This is the application ID associated with the application created in Azure for certificate-based authentication.
    
  • This is required if you specify an ExchangeOnlineCertificateThumbprint.
    
• (Optional)AzureADCredential
  
  • This is the credential that will be used for Azure Active Directory connectivity.
    
  • This credential is mandatory if certificate-based authentication is not being used.
    
• (Optional)AzureEnvironmentName
  
  • This is the environment for the Azure Active Directory PowerShell connection.
    
  • This automatically defaults to the Office 365 commercial environment.
    
  • This may not change for other environments like GCC.
    
  • This is required if you specify AzureCertificateThumbprint.
    
• (Optional)AzureTenantID
  
  • This is the tenant GUID associated with the Azure Active Directory instance.
    
  • This is required if you specify AzureCertificateThumbprint.
    
• (Optional)AzureAplicationID
  
  • This is the application ID associated with the application created in Azure for certificate-based authentication.
    
  • This is required if you specify AzureCertificateThumbprint.
    
• (Optional)AzureCertificateThumbprint
  
  • This is the thumbprint of the locally installed certificate that will be used with certificate-based authentication.
    
  • This is mandatory if an Azure Active Directory credential is not specified.
    
• (Required)LogFolderPath
  
  • This is the root path where the script will look for audit data (pre-collected dependencies) and store all log / export files associated with the migration.
    
  • Upon completion this folder is a date/time rename and appended with either success or failure.
    
• (Mandatory)DoNotSyncOU
  
  • This is the organizational unit in Active Directory in the same domain as the distribution list to be migrated that is set to not synchronize through Azure AD Connect.
    
  • This is mandatory and used to trigger distribution list removal in Office 365.
    

Above are the basic parameters that can be used as part of a simple distribution list migration. The parameters below offer administrators more advanced options, including tracking additional dependencies in both the on-premises and Office 365 environments.

• (Optional)RetainOriginalGroup
  
  • This allows the administrator to retain the group after migration.
    
  • The default is TRUE.
    
  • In a future post, the workflow will be outlined as to how the group is retained.
    
  • If the group is a security group type on premises and retainOriginalGroup is set to false the option is ignored and the group is retained.
    

• • (Optional)EnableHybridMailFlow
    
  • This option enables the hybrid mail flow feature in the on-premises directory.
    
  • If specified local Exchange Server names and credentials must be specified.
    
  • • For information on how hybrid mail flow works with migrated distribution lists see Office 365 – Distribution List Migrations Version 2.0 – Part 7 | TIMMCMIC (wordpress.com)
      

• (Optional)GroupTypeOverride
  
  • This option allows the administrator to create the migrated distribution group in Office 365 as a type that differs from on-premises.
    
  • For example, a security enabled group can be changed to a distribution only group in Office 365 by specifying the override value “Distribution.”
    
  • Values are “Distribution” or “Security.”
    
  • Default is “None.”
    
• (Optional)TriggerUpgradeToOffice365Group
  
  • This option allows administrators to request that the migrated distribution group be automatically converted to a Microsoft 365 Group.
    
  • This option only triggers the upgrade request; it does not guarantee that the upgrade will occur or be successful as this is an asynchronous process that occurs in the background.
    

• • (Optional)OverrideCentralizedMailTransportEnabled
    
  • If centralized mail transport is enabled in Exchange Online administrators must specify TRUE.
    
  • • For more information on why this is required see Office 365 – Distribution List Migration Version 2.0 – Part 16 | TIMMCMIC (wordpress.com)
      
  • (Optional)allowNonSyncedGroups
    
  • Allows administrators to migrate groups that are not represented in Office 365 but where all members of the group are reflected in Office 365.
    
  • • For more information on this feature see Office 365 – Distribution List Migration Version 2.0 – Part 15 | TIMMCMIC (wordpress.com)
      

• (Optional)UseCollectedFullMailboxAccessOnPrem
  
  • This switch indicates that the administrator has run the pre-collection command to gather all full mailbox access permissions prior to migration.
    
  • This uses point in time data to increase the efficiency of maintaining additional rights.
    
  • See documentation on start-collectOnPremFullMailboxAccess.
    
• (Optional)useCollectedFullMailboxAccessOffice365
  
  • This switch indicates that the administrator has run the pre-collection command to gather all full mailbox access permissions prior to migration.
    
  • This uses point in time data to increase the efficiency of maintaining additional rights.
    
  • See documentation on start-collectOffice365FullMailboxAccess.
    
• (Optional)UseCollectedSendAsOnPrem
  
  • This switch indicates that the administrator has run the pre-collection command to gather all send as permissions to recipients.
    
  • This uses point in time data to increase the efficiency of maintaining additional rights.
    
  • See documentation on start-collectOnPremSendAs.
    
• (Optional)UseCollectedFolderPermissionOnPrem
  
  • This switch indicates that the administrator has run the pre-collection command to gather all mailbox rights on folders.
    
  • This uses point in time data to increase the efficiency of maintaining additional rights.
    
  • See documentation on start-collectOnPremMailboxFolders.
    
• (Optional)useCollectedFolderPermissionsOffice365
  
  • This switch indicates that the administrator has run the pre-collection command to gather all mailbox rights on folders.
    
  • This uses point in time data to increase the efficiency of maintaining additional rights.
    
  • See documentation on start-collectOffice365MailboxFolders.
    

• (Optional)allTelemetryCollection
  
• Allows administrators to opt out of telemetry collection.
  
• • For more information on telemetry collection see Office 365 – Distribution List Migration Version 2.0 – Part 23 | TIMMCMIC (wordpress.com)
    

With the parameters defined here are some sample migration commands:

• Simple distribution list migration with delta sync trigger.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -azureADCredential $cred -logFolderPath c:\temp -doNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCredential $cloudCred
    

• Simple distribution group migration with no other dependencies.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -logFolderPath c:\temp -doNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCredential $cloudCred -azureADCredential $cloudCred
    

• Simple distribution group migration where hybrid mail flow should be maintained.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -azureADCredential $cloudCred -logFolderPath c:\temp -doNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCredential $cloudCred -exchangeServer webmail.contoso.com -exchangeCredential $cred -enableHybridMailFlow:$TRUE
    

• Simple distribution group migration where the group will be deleted post migration – delta sync triggered.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -logFolderPath c:\temp -dnNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCredential $cloudCred -azureADCredential $cloudCred -retainOriginalGroup:$FALSE
    

• Migrate everything using all data gathered from pre-recorded commands.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -logFolderPath c:\temp -dnNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCredential $cloudCred -azureADCredential $cloudCred -retainOriginalGroup:$FALSE -useCollectedSendAsOnPrem:$TRUE -useCollectedFullMailboxAccessOnPrem:$TRUE -useCollectedFolderPermissionsOnPrem:$TRUE -useCollectedFullMailboxAccessOffice365:$TRUE -useCollectedFolderPermissionsOffice365:$TRUE -retainSendAsOffice365:$TRUE
    

• Simple distribution group migration with delta sync and upgrade to Office 365 group.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -logFolderPath c:\temp -dnNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCredential $cloudCred -azureADCredential $cloudCred -triggerUpgradeToOffice365Group:$true
    

• Simple distribution list migration with delta sync trigger and exchange certificate authentication.
  
  • Start-distributionListMigration -globalCatalogServer server.domain.com -activeDirectoryCredential $cred -groupSMTPAddress group@contoso.com -AADConnectServer aadconnect.domain.consoto.local -aadConnectCredential $cred -logFolderPath c:\temp -dnNotSyncOU “ou=nosync,dc=domain,dc=contoso,dc=local” -exchangeOnlineCertificateThumbPrint 7972D7272C95F8D7C7CE26DF2ECE286EE853BDD7 -exchangeOnlineOrganizationName domain.onmicrosoft.com -exchangeOnlineAppID 42726348-e106-4b55-8304-228159d80ddd -azureADCredential $cloudCred
    

The actions of the script are logged into a log file with the name of the distribution group. Upon success, the folder is renamed with a date/time stamp and appended with success. If a failure is encountered, the folder is renamed with a date/time stamp and appended with failure. Included with the log directory are XML dumps of all dependencies in case the distribution list requires manual recreation. In addition, this could be used to debug failed migration attempts.

• Sample of log files and folders in the log folder path.
  

• Sample of data contained in the success / failure folder.
  

Happy migrating!