Microsoft 365 Tenant-to-Tenant Migration Assessment Version 2

Time for an Update

A Microsoft 365 Tenant-to-Tenant migration can be a daunting task. As more apps and features become available, the list of things to keep track of when planning a migration grows. I strongly believe that the key to any project – particularly migration projects – lies in strong preparation and planning.

Some time ago, I published a PowerShell script to help admins prepare for Microsoft 365 Tenant to Tenant Migrations. The script gathers key data from a Microsoft 365 tenant to generate an Excel report containing key data for consideration during the migration planning process. The feedback on this script was very positive and many people had their own suggestions of items that should be included.

The feedback provided through GitHub or within the article comments has highlighted some areas to include in the assessment script. Taking this on board, I have now published Version 2 of the Tenant-to-Tenant Migration Assessment on GitHub.

What’s New?

While the fundamentals of the script haven’t changed, there are some key improvements and additions to be aware of:

• A new Power BI template that can be used to summarize core areas.
• The entire script has been updated to use the Microsoft Graph PowerShell SDK, allowing for better performance and scalability.
• Addition of the following optional areas in the output:
  • SharePoint Document Libraries
  • SharePoint Lists
  • Planner Plans
• Addition of the user’s directory sync status in the output.

Prepare the Environment

Preparing and running the script is like the process for Version 1 of the Tenant Assessment. The files for the assessment are available from GitHub here. To prepare to run the script, download all files to the folder C:\TenantAssessment on a local machine. The following files are used:

• Perform-TenantAssessment.ps1 – This PowerShell script runs the assessment and generates the output file.
• Prepare-TenantAssessment.ps1 – This PowerShell script creates the app registration in the Entra tenant and generates a self-signed certificate for authentication.
• TenantAssessment-Report.pbit – This Power BI template imports data from the output file and visualizes key data.
• TenantAssessment-Template.xlsx – This is the Excel template used to create the output file.

To prepare the tenant and generate the authentication certificate, run the script Prepare-TenantAssessment.ps1, as shown in Figure 1.

The script performs the following tasks to prepare the environment for the assessment:

• Authenticates to the Microsoft Graph using the PowerShell SDK (prompting the user for credentials).
• Creates a new app registration with the permissions shown in Figure 2 below.
• Adds the app service principal to the “Global Reader” and “Exchange Administrator” roles. If the roles are not activated yet, the script will activate them.
• Generate a new self-signed certificate and store it in the user’s certificate store on the workstation
• Upload the certificate to the app registration for use when authenticating.
• Outputs the Tenant ID, Client ID, and Certificate Thumbprint to the screen.
• Opens the application consent page in a browser to allow consent for the application permissions (as per Figure 2). Alternatively, the permissions can be consented from the app registration page of the Entra admin center. This consent must be granted by a Global Administrator account.

It’s important to understand that this app requires a high level of permissions, a level that attackers would love to gain to enumerate data in the tenant. The app registration should be treated as a highly privileged account and protected with Conditional Access and/or deleted after you have run the assessment. The high level of permissions is required to gather the data butit it shouldn’t be left in place and unprotected.

Running the Assessment Script

As with the previous version of the script, version 2 requires the “TenantID”, “ClientID” and “CertificateThumbprint” parameters. These values are displayed as the output of the preparation script shown above in Figure 1. There are also several optional parameters which will gather additional information:

• IncludeGroupMembership – This parameter includes a report of the members of each group.
• IncludeMailboxPermissions – This parameter includes a report of all mailbox permission assignments.
• IncludeDocumentLibraries – This parameter includes a report of all Document Libraries in the SharePoint environment.*
• IncludeLists – This parameter includes a report of all lists in the SharePoint environment (Excluding Document Libraries).
• IncludePlans – This parameter includes a report of all Planner plans in the tenant.

*Note, for non-English tenants, the filters in the code need to be updated to reflect the name of the “Documents” library in your tenant

The script uses only these PowerShell modules:

