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.
Terminology
Basic Authentication
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
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.
Delegated Permissions
Your application needs to access the web API as the signed-in user, but access is limited by the selected permissions. This type of permission can be granted by a user unless the permission is configured as requiring administrator consent.
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.
Authentications Available per Product Type
SharePoint & OneDrive
Modern Authentication - Delegated Permissions - BitTitan App
This authentication method requires the BitTitan permissions app. The steps for this app are described in a 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 destination tenant doesn’t block basic authentication).
Modern Authentication - Delegated Permissions - Customer Tenant App
- SharePoint migrations: Global admin and site collection admin (GA role required to create tenant app)
- OneDrive migrations: will utilize the SharePoint admin credentials. The global admin will create the tenant app and promote their permissions to site collection admin levels for the account being migrated. OneDrive user account provisioning is supported when using SharePoint admin credentials (provided 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 a 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 - Delegated Permissions - Customer Tenant App
- Requires global 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 Azure account.
- Requires admin credentials.
- Requires ClientID and TenantID, which are added via Advanced Options.
Small Business Tenant
Document migrations in the Microsoft 365 Small Business Tenant require some special considerations.
MigrationWiz will support Document Migration, but the Destination has to be configured in the following manner:
While the Source (e.g., Google Drive) is able to use admin credentials, the Destination, Microsoft 365 Small Business Tenant, needs to be configured with the end user credentials. If admin credentials are used, the following error will surface:
Destination |
Your migration failed checking destination credentials. OneDrive for Business administrative authentication failed with <your tenant URL>. |
We use SharePoint administrator API in order to perform auto-provisioning and provide rights to the administrator to access user sites. Some Office 365 plans prevent us from accessing them (Small Business, for example). If your plan doesn't provide access to the SharePoint administrator API, you must use end user credentials.
Enabling Modern Authentication for EWS between MigrationWiz and your Exchange Online Tenant
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 Azure Active Directory and Microsoft 365.
Microsoft's documentation explains enabling and disabling Modern Authentication for Exchange Online.
Prerequisites
- A Global Administrator account with access to Azure Active Directory. MFA/2FA is not supported at this time. The administrator account will need to be excluded from these policies if enabled.
- 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.
Supported Endpoints
Project Type |
Source |
Destination |
---|---|---|
Mailbox |
|
|
Public Folder |
|
|
Personal Archive |
|
|
Hybrid |
|
|
Process (Images are directly below the steps that they represent. Images that represent multiple steps will indicate in bold above the image)
- Log in to the Azure AD admin console with a Global Administrator login.
- Select Azure Active Directory in the Azure Active Directory Admin Center.
- Select App Registrations, which is found under Manage
- Select New Registration at the top of the screen.
Steps 3 - 4 - Give the app a distinct name. You can change this later if necessary.
- Select the Accounts in any organizational directory button.
- Under Redirect Uri, select Public Client (mobile & desktop) and set it to urn:ietf:wg:oauth:2.0:oob
- Click Register.
Steps 5 - 8 - Go back to App registrations.
- Select the App you just created.
Steps 9 - 10 - In the Overview, you will find a ClientId (aka Application) and Directory (Tenant) ID.
- Copy both of these to another application, such as Notepad, for use later in this process.
Steps 11 - 12 - Under the Manage menu, select Authentication.
- Set the option Allow public client flows to Yes.
- Click Save.
Steps 13 - 15 - From the Manage menu, select API permissions.
- If an API permission named User.Read under Microsoft Graph is already present, this can be removed. The Microsoft Graph API is not applicable to this project type and is not used.
- Select Add a Permission.
Steps 16 - 18 -
Select APIs my organization uses
-
Scroll down and select Office 365 Exchange Online
Steps 19 - 20 -
Then 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.
Steps 21 - 24
-
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 the permission has been granted for the domain.
Step 25
Step 26 - In MigrationWiz, select the project that needs to be configured for Modern Authentication.
- Click the Edit Project menu.
- Select Advanced Options.
- Under Support Options enter the ClientID and TenantID information you saved earlier in the following format. Click on the + button to add each.
- If enabling Modern Authentication for the Source:
ModernAuthClientIdExport=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ModernAuthTenantIdExport=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- If enabling Modern Authentication for the Destination:
ModernAuthClientIdImport=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-
ModernAuthTenantIdImport=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Enter the specific ClientID and TenantID for your tenant in place of the xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
- These options can be entered for either the Source or the Destination, or both, depending on the settings on the tenants.
- These options need to be configured for each MigrationWiz project that needs to have Modern Authentication enabled.
- If enabling Modern Authentication for the Source:
- Run a Verify Credentials to confirm that MigrationWiz can connect using Modern Authentication.
- Click on the item that was verified. There will be a message in the MigrationWiz Migration Information page that Modern Authentication is being used. This message will show in the “Migration Errors” box; however, it is not an error. This is just a message confirming that Modern Authentication is now active and being used for connection.
AAD SSO Login
Microsoft 365 AAD login can be enabled on your company's MigrationWiz account by our Support team. 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 AAD 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 AAD login.
- Once your AAD is ready, Support will contact you with instructions.
- You will receive a response from Support when your account is all set up.
If there are any Security Conditional Access Policy at the Azure AD that is blocking the BitTitan Application for MigrationWiz SSO then Exclude the application for the SSO to work.
In order to use the MigrationWiz PowerShell SDK with MigrationWiz SSO, you must use your original MigrationWiz/MSPComplete password, not your Azure AD password.
Enabling Application Permissions
Teams - Global admin & Application Permissions
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 Teams 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 the use of Global Admin or Site Collection Admin permissions on the source and destination. The account being used still needs to be licensed for Teams in the Exchange Online tenant.
This app is similar to the Office 365 Authentication App previously deployed, which utilized delegate permissions. This app uses application permissions. If you are not using application permissions, go to the Authentication App article and follow those steps.
Enable Application Permissions
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 to 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 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 new user. This user must have an active Teams license applied.
-
Add new user to 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.
Steps to enable permission 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 new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal.
-
Create new user. This user must have an active Teams license applied. Important: ADFS and MFA must be turned off for this user.
-
Add new user to 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 tenant 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:
-
Launch PowerShell.
-
Connect PowerShell to Microsoft 365.
-
Enter the command: Connect-AzureAD
-
Enter the admin credentials in the prompt.
-
Enter the command:Get-AzureADServicePrincipal -SearchString Migration.
-
Look for the ObjectId of the app you want to remove and enter the following command: Remove-AzureADServicePrincipal -objectId <the object id>
-
Permissions Granted
Teams ReadOnly | Teams FullControl | |
Conversations | Y | Y |
Teams Permissions | Y | Y |
Documents | Y | Y |
Document Permissions | N | Y |
Read Only permissions granted:
-
-
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 a 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)
-
-
Full Control permissions granted:
-
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
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 the use of 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.
BitTitan applications are fully verified and accepted by Microsoft.
Enable Application Permissions
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 to MigrationWiz-SharePoint-FullControl and consent to the app access when prompted.
- Create new Security Group named “MigrationWiz” on the Office 365 Admin Portal.
- Create new user. This user must have a SharePoint/OneDrive license applied.
- Add new user to previously created security group as a member.
- Create MigrationWiz project.
- When creating the endpoints, enter the new user credentials.
- Add support option UseApplicationPermission=1
Steps to 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 new Security Group named “MigrationWiz” on the Microsoft 365 Admin Portal.
- Create new user. This user must have a SharePoint/OneDrive license applied.
- Add new user to 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 tenant 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:
- Launch PowerShell.
- Connect PowerShell to Microsoft 365.
- Enter the command:
Connect-AzureAD
- Enter the admin credentials in the prompt.
- Enter the command:
Get-AzureADServicePrincipal -SearchString Migration
- Look for the ObjectId of the app you want to remove and enter the following command:
Remove-AzureADServicePrincipal -objectId <the object id>
Permissions Granted
Read Only permissions granted:
- 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)
Full Control permissions granted:
- 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)