Tenant Migration

Use Case: Consolidation of one Azure tenant environment into another.


  • Create cloud-only placeholder objects in the destination tenant
    • This should encompass Users, Groups, Teams, Exchange Items (Shared Mailboxes, Equipment, Rooms etc), SharePoint and OneDrive data
      • Before creating, reconcile objects which will conflict in the destination tenant

        ie UPNs, MailNickNames, SharePoint and Teams identifiers that may already be in use on the @tenant.onmicrosoft.com or custom domain

      • Create a mappings file of source objectId to destination objectId for each item
      • Optionally, give the destination objects the source objectID as their name

        This is useful for iteratively provisioning objects without duplication

      • Where possible hide or obscure these resources in the destination tenant
      • Record the custom smtps/SMTP values on these objects
      • Record all UPN values
      • For Users, optionally record the source MFA SMS registrations
        • These mobile details may be reapplied to the placeholder user accounts
  • Increase the O365 licensing capacity in the destination tenant to accomodate these migrating accounts. If required, raise a ticket with Microsoft to migrate tenant licensing to the destination tenant (if billed to a single company)
  • At this point perform incremental data migration using your chosen migration tool

    Data migration should include mailbox, OneDrive, SharePoint and Teams

  • Identify other configurations for migration including; Mail Transport Rules, Security Policies, Named Locations, SIEM integrations and Conditional Access
  • Identity App Integrations
    • Create the required placeholder App Registrations in the destination tenant and add third party integration placeholders
    • Assign security (ie user assignment as required)
    • Also create any required service or managed identity accounts.
  • Note down Guest users in the destination tenant that are also Users in the migrating tenant

    During the cutover (for a custom domain name) there cannot be Guests that also members in the tenant that you are migrating from

  • Identify an approach for migrating devices (intune or other applicable service)
  • In the destination tenant identify and amend any dynamic group membership that may inadvertently encompass the migrating accounts
  • Lastly, if transfering a custom domain name, begin validation of the custom domain in the destination tenant
    • This will create a TXT MS string value for later verification as a domain owned by the destination tenant

Near Cutover Preparation

  • Reduce the TTL on migrating domain DNS name (for both MX and TXT records)
  • Set the new TXT MS value on the DNS record
  • Continue incremental migration of Mailbox, OneDrive, Teams and SharePoint data at this point
  • Raise tickets with Microsoft for the migration of identified content outside of your chosen migration tool; ie PowerBI, Dynamics


  • Where appropriate, apply group policy for the recreation of Outlook profiles

    Outlook clients will commonly cache the previous tenant’s Exchange settings

  • If applicable, Disable Directory Sync in the source tenant

    This will convert the on-premises synchronised objects to cloud only

  • Invalidate mail flow MX record

    This will cause mail for the source domain to queue for 24 hrs - optionally queue mail at another server

  • Rename or remove all references to the custom domain in the source tenant
    • Across Users, Groups, Apps
    • In the target tenant, remove objects referencing the migrating domain
      • ie Contacts, Guest Users (that are migrating users)
  • When all references are removed the custom domain may be removed from the source tenant
  • For created (on-premises) users in the destination tenant local AD; ensure the on-premises archive mailbox GUID values align to the placeholder account value
  • Where joining to on-premises accounts, update your AAD Connect scoping rules

    If you have created placeholder accounts with the previous ImmutableId, these objects will join automatically and flow the password hash value (where enabled)

  • Assign UPNs as needed
    • Note that UPNs do not update from on-premises source values where the cloud counterpart is already assigned an O365 licenses
  • Apply smtps/SMTP as previously recorded

    If you have joined the placeholders to on-premises objects these addresses will apply automatically, otherwise assign according to your records

  • Resume mail flow by correcting MX record to route to O365 once again
  • Revoke refresh tokens on the source tenant
  • App owners are to refactor their apps to utilise the new OpenID Connect or SAML configurations as previously created