This article provides additional information and appropriate changes regarding scoping when performing a mailbox migration from an M365 Tenant.
The procedures shown here are the differences in the normal permission assignment and can be used in conjunction with the M365 Mailbox and Archive Migration Permissions, found here.
Some migrations may require only allowing rights to the migration process for a particular set of users. In such cases, use the following procedure that outlines how this can be achieved. To do so, please replace Step Two's instructions with the ones detailed below.
Replacement Step Two - Changes in API Permissions
In Step Two you must add the additional Application Permissions to the App Registration. In this case, the full_access_as_app permission should NOT be checked.
When this permission is selected, it will override any of the management scopes and simply provide access to all mailboxes in the organization. So, remove this permission if you had previously included it in your application registration.
Create Management Scope Manually Using a Mail-Enabled Security Group
To assign a management scope only for a particular set of mailboxes, create a mail-enabled security group in the tenant (or use an existing one).
Make sure you have copied down the distinguished name of the security group as you will need it when creating the restriction filter for your management scope. The following is an example of what a distinguished name for the group would look like:
CN=MailEnSecGro20240913485729,OU=BTTest.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=NAMP210A006,DC=PROD,DC=OUTLOOK,DC=COM
To obtain the Distinguished Name of a Group, you can use the PowerShell command below. It does rely on the connection made into the Exchange Online module so be sure to connect there first.
Connect-ExchangeOnline
Get-distributiongroup -identity "GROUPNAME" | select distinguishedname | fl
Then follow the steps below to create the management scope.
- Connect to the M365 Tenant with the following PowerShell command, using your Admin credentials.
connect-exchangeonline - Run these PowerShell commands, replacing the items in bold with the details from your Enterprise Application, and make sure to use the distinguished name of your own security group and not the one in the example shown below:
$applicationId = "ApplicationID from the Enterprise Application"
$objectId ="ObjectID from the Enterprise Application"
$MgmtScopeName="User Mailboxes"
New-ManagementScope -Name $MgmtScopeName -RecipientRestrictionFilter "MemberOfGroup -eq 'CN=MailEnSecGro20240913485729,OU=BTTest.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=NAMP210A006,DC=PROD,DC=OUTLOOK,DC=COM'"
New-ServicePrincipal -AppId $applicationId -ObjectId $objectid -DisplayName "MigrationWiz"
New-ManagementRoleAssignment -App $objectId -Role "Application EWS.AccessAsApp" -CustomResourceScope $MgmtScopeName - Check that the management scope is in place by using this command.
Get-ManagementScopeThe results will have a similar output to this image.
In the example above, only mailboxes that are members of the mail-enabled security used for the recipient restriction filter will be in scope for the migration.
As a result, when you try to perform a migration with MigrationWiz, mailboxes that are not added as members of the mail-enabled security group will fail with a 403 error like in the following example.
Your migration failed while checking destination credentials. The request failed. The remote server returned an error: (403) Forbidden.
In the example above, the destination mailbox fails as it is not a member of the mail-enabled security group being used for the management scope in the destination tenant.
Another way to confirm that a mailbox is part of the scope created is by running the following PowerShell commands against the impacted mailbox in the tenant.
Test-ServicePrincipalAuthorization -Identity <ObjectID, AppID, or DisplayName> [-Resource] <target mailbox>
Tip
The ObjectID or AppID refers to the same values used to create the management scope earlier
As a result, you will get the following values:
- InScope = False, indicating the mailbox is not a member of the mail-enabled security group used for the management scope.
- InScope = True, indicating the mailbox is a member of the mail-enabled security group.
The DisplayName of the Service Principal is used in the example below, showing an InScope value of False.
Updating the Management Scope
To update the management scope, you must remove the previous one and re-apply it to the tenant. To do this, follow the next steps:
- Remove the Management Role Assignment.
get-managementroleassignment -Identity "Application EWS.AccessAsApp*" -RoleAssigneeType ServicePrincipal | remove-managementroleassignment - Remove the Service Principal.
remove-serviceprincipal -identity "MigrationWiz" - Remove the Management Scope itself.
remove-managementscope -identity "User Mailboxes"
Afterward, you can rerun the commands from the sections above to recreate the Management Scope with the updated filter.