Authentication and permission management for Microsoft 365 can be complex and varies by type. This article covers the various types of authentication, what scenarios they apply to, and special cases.
The specific authentication needed, and the steps to enable it, will be found in the migration guide for your specific scenario.
Basic Authentication is no longer supported between MigrationWiz and Exchange Online endpoints as of the end of December 2022 due to Microsoft discontinuing support for Basic Authentication in Exchange Online. Basic Authentication will not be supported after that and configuring MigrationWiz to use Modern Authentication will be required.
Modern authentication is based on the use of OAuth 2.0 tokens and the Active Directory Authentication Library. It notably adds support for multifactor authentication, in which a secondary challenge besides a password is used to verify a user's identity, such as previously set personal questions.
With Delegated Permissions, your application needs to access the web API as the signed-in user, but the selected permissions limit access. A user can grant this type of permission unless the permission is configured as requiring administrator consent.
With Application Permissions, your application needs to access the web API directly as itself (no user context). This type of permission requires administrator consent and is also not available for native client applications.
SharePoint & OneDrive
Modern Authentication - Delegated Permissions - BitTitan App
This authentication method requires the BitTitan permissions app. The steps for this app are described in the following section.
Global admin credentials are required for this method.
- SharePoint migrations: Site Collection admin credentials
- OneDrive migrations: will utilize the SharePoint admin credentials. The admin will be promoted to a site collection admin for the OneDrive account being migrated. OneDrive user account provisioning is supported when using SharePoint admin credentials (provided the destination tenant doesn’t block basic authentication).
Modern Authentication - Application Permissions - BitTitan App
This authentication method requires the BitTitan permissions app. The steps for this app are described in the following section.
- This method uses user credentials, but the user will need to be a member of a created MigrationWiz security group in the Microsoft 365 tenant.
- Global admin permissions are required to give consent to the BitTitan app.
- OneDrive provisioning is not supported and only admin cred flow is supported.
- Requires the Advanced Option UseApplicationPermission=1
Teams
Modern Authentication - Delegated Permissions - BitTitan App
This authentication method requires the BitTitan permissions app. The steps for this app are described in the Teams to Teams migration guide.
- Requires global admin or Teams admin credentials.
- Requires the Advanced Option UseDelegatePermission=1
Modern Authentication - Application Permissions - BitTitan App
This authentication method requires the BitTitan permissions app. The steps for this app are described in the Teams to Teams migration guide.
- This method uses user credentials, but the user will need to be a member of a created MigrationWiz security group in the Microsoft 365 tenant.
Microsoft 365
Modern Authentication - Delegated Permissions
- Created in the customer's Microsoft Entra account.
- Requires admin credentials.
Small Business Tenant
Document migrations in the Microsoft 365 Small Business Tenant require some special considerations.
MigrationWiz supports Document Migration, but the Destination has to be configured in the following manner:
While the Source (e.g., Google Drive) can use admin credentials, the Destination, Microsoft 365 Small Business Tenant, must be configured with the end user credentials. If admin credentials are used, the following error arises:
Destination: Your migration failed to check destination credentials. One Drive for Business administrative authentication failed with <your tenant URL>.
We use SharePoint administrator API to perform auto-provisioning and provide the administrator rights to access user sites. Some Office 365 plans prevent us from accessing them (Small Business, for example). If your plan does not provide access to the SharePoint administrator API, you must use your end-user credentials.
Obtain Client and Tenant ID Settings for Mailbox and Exchange Online Migrations
BitTitan only supports Modern Authentication for Microsoft 365 endpoints used for Mailbox, Online Archive mailbox, and Public Folder migrations. Modern Authentication provides a more secure authentication mechanism for registered applications to connect to Microsoft Entra ID and Microsoft 365.
Microsoft's documentation explains enabling and disabling Modern Authentication for Exchange Online.
Prerequisites
- A Global Administrator account with access to Microsoft Entra ID.
- MigrationWiz Mailbox project(s) created and ready for configuration.
- End-user credentials are not supported. Administrator credentials must be used for the endpoints in the MigrationWiz project
- The application will require administrator consent.
Warning
App password usage, MFA/2FA, and ADFS are not supported for the migration admin account/service account being used by these endpoints. The administrator account will need to be excluded from these policies if enabled.Supported Endpoints
Project Type |
Source |
Destination |
---|---|---|
Mailbox |
|
|
Public Folder |
|
|
Personal Archive |
|
|
Hybrid |
|
|
Registration and Configuration
Mailbox and Personal Archive
In case you want to register and set up your Mailbox and Personal Archive endpoints we strongly recommend you follow the steps outlined in the API Permissions for Application Impersonation article.
The approach outlined in the article contains important information about the setup of the tenant, the application registration, the replacement of the Application Impersonation role in M365, and the assignment of permissions.
Microsoft 365 Groups Endpoints
If you want to set up a Microsoft 365 Groups endpoint please consider the following recommendations.
- Configuration without ModernAuthClientSecret: Avoid using ModernAuthClientSecret in the advanced options. Instead, use ClientId, TenantId, and Global/Exchange Admin credentials.
- Connector User Ownership: Ensure that the connector user is the owner of the Microsoft 365 Group being migrated.
- Utilize Recipient Mappings: Implement recipient mappings for mapping user attributes during the migration. For more information, please check the recipient mapping section of the Advanced Options and General Options article.
- Please note that for Google Groups to Shared Mailbox, a Global Admin is required for the destination if you wish to migrate members.
Public Folder
Important
Below the steps, please find corresponding images representing each step or a group of steps.
- 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 any organizational directory (Any Microsoft Entra ID tenant - Multi Tenant) radio button.
- Under Redirect URI (optional), select Public client/native (mobile & desktop) and set it to urn:ietf:wg:oauth:2.0:oob
- Click Register.
- 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.
- Under the Manage menu, select Authentication.
- Set the option Allow public client flows to Yes.
- Click Save.
- 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.
- Click Add Permissions. This permission only allows the OAuth application (MigrationWiz) to be associated with EWS.
Important
This does not grant access to all mailbox data. - 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.
Google Groups to O365 Migrations
For this type of migration, some API permissions must be added to the destination tenant. To complete the process you must follow the next steps:
- Repeat steps 15 and 16.
- Search Microsoft Graph.
- Then select Delegated Permissions.
- Select permissions below and click Add Permissions.
- Directory.ReadWrite.All
- Group.ReadWrite.All
- GroupMember.ReadWrite.All
- User.Read.All
- Click Grant admin consent.
- Click Yes to confirm the settings.
Once you created a MigrationWiz project, do not forget to use the credentials you use here. These are required when setting up your endpoints (source and destination).
Warning
Please consider that you will not be able to save your project if you do not complete these fields, the credentials (client or tenant) are incorrect, or the credentials do not belong to the tenant.
Besides, remember that the client secret field is only mandatory for mailbox and archive endpoints.
Common Errors when Configuring Your Endpoint
For more information, review the AADSTS700016, AADSTS90002, and ADDSTS50126 issues on the Common Errors Using Modern Authentication page.
Make sure to complete the Application (client) ID and the Directory (tenant) ID fields, otherwise, the following warnings arise and you cannot go to the next step.
This happens when configuring the source or destination endpoints.
Invalid Application Client ID at Source Settings
Check whether the Application ID has been installed before or if it is the right one. For more information, refer to AADSTS700016.
Invalid Directory Tenant ID at Source Settings
Check whether the Directory Tenant ID has been installed before or if it is the right one. For more information, refer to AADSTS90002.
In case an Invalid Username or Password at source settings or client settings occurs a warning arises. Make sure that your credentials are the correct ones.
For more information, refer to ADDSTS50126.
Microsoft Entra SSO Login
Our Support team can enable the Microsoft 365 Microsoft Entra login on your company's MigrationWiz account. Note that SSO login happens at the domain level, which means all users with the domain you request will therefore be required to sign in with their Microsoft 365 Microsoft Entra logins - for example, instead of enabling SS just for You@company.com, it would be enabled for all users of @company.com.
To set this up, you must have at least one MigrationWiz account with the same domain as your Microsoft 365 account. We do not support other SSO providers at this time.
- Contact our Support team.
- Our support team will set up your account to use Microsoft Entra login.
- Once your Microsoft Entra is ready, Support will contact you with instructions.
- You will receive a response from Support when your account is all set up.
If any Security Conditional Access Policy at Microsoft Entra is blocking the BitTitan Application for MigrationWiz SSO then Exclude the application for the SSO to work.
To use the MigrationWiz PowerShell SDK with MigrationWiz SSO, you must use your original MigrationWiz/MSPComplete password, not your Microsoft Entra password.
Enabling Application Permissions
Teams - Global admin & Application Permissions
Warning
App password usage, MFA/2FA, and ADFS are not supported for the migration admin account/service account being used by this endpoint.In recent updates, the AO ‘UseApplicationPermission=1’ has been defaulted. Use Teams-FullControlApp for both Source and Destination.
MigrationWiz now supports read-only Application Permissions for Team migrations, in addition to full-control permissions. This new app, with ReadOnly permissions, can only be used at the source to enhance security and will not export document permissions. The destination permissions will always require FullControl permissions.
This allows for a secure migration without using Global Admin or Site Collection Admin permissions on the source and destination. The account still must be licensed for Teams at Exchange Online tenant.
This app is similar to the Office 365 Authentication App previously deployed, which utilized delegate permissions. This app uses the application permissions. If you are not using application permissions, go to the Authentication App article and follow those steps.
Enable Application Permissions
Enable Permissions at Source
These are the steps to enable permission level at the source only. This authentication process gives you control over who is entitled to use the source.
-
Ensure you are signed in as a Global Admin in the Office 365 Admin Portal.
-
Go to either Teams-ReadOnlyApp or Teams-FullControlApp and consent to the app access when prompted. If choosing the Teams-ReadOnlyApp option, you will need to disable AMR via "DisableAsynchronousMetadataRead=1", due to Microsoft API limitation.
-
Create a new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal. If you have not created a security group before, follow Microsoft's instructions.
-
Create a new user. This user must have an active Teams license applied.
-
Add a new user to the previously created security group as a member. Important: ADFS and MFA must be turned off for this user.
-
Create MigrationWiz project.
-
When creating the endpoints, enter the new user credentials.
Enable Permissions at Destination
These are the steps to enable the permissions level at the destination.
-
Ensure you are signed in as a Global Admin.
-
Go to Teams-FullControlApp and consent to the app access when prompted.
-
Create a new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal.
-
Create a new user. This user must have an active Teams license applied. Important: ADFS and MFA must be turned off for this user.
-
Add a new user to the previously created security group as a member.
-
Create MigrationWiz project.
-
When creating the endpoints, enter the new user credentials.
Teams-FullControlApp may be used on both source and destination tenants and will export document permissions. Teams-ReadOnly can only be used on the source tenant, and will not export document permissions.
Post-Migration Steps
-
Remove the newly created user.
-
Remove the MigrationWiz Security Group created in Step 3.
To remove the app from the source or destination, perform the following steps:
- Sign in to Microsoft Entra admin center.
- Select Microsoft Entra ID.
- Go to Identity > Applications > Enterprise applications, in the left bar of the window.
- In the Manage section, select All applications.
- Search for the application permission you configured (Teams-FullControlApp), and select it.
- Go to Manage > Properties, and select Delete from the properties bar.
Permissions Granted
Teams ReadOnly | Teams FullControl | |
Conversations | Y | Y |
Teams Permissions | Y | Y |
Documents | Y | Y |
Document Permissions | N | Y |
The following permissions are granted for Read Only.
SharePoint API
- Sites.Read.All
- User.Read.All
Graph API
- Files.Read.All
- Group.ReadWrite.All
(This is to add the user to the team as an owner first before being able to read conversations) - User.Read.All
- Group.Read.All (delegate permission)
(This is to be able to read all the conversations as a user after being added) - User.Read (delegate permission)
The following permissions are granted for Full Control.
SharePoint API
- Sites.FullControl.All
- User.ReadWrite.All
Graph API
- Files.Read.All
- Group.ReadWrite.All
- User.Read.All
- Group.ReadWrite.All (delegate permission)
- User.Read (delegate permission)
SharePoint & OneDrive
Warning
App password usage, MFA/2FA, and ADFS are not supported for the migration admin account/service account being used by this endpoint.MigrationWiz now supports read-only Application Permissions for SharePoint and OneDrive migrations, via use of the support option UseApplicationPermission=1, in addition to full control permissions. This new app with ReadOnly permissions, can only be used at the source to enhance security. The destination permissions will always require FullControl permissions.
This allows for a secure migration without Global Admin or Site Collection Admin permissions on the source and destination.
This app is similar to the Office 365 Authentication App previously deployed, which utilized delegate permissions. This app uses application permissions.
Microsoft has fully verified and accepted BitTitan applications.
Enable Application Permissions
Enable Permissions at Source
These are the steps to enable permission level at the source only. This authentication process gives you control over who is entitled to use the source.
- Ensure you are signed in as a Global Admin.
- Go to either MigrationWiz-SharePoint-ReadOnly or MigrationWiz-SharePoint-FullControl and consent to the app access when prompted.
- Create a new Security Group named “MigrationWiz” on the Office 365 Admin Portal.
- Create a new user. This user must have a SharePoint/OneDrive license applied.
- Add a new user to the previously created security group as a member.
- Create MigrationWiz project.
- When creating the endpoints, enter the new user credentials.
- Add support option UseApplicationPermission=1
Enable Permissions at Destination
The following steps enable permission level at the destination.
- Ensure you are signed in as a Global Admin.
- Go to MigrationWiz-SharePoint-FullControl and consent to the app access when prompted.
- Create a new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal.
- Create a new user. This user must have a SharePoint/OneDrive license applied.
- Add a new user to the previously created security group as a member.
- Create MigrationWiz project.
- When creating the endpoints, enter the new user credentials.
MigrationWiz-SharePoint-FullControl may be used on both source and destination tenants and will export document permissions. MigrationWiz-SharePoint-ReadOnly can only be used on the source tenant, will not export document permissions, and cannot use AMR.
Post-Migration Steps
- Remove the newly created user.
- Remove the MigrationWiz Security Group created in Step 3.
To remove the app from the source or destination, perform the following steps:
- Sign in to Microsoft Entra admin center.
- Select Microsoft Entra ID.
- Go to Identity > Applications > Enterprise applications, in the left bar of the window.
- In the Manage section, select All applications.
- Search for the application permission you configured (Teams-FullControlApp), and select it.
- Go to Manage > Properties, and select Delete from the properties bar.
Permissions Granted
The following permissions are granted for Read Only.
SharePoint API
- Sites.Read.All
- User.Read.All
Graph API
- Directory.Read.All
- Files.Read.All
- Group.Read.All (delegate permission)
- User.Read (delegate permission)
The following permissions are granted for Full Control.
SharePoint API
- Sites.FullControl.All
- User.ReadWrite.All
Graph API
- Directory.Read.All
- Files.Read.All
- Group.Read.All (delegate permission)
- User.Read (delegate permission)