Migrating EOP Settings Between Tenants

I find myself currently writing tools to both support my and other organization projects, as well as looking for ways to refine existing tools and scripts, make my life easier for future migrations, and provide additional resources to the community to help other customers more successfully use our products.

Today's tool fulfills all of those goals.

While working with a particular customer, I've found it necessary to migrate them from one legacy EOP instance in our commercial space to an integrated Office 365 (with EOP) tenant in the GCC space.  There are a number of things that need to be captured to do this, and TN article at https://technet.microsoft.com/en-us/library/dn801047%28v=exchg.150%29.aspx does an excellent job at capturing a lot of those.

However, I ran into a number of issues with the script provided in TN.

sayitaintso

I know.  Say it ain't so.

Some of the problems I ran into included transport rules failing to import due to encryption not being enabled in the target tenant, options requiring Enable-OrganizationCustomization to be run, attributes that can't be imported (even though you can export them), and certain fields that weren't escaped properly so possible attribute values would cause an error in the cmdlets.

Additionally, the documented TN script and process required you to save/create multiple scripts for exporting and importing settings, as well as an intermediary script to take the exports and process them into a functional import script.  I have taken the functions and steps of the script, and wrapped it into a single script.  The new, bigger package that includes functions for connecting to source and target tenants (both EOP and Office 365, since they have different endpoints and cmdlets available to them), enabling organization customization (which is required for some rules to work properly), checking your exported transport rules to see if any of them require Office 365 Message Encryption (and attempting to enable AADRM if you have licensing for it), and then some additional nice-to-have features that you would also find yourself needing in a tenant migration, such as adding new domains to the target tenant and creating DNS verification records for the network team.  I also added a function to only import the transport rules (since that seems to be the item that fails most commonly).

A quick break down of the features and how to use them:

 .PARAMETER AADRM
Enable Azure AD Rights Management for tenant. Valid parameters:
- GCC - US Government Community Cloud
- NA - North America
- EU - European Union
- AP - Asia / Pacific
- SA - South America

This parameter will tell the tool to attempt to enable Azure AD Rights Management in the target tenant.  Users must have a license that support ADRMS in order to be able to use this feature, but you should be able to configure it regardless.  The valid values for an RMS TPD are mapped to the various allowed values in the AADRM parameter (GCC, NA, EU, AP, and SA).  That will set the RMS Publishing Domain to the correct value.

 .PARAMETER EOP
Identifies source environment as EOP (different target endpoint)

You would would a want to use this parameter if you're migrating from a legacy EOP-only tenant (which would most likely have been a legacy FOPE tenant).  It has a different endpoint (ps.protection.outlook.com vs ps.outlook.com).

 .PARAMETER SourceTenantCredential
Standard PSCredential object for connecting to source environment.

You can save a credential (via Get-Credential) and pass it to SourceTenantCredential.

 .PARAMETER TargetTenantCredential
Standard PSCredential object for connecting to target environment.

You can save a credential (via Get-Credential) and pass it to TargetTenantCredential.

 .PARAMETER Mode
Modes available:
- Export (Exports all settings and domains)
- ExportDomains (Exports only domains from source tenant)
- ImportDomains (Imports only domains from source tenant)
- ConfirmDomains (confirms domains in target tenant)
- Import (Imports all settings except domains)
- ImportTransportRulesOnly (Imports transport rules; useful for re-running if initial import failed)

This is the important stuff.  You'll always need to specify Mode and then one of the following values:

  • Export - This will create an export file for each of the different data types (Connection Filter Policy, Content Filter Policy, Content Filter Rules, Outbound Spam Filter Policy, Malware Filter Policy, Malware Filter Rules, Inbound Connectors, Outbound Connectors, Transport Rules, and Domains).
  • Export Domains - This runs an export, but only selects domains from the source tenant.
  • Import Domains - This runs an import of the domains only into the target tenant, utilizing the XML file generated from Export Domains.  It will generate a DNS verification file that has the data necessary to be added as DNS TXT records for domain verification.
  • ConfirmDomains - You can use this after the ImportDomains process.  It will attempt to confirm all of the domains in the tenant.  Do NOT do this until after the domains have been removed from the previous tenant, or you will end up having to create new DNS verification records.
  • Import - This imports all exported settings, except for domains.
  • ImportTransportRulesOnly - This setting only imports the transport rules.  This is particularly useful if some of the transport rules failed import due to security or encryption settings in the target tenant and you have resolved the issues.  ImportTransportRulesOnly can be used with the AADRM parameter to attempt to configure AADRM.

You can find the new script with guidance here: https://gallery.technet.microsoft.com/Migrate-EOP-Settings-9d480325.  Be sure to let me know what you think--what's working, what's not, and what suggestions you might have.