1. BitTitan Help Center
  2. Perform a Migration
  3. Microsoft Migrations
  4. Exchange Online Mailbox Migrations using Graph API
  5. Exchange Online Authentication options using Graph API

Authentication Requirements for Graph API using the BYO App with Client Secret

This article covers the authentication requirements using the BYO App with Client Secret, the supported migration scenarios, and the setup steps for using Graph API with Microsoft 365 endpoints in MigrationWiz.

Find the authentication steps required to enable Graph API for your migration scenario below. For more information, see Microsoft Graph permissions and consent.

Retirement of Exchange Web Services in Exchange Online

Microsoft has announced a phased retirement of Exchange Web Services (EWS) in Exchange Online, beginning October 1, 2026, with final retirement on April 1, 2027. To ensure migrations continue without disruption, BitTitan is transitioning Microsoft 365 endpoint connectivity to Microsoft Graph API ahead of that deadline.

What this means to you:

  • EWS remains fully supported by MigrationWiz today and will continue to work for most scenarios until closer to Microsoft's final retirement date in April 2027. The official retirement date for MigrationWiz will be announced.
  • Plan your transition to Graph API ahead of the 2027 deadline rather than waiting until EWS is fully disabled.

Supported Scenarios

At this time, Graph API authentication is supported only for Mailbox migrations, including the following scenarios:

Exchange/Microsoft 365 as Source

Google Workspace as Source

Other Mailbox Migrations as Source

Important

Scenarios not listed above (e.g. Public Folder, Microsoft 365 Groups conversations and Archive Mailbox Migrations) continue to use EWS authentication. Refer to Authentication Methods for Microsoft 365 (All Products) Migrations for those endpoint types.

Prerequisites

Before you begin your migration process using Graph API endpoints, review the following requirement:

  • End-user credentials are not supported. Due to the permission types required for the Entra ID Application, a Global Administrator must be used to consent to the BitTitan app and/or create and consent to the BYO (Bring Your Own Application) in your tenant.

Register and Configure your Application

The following steps outline the necessary steps to set up the tenant, register the application, and assign the required permissions.

If you decide to use this alternative, below, you can find the available authentication options for implementing it in your projects. 

Using the BYO App with Client Secret Key

This section provides step-by-step instructions to create a Bring Your Own (BYO) using Client Secret in a Mailbox Project, configure source and/or destination endpoints using Client Secret Key.

Step 1: Register and Configure your Application

Create a New Application Registration

Create a new Application Registration in the Microsoft 365 tenant source or destination.

  1. Log in to the Microsoft Entra admin center with a Global Administrator login.
  2. Click View all products and select Microsoft ID (Azure AD) in the Microsoft Entra Admin Center.
  3. In the left sidebar, open the Applications dropdown list and select App Registrations, which is found under the Identity dropdown list.
  4. Select New Registration at the top of the screen.
    1. New App Registration.png
  5. Enter a distinct name for the application.
  6. Select the Accounts in this organizational directory only ('Tenant name only' - Single tenant) from the dropdown menu.
  7. Under the Redirect URI, select Public client /native (mobile & desktop application),then add the https://auth.bittitan.com/permissions as the redirect URI.
  8. Click Register.
    Register an Application + URI.png
  9. Under the Manage menu, select Authentication (preview).
  10. Select the Settings tab.
  11. Set the option Allow public client flows to Enabled. 
  12. Click Save.
    Enable Authentication Preview.png
  13. From the left Manage menu, select Certificates & Secrets.
  14. Click New Client Secret. 
  15. Enter a description for your new Client Secret, select an expiration date from the dropdown, and then click Add.
    Add Client Secret.png

  16. Copy and save the Client Secret Value (Not the Secret ID). You will need this value later to configure your endpoint.

    Important

    Copy and save the Client Secret Value. This value is only visible on this page. Once you navigate away, it is masked and cannot be retrieved again.

  17. From the left navigation menu, click Overview to view your tenant's details. 
  18. Copy and save the Application (client) ID and the Directory (tenant) ID. You will need both values later to configure your endpoint.
    App ID and Directory ID.png

Assign the API Permissions and Grant Admin Consent