• Microsoft.Graph to perform the data gathering
• ImportExcel to create the output file
• ExchangeOnlineManagement to connect to Exchange Online to get information that is not exposed via the Graph API

The example command shown in Figure 3 runs the script with all optional parameters enabled and the Client ID, Tenant ID, and Certificate Thumbprint passed as variables as shown in Figure 3:

.\Perform-TenantAssessment.ps1 -clientId $clientid -tenantId $tenantID -certificateThumbprint $Thumbprint -IncludePlans -IncludeGroupMembership -IncludeMailboxPermissions -IncludeDocumentLibraries -IncludeLists

Note: Adding all optional parameters can increase the time required to run the script significantly, particularly in larger environments. Progress is displayed throughout to allow the administrator to know what’s happening.

When the script finishes, it generates a report in the folder C:\TenantAssessment named TenantAssessment.xlsx. Many of the tabs in the report are similar to the output from Version 1 of the assessment, so I won’t repeat them here. The new tabs generated by using the optional parameters are:

• Mailbox Permissions: This tab lists each assigned mailbox permission in Exchange Online.
• Group Membership: This tab lists every group membership present in Microsoft Entra ID.
• Document Libraries: This tab lists every Document Library present in SharePoint Online.
• Lists: This tab lists every SharePoint list (excluding Document Libraries) present in SharePoint Online.
• Planner Plans: This tab lists every Planner plan present in Microsoft 365 Groups.

Using the Power BI Template

With the output file generated, opening the Power BI Template “TenantAssessment-Report.pbit” will connect to the output file (located in C:\TenantAssessment) and import the data. After a few seconds, the report will load and present four pages: “User Overview”, “Exchange Overview”, “SharePoint Overview” and “Teams Overview”.

User Overview Page

The User Overview page in the Power BI report displays high-level statistics about the user accounts in the tenant. From this page, it’s easy to see data sizes for each component of a user account and see how they relate to each other as seen in Figure 4.

Each report page also contains two buttons on the left to filter results to only items which have the “migrate” column in the report set to “TRUE”. By default, all items have migrate set to “TRUE” but as you work through the migration plan, any objects not being migrated can be set to “FALSE” and they will be excluded from this view by clicking the “Show Migrating” button.

Exchange Overview

The Exchange Overview page (Figure 5) shows the details of the Exchange-related objects in the assessment such as counts and sizes of each mailbox type. The sliders at the top of the page allow for quickly identifying mailboxes of each type by size, for example, locating particularly large mailboxes that may take more time to synchronize data.

SharePoint Overview

The SharePoint Overview page (Figure 6) shows the data sizes within SharePoint (not including SharePoint sites linked to Teams), and the associated site types and activity. It also provides details on the 10 largest OneDrive and SharePoint sites and the most active sites. This information is useful when targeting priority areas for the business during a migration.

Teams Overview

Finally, the Teams Overview page (Figure 7) shows the details of Teams data sizes, counts of private and shared channels, and lists the largest Teams, Teams with most private channels and Teams with most Shared channels. Private and Shared channels require extra consideration during a migration, so this information supports planning for migration and estimating timeframes of data transfers.

Summary

When I created the initial tenant assessment script, I included what was (at the time) the most important aspects of a tenant-to-tenant migration for Microsoft 365. Extending the assessment out to these additional areas will help when it comes to planning migrations and the Power BI template allows for a summarized view of the key areas that impact migration planning.

One consistent piece of feedback I received in the previous version was that this information isn’t just useful in a migration context. Sometimes admins just need to get a view of what is in their tenant and the information provided can absolutely help in that scenario too.

As with the previous version, the feedback from the community is key to determining what version 3 might look like. I encourage people to share what they have found useful and maybe even add and share some features of their own through GitHub. Having a solid assessment is the first step to success in a migration project, and hopefully, this tool will help people to prepare and minimize late nights and weekends trying to get everything working in the new environment.