This article provides all the necessary information to set up and perform a mailbox migration for a Microsoft 365 tenant. The approach outlined in the article is important to follow as it contains new information about the setup of the tenant, the application registration, the replacement of the Application Impersonation role in M365, and the assignment of permissions.
Important
The steps listed in this article do not scope the API permissions and will allow access to all user mailboxes in the tenant. For alternative steps that allow scoping of the API permissions to specific mailboxes only, please review this article this article.
The quick checklist below outlines the basic steps covered in detail in this article. These steps allow for the process of replacing the application impersonation.
- Create a new Application Registration
- Assign the API Permissions and Grant Admin Consent
- Obtain the AppID and TenantID from the Application Registration
- Create a Client Secret
- Note regarding the Scoping Requirements
- Set up your MigrationWiz Project
Important
The Application Impersonation is still a valid way to configure a MigrationWiz, however, Microsoft is already deprecating the ability to assign this role to tenants across the M365 architecture. Although it is still valid and will work where the role can be assigned to your tenant, it is recommended that the replacement method be used as a longer-term strategy for your migrations. This article concentrates on this new method as the default option in M365 Mailbox migrations.
Considerations
- The following replacement should be followed for any O365 endpoints for O365 mailbox/archive mailbox projects. Depending on the case, these steps should be performed at both the source and the destination.
- You can only perform the recommended replacement with Administrator credentials. If you use end-user credentials you should use the delegated permissions process.
- This guide does not apply to Public folder migrations.
- The Use Impersonation to Authenticate checkbox must be enabled in your advanced options' Source/Destination tab.
Otherwise, the following error might arise.
Step One - Create a New Application Registration
Create a new Application Registration in the Microsoft 365 tenant source or destination.
- Log in to the Microsoft Entra admin center with a Global Administrator login.
- Click View all products and select Microsoft ID (Azure AD) in the Microsoft Entra Admin Center.
- In the left sidebar, open the Applications dropdown list and select App Registrations, which is found under the Identity dropdown list.
- Select New Registration at the top of the screen.
- Give the app a distinct name. You can change this later if necessary.
- Select the Accounts in this organizational directory only ('Tenant name only' - Single tenant) radio button.
- Click Register.
- Under the Manage menu, select Authentication.
- Set the option Allow public client flows to Yes.
- Click Save.
Step Two - Assign the API Permissions and Grant Admin Consent
The following steps allow you to assign the API permission and grant consent to the necessary M365 components.
- From the Manage menu, select API permissions.
Important
If an API permission is named User.Read under Microsoft Graph is already present, this can be removed. The Microsoft Graph API does not apply to this project type and is not used. - Click Add a Permission.
- Select APIs my organization uses.
- Scroll down or search for the following permissions Office 365 Exchange Online.
- Select Delegated Permissions.
- Select EWS.
- Check the box under EWS for EWS.AccessAsUser.All.
Important
This permission only allows the OAuth application (MigrationWiz) to be associated with EWS. This does not grant access to all mailbox data. - Click Add a Permission.
- Select APIs my organization uses.
- Scroll down or search for the Office 365 Exchange Online.
- Select Application Permissions.
- Check the box under Other Permissions for full_access_as_app.
- Click Add Permissions.
- Click Grant admin consent.
- Click Yes to confirm the settings. Under the Status column, you should see a message that permission has been granted for the domain.
Step Three - Obtain the AppID and TenantID from the Application Registration
Follow the steps below to obtain the AppID and TenantID from the Application Registration.
- Navigate to the App Registrations item as shown below. In the Overview tab, you will find the Application (client) ID and the Directory (Tenant) ID.
- Copy both of these to another application, such as Notepad, for use later in this process. This is needed for the MigrationWiz Project Setup.
Step Four - Create a Client Secret
Create a Client Secret for the application by following the steps below.
- Go to Manage > Certificates & secrets from the left sidebar.
- Create a new secret client by clicking + New client secret.
- Copy and save the client secrets' value on a notepad or other preferred tool.
Warning
Consider that the secret client's value is only available until the first time you sign off the Azure Portal after the secret client creation. After that, it will be no longer visible.In case you lost the value, please create a new client secret as suggested above and use it in the steps below.
Step Five - Informational Note
Using the Full_Access_As_App in the Application Permissions from Step Two negates the need to run the ConfigureM365Tenant.PS1 script that has been required previously.
The options provided in Step Two do allow the Application Permissions to have full rights to read the mailboxes in the tenant. If you do not want this to be the case, please look at the article here on how to scope the application permissions to only allow access to a smaller set of mailboxes.
Step Six - Set up your MigrationWiz Project
Add the details from the Application Registration into the MigrationWiz project.
- Create your migration project.
- Set up your Endpoints. During this setup, you will be asked for
- Application (Client) ID - Obtained in Step Three
- Directory (Tenant) ID - Obtained in Step Three
- Client Secret - Obtained in Step Six
The correct Application and Directory IDs must be used, from the App Registration screen. These are NOT the values you used in running the ConfigureM365Tenant script above. They are obtained from Step Three and Step Six in these instructions.
Important
Consider that the following support options will appear on the Advanced Options depending on the Microsoft 365 endpoints defined on your project.- ModernAuthClientSecretExport=xxxxxxxxxxxx Where the value is the client secret's value for M365 endpoints at the source.
- ModernAuthClientSecretImport=xxxxxxxxxxxx Where the value is the client secret's value for M365 endpoints at the destination.
These values can only be modified by editing your project's endpoints.
Having the Client Secret with a value in the dialog box notifies the system that you are using the new way of authenticating in the M365 environment. If you are still using the Application Impersonation method, then do not enter a client secret into this box.
Final Notes
The configuration will need to be performed on both the source and destination if they are Microsoft 365 endpoints. This entire process now supersedes the Application Impersonation requirements that have been present in these migrations for many years. As this old process is being deprecated across M365 tenants by Microsoft over the coming year it is highly recommended that this be the 'go-to' method for the setup of MigrationWiz projects from this point.
In case of any questions or concerns about this new method, contact our support team.