The following steps allow you to assign the API permissions and grant consent to the required M365 components.

  1. From the Manage menu, select API permissions.
  2. Click Add a Permission.
    5. API Permissions_1.png
  3. Select APIs my organization uses.
  4. Select Application Permissions.

  5. Scroll down or search for Office 365 Exchange Online and add Exchange.ManageAsApp.

    Note

    This permission is required to migrate calendar folder permissions and mailbox folder permissions. 

  6. Click Add Permission.
  7. Select Graph API.
  8. Select Application Permissions.Graph APIs Source.png
  9. Scroll down or search for the following Graph API permissions.

    • For the Source tenant:

      Permission Name Type Data Type Purpose
      Mail.Read Application Mail Read mail messages and folder structure from source mailbox
      Calendars.Read Application Calendar Read calendar events from source mailbox
      Contacts.Read Application Contacts Read contacts from source mailbox
      Tasks.Read.All Application Tasks Read Microsoft To-Do task lists and tasks from source mailbox
      MailboxSettings.Read Application Mailbox Read mailbox settings (timezone, language, OOF rules)
      User.Read.All Application User Resolve user objects for application impersonation

    • If you are using the Exchange Online using Graph API (Microsoft 365) to Exchange Online using Graph API (Microsoft 365) Mailbox Migration Guide using Coexistence guide, add the following permissions to the BYO App in your Source tenant:

      Permission Name Type Data Type Purpose
      Group.Read.All Application User Read security groups, distribution lists, and O365 groups on the source side
      Organization.Read.All  Application Organization Read tenant-level configuration (domains, licensing SKUs) when applying licenses

    • For the Destination tenant:

      Permission Name Type Data Type Purpose
      Mail.ReadWrite Application Mail Create mail messages and folders at destination mailbox
      Calendars.ReadWrite Application Calendar Create calendar events at destination mailbox
      Contacts.ReadWrite Application Contacts Create contacts at destination mailbox
      Tasks.ReadWrite.All Application Tasks Create Microsoft To-Do task lists and tasks at destination mailbox
      MailboxSettings.ReadWrite Application Mailbox Apply mailbox settings (OOF, timezone, language) at destination
      User.Read.All Application User Resolve user objects for application impersonation

    • If you are using the Exchange Online using Graph API (Microsoft 365) to Exchange Online using Graph API (Microsoft 365) Mailbox Migration Guide using Coexistence guide, add the following permissions to the BYO App in your Destination tenant:

      Permission Name Type Data Type Purpose
      User.ReadWrite.All Application User Create users in the destination tenant during pre-migration and update user properties
      Group.ReadWrite.All Application Group Create groups in the destination tenant and update group properties
      GroupMember.ReadWrite.All Application Group Members Read and write group conversations
      Directory.ReadWrite.All  Application Directory Assign licenses to newly created destination users and write directory-level objects (roles, group memberships) used during security-group cloning
      Organization.Read.All Application Organization Read tenant-level configuration (domains, licensing SKUs) when applying licenses

    • If you are using the Google Groups to Microsoft 365 Shared Mailbox using Graph API Migration guide, add the following permissions to the BYO App in your Destination tenant:

      Permission Name Type Data Type Purpose
      Group.ReadWrite.All Application Group Read and write all groups
      Group-Conversation.ReadWrite.All Application Organization Read and write group conversations

    • If you are using the IMAP/POP to Microsoft 365 using Graph API Mailbox Migration or the Zimbra 6+ to Microsoft 365 using Graph API Migration guide, add the following permission to the BYO App in your Destination tenant:

      Permission Name Type Data Type Purpose
      Mail.Send Application Mail Required for MIME Content extracts for IMAP, Pop and Zimbra as source for import in the destination using Graph
  10. Click Add Permissions.
  11. Click Grant admin consent. The example below shows the source tenant permissions in a mailbox project.
    Graph Admin Consent Source.png
  12. Click Yes to confirm the settings. The Status column shows that permission was granted for the domain.

Grant the Application Exchange Administrator Role

The following steps allow you to grant the Exchange Administrator role to your application.

  1. From the Entra Admin Center menu, select Roles & admins.
  2. In the search bar, type Exchange, then click on Exchange Administrator.
    Exchange Admin.png
  3. On the Exchange Administrator role assignments page, click Add assignments.
  4. Search for your Application name to grant this role and mark the checkbox.
  5. Click Add.
    Graph Add Assignments.png
  6. A confirmation message, "Successfully Added Assignment", appears in the top right corner.

Step 2: Create your Project and Select Endpoint Type

Follow the steps below to configure your project:

Source Endpoint

The following steps outline the source endpoint creation:

  1. Go to Projects.
  2. Click Create Project.
  3. Select Mailbox Project.
  4. Enter the project information: add a Project Name, select a Customer from the drop-down list or create a new one, then click Next Step.
  5. Click New.
  6. Name the endpoint. It is recommended to use a unique endpoint name for the project.
  7. Go to Endpoint Selection.
  8. From the list, select Microsoft 365 Graph API.
    Microsoft 365 Graph API Endpoint.png
  9. Click Add.

Destination Endpoint

The following steps outline the destination endpoint creation:

  1. Click New.
  2. Name the endpoint. It is recommended to use a unique endpoint name for the project.
  3. Go to Endpoint Selection.
  4. From the list, select Microsoft 365 Graph API.
    Microsoft 365 Graph API Endpoint.png
  5. Click Add.
  6. Click Save Project.

Step 3: Configure Graph API Endpoint

After adding your Endpoint, configure it in the Source/Destination settings screen following these steps:

Source Endpoint

  1. Check the Use BYO Application checkbox as shown below, then select the Use Client Secret radio button.
    1. BYO Source.png
  2. Use Application Permission is already selected for the Permissions setting. Although present, Delegated Permissions are currently disabled and cannot be selected.
    2. BYO Source.png
  3. Enter the following details (find these values on the Overview page in Entra ID for your application, in your tenant):
    • Modern Auth Client ID
    • Directory (tenant) ID
      3. BYO Source.png
  4. Enter the Client Secret ID (this is the Client Secret Value you saved when you created the application in your tenant, Step 16 of this section).4. BYO Source.png
  5. Click Next Step.

Destination Endpoint

  1. Check the Use BYO Application checkbox as shown below, then select the Use Client Secret radio button.
    1. BYO Destination.png
  2. Use Application Permission is already selected for the Permissions setting. Although present, Delegated Permissions are currently disabled and cannot be selected.
    2. BYO Destination.png
  3. Enter the following details (find these values on the Overview page in Entra ID for your application, in your tenant):
    • Modern Auth Client ID
    • Directory (tenant) ID
      3. BYO Destination.png
  4. Enter the Client Secret ID (this is the Client Secret Value you saved when you created the application in your tenant, Step 16 of this section).4. BYO Destination.png
  5. Click Next Step.
  6. On the Project Setting page, click Save and Go to Summary. Do not check either of the boxes shown below, unless you are using the Exchange Online using Graph API (Microsoft 365) to Exchange Online using Graph API (Microsoft 365) Mailbox Migration Guide using Coexistence guide.
    Project Setting Page.png

Step 4: Review the Project Summary and Grant Consent

After configuring both Source and/or Destination endpoints you need to grant consent to the Entra ID Application in your tenant with MigrationWiz.

Note

An account with a Global Administrator role is required to grant consent.  

Graph Consent.png
  1. Click on the Application Consent button as shown above. You are redirected to Microsoft Identity Platform (Login Page). The account used to login need to have the Global Administrator role in the tenant.
  2. If the Consent is successful, the following message appears in your browser. Close the page and continue with the next step.
    Successful Authorization.png
  3. Once Consent is successful for the Source/Destination tenant, the status changes from Pending Authorization to Authorized.
    Graph Project Summary.png

Consent Flow:

  • Click on Application Consent.
  • Sign in using Global Administrator credentials.
  • Review permissions requested by the application. 
    The API Permissions included in this step should match the permissions granted in the Assign the API Permissions and Grant Admin Consent section for your source/destination endpoint.
Was this article helpful?
0 out of 0 found this helpful

Articles in this section