#Required Permissions for Gmail Migration

Fly supports the app profile authentication method to connect to your Google tenants, and the service account profile and app profile authentication methods to connect to your destination Microsoft 365 tenants.

#Permissions for Source Gmail

To perform Gmail migrations, the Super Admin can refer to Connect Your Tenants to AvePoint Online Services to connect your Google tenant to AvePoint Online Services at first. Then, you need to create a default or custom Google app profile in AvePoint Online Services > Management > App management to connect to the Google tenant.

Refer to the following sections for details about how to create a default or custom Google app profile with required permissions:

#Create a Default Google App Profile

If you want to use a default Google app profile, refer to the following creation steps and required permissions:

1. Click Create on the App management page in AvePoint Online Services.

2. In the Select servicesstep, select a Google tenant, and choose Fly.

3. Click Next to go to the Choose setup method step.

4. In the Choose setup method step, select Modern mode.

5. Click Next to go to the Consent to apps step.

6. Click Consent.

7. Click Google Workspace Marketplace in the Install app window to go to Google Workspace Marketplace, and click Admin install to install the AvePoint Fly Migration app.

8. Go back to the Create app profile page and click Continue to consent in the Install app window. Then, the Google sign-in page appears.

9. On the Google sign-in page, sign in with a Super Admin account to consent to the app. Then, you can review the Google data that can be accessed by the AvePoint Fly Migration app.

10. Click Finish to consent to the AvePoint Fly Migration app, and you will be redirected to the App management page.

Refer to the sections about permission required by the default app:

#API Requirements

The following APIs are automatically assigned to the app profile after you consent the app.

API Requirements	Google Scopes Permission	Purpose
Gmail API	https://www.googleapis.com/auth/gmail.readonly	Retrieve mails and labels, including data and properties.
Gmail API	https://www.googleapis.com/auth/gmail.settings.sharing	Used to enable email forwarding.
Google People API	https://www.googleapis.com/auth/contacts.readonly	Retrieve contact groups and contacts.
Google Tasks API	https://www.googleapis.com/auth/tasks.readonly	Retrieve all tasks.
Admin SDK API	https://www.googleapis.com/auth/admin.reports.usage.readonly	Retrieve size usage of users.
Admin SDK API	https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly	Retrieve resource calendars.
Admin SDK API	https://www.googleapis.com/auth/admin.directory.user.readonly	Retrieve source users.
Admin SDK API	https://www.googleapis.com/auth/admin.directory.group.readonly	Retrieve source groups.
Google Calendar API	https://www.googleapis.com/auth/calendar	Retrieve calendars and events.
Google Drive API	https://www.googleapis.com/auth/drive.readonly	Retrieve event attachments.
Enterprise License Manager API	https://www.googleapis.com/auth/apps.licensing	Used to retrieve license information.

#Admin Account Permissions

The Admin account permissions will be used in the following situations.

Type	Admin Account Permission	Purpose
Gmail	Users > Read	Migrate Gmail mailboxes.
Gmail	Calendar > All Settings > Buildings and Resources > Room Insights	Migrate Gmail mailboxes.
Gmail	Groups > Read	Migrate Google groups.
Gmail	Reports	Retrieve source data.
Gmail	Make changes to events permission to the calendar, or assign the Super Admin role to the Admin account.	Migrate private calendar events in the resource mailbox.

To assign the Make changes to events permission to the Admin account, refer to the following steps to subscribe and share the calendar to the Admin account:

1. Log in to Gmail using an account with the Super Admin role.

2. Click the Google apps button and click the Calendar app.

3. 

Google apps button.

4. Click the add button of the Other calendars at the bottom of the left pane, then click Browse resources.

5. Click the down arrow button of a resource and select the calendar you want to share with the Admin account. The selected calendar will be subscribed.

6. Click the desired calendar in the Settings for my calendars section in the left pane.

7. Click Add people under the Share with specific people section on the Settings page.

8. Add the Admin account you want to share the calendar in the first text box and select Make changes to events from the permissions drop-down list.

9. Click Send.

#Create a Custom Google App Profile

To use a custom Google app profile, refer to the following steps and required permissions:

1. Click Create on the App management page in AvePoint Online Services.

2. In the Select services step, select a Google tenant, and choose Fly.

3. Click Next to go to the Choose setup methodstep.

4. In the Choose setup method step, select the Custom mode.

5. Click Next to go to the Consent to apps step.

6. In the Consent to apps step, enter the app profile name, admin account, Google service account, and private key of your app.

7. Click Finish.

Refer to the following sections about permissions required for the custom app.

#API Requirements

Make sure the following APIs are enabled in the projects where the service accounts are created.

Refer to the following steps to enable the APIs:

*Note: The user must be the project owner to enable the APIs.

1. Go to Google APIs.

2. Click ENABLE APIS AND SERVICES. The API library page appears.

   

3. Click the API you want to enable respectively.

4. Click ENABLE on the top of the page to enable the corresponding API.

Make sure the API Access in your Google Workspace environment is enabled. Follow the https://support.google.com/a/answer/7281227 provided by Google to ensure all your settings meet the requirements.

#Admin Account Permissions

Make sure the Admin account has the following custom roles.

Type	Admin Account Permission	Purpose
Gmail	Users > Read	Migrate Gmail mailboxes.
Gmail	Calendar > All Settings > Buildings and Resources > Room Insights	Migrate Gmail mailboxes.
Gmail	Groups > Read	Migrate Google groups.
Gmail	Make changes to events permission to the calendar, or assign the Super Admin role to the Admin account.	Migrate private calendar events in the resource mailbox.

*Note: The user must have the Super Admin role to assign permissions and manage roles.

To manage the roles of the Admin account, refer to the following steps:

1. Go to the Google Admin console.

2. Click Manage in the Users section.

3. Click the user you want to assign the roles. The user profile page appears.

4. Click the down arrow button in the Admin roles and privileges section.

5. If you need to assign the Super Admin role to the Admin account, search Super Admin in the search box, then switch on the Assigned state button to assign the role.

6. Click SAVE.

7. Click the Edit button in the upper-right corner of the Roles section.

   

8. Click CREATE CUSTOM ROLE in the upper-right corner of the Roles section.

   

9. Click Create new role.

10. Enter a name for the current role and click CONTINUE.

11. In the Admin console privileges section, select the following privileges:

    • Users > Read

    • Calendar > All Settings > Buildings and Resources > Room Insights

    • Groups > Read

12. Click CONTINUE. The selected privileges will be listed on the Review Privileges page.

13. Click CREATE ROLE.

To assign the Make changes to events permission to the Admin account, refer to the following steps to subscribe and share the calendar to the Admin account:

1. Log in to Gmail using an account with the Super Admin role.

2. Click the Google apps button and click the Calendar app.

3. 

Google apps button.

4. Click the add button of the Other calendars at the bottom of the left pane, then click Browse resources.

5. Click the down arrow button of a resource and select the calendar you want to share with the Admin account. The selected calendar will be subscribed.

6. Click the desired calendar in the Settings for my calendars section in the left pane.

7. Click Add people under the Share with specific people section on the Settings page.

8. Add the Admin account you want to share the calendar in the first text box and select Make changes to events from the permissions drop-down list.

9. Click Send.

#Google Service Account Permissions

To manage a Google service account, refer to the following steps:

*Note: The user must be the project owner to manage service accounts.

1. Go to the Google https://console.cloud.google.com/iam-admin/serviceaccounts.

2. Select the desired project. The accounts in the projects are displayed.

3. To create a new service account, refer to the following steps:

   *Note: If you want to use an existing service account to add the Google Workspace connection, ignore this step.

   1. Click CREATE SERVICE ACCOUNT.

      

   2. Enter a service account name.

   3. Enter the service account ID.

   4. Enter the description for the service account.

   5. Click CREATE AND CONTINUE. The service account is created.

   6. Select the Owner role to the project from the drop-down list and click CONTINUE.

   7. Click DONE.

4. A private key will be used when adding the connection. To obtain the private key of the service account, click the Actions button of an existing service account, click Manage keys, click ADD KEY, and then select Create new key. Select the JSON type and click CREATE to download the private key file.

   *Note: If the service account key creation is disabled in your organization, enable it first by the following steps.

   1. Navigate to Google Cloud > IAM & Admin > IAM.

   2. Click the resource tab and click the domain name as the resource.

   3. 

   4. Click Grant access to access the Grant access to "[Tenant]" panel.

   5. In the Add principals field, enter the email address of the signed-in user.

   6. In the Assign roles field, select the Organization Policy Administrator role from the drop-down list.

   7. Click Save to grant the role for the user to access the selected tenant.

   8. Go to IAM-Disable Service Account Key Creation.

      *Note: Make sure the current project is the project where you create the service account.

   9. Click MANAGE POLICY.

      

   10. Select Override parent's policy to set a unique policy for this project.

       

   11. Click ADD A RULE to add a new rule.

       

   12. Select Off to disable the enforcement of the new rule, and click DONE.

       

   13. Click SET POLICY.

5. Open the .json file with Notepad and find the private key after the "private_key": node. The private key will be used when adding the connection.

6. 

7. Go to the Google https://admin.google.com/ using the Super administrator credentials.

8. Navigate to Security > Overview > API controls.

9. Click MANAGE DOMAIN WIDE DELEGATION.

10. On the Domain-wide Delegation page, click Add new.

    

11. Enter the client ID of the service account in the Client ID field. The client ID can be found in the "client_id": " " node of the .json file in step 5.

12. Enter the following scopes in the OAuth scopes field:

    https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/contacts.readonly,https://www.googleapis.com/auth/tasks.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly,https://www.googleapis.com/auth/gmail.settings.sharing,https://www.googleapis.com/auth/apps.licensing

    The table below lists why the scopes are needed:

Google Scopes Permission	Purpose
https://www.googleapis.com/auth/gmail.readonly	Retrieve mails and labels, including data and properties.
https://www.googleapis.com/auth/gmail.settings.sharing	Used to enable email forwarding.
https://www.googleapis.com/auth/contacts.readonly	Retrieve contact groups and contacts.
https://www.googleapis.com/auth/tasks.readonly	Retrieve all tasks.
https://www.googleapis.com/auth/admin.reports.usage.readonly	Retrieve size usage of users.
https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly	Retrieve resource calendars.
https://www.googleapis.com/auth/admin.directory.user.readonly	Retrieve source users.
https://www.googleapis.com/auth/admin.directory.group.readonly	Retrieve source groups.
https://www.googleapis.com/auth/calendar	Retrieve calendars and events.
https://www.googleapis.com/auth/drive.readonly	Retrieve event attachments.
https://www.googleapis.com/auth/apps.licensing	Used to retrieve license information.

13. Click AUTHORIZE.

#Permissions for Destination Exchange Online

To connect to the destination, you can choose to only use a service account, Fly app profile, or custom app profile as the authentication method. You can also use the combination of a service account and a Fly app profile, or the combination of a service account and a custom app profile.

Refer to the following sections to view the permissions required by the authentication methods.

#Fly App Profile Permissions

With the Tenant Owner or Service Administrator role, you can create a Fly app profile in AvePoint Online Services > Management > App management to connect to the Microsoft 365 tenant using the Fly app.

Refer to Fly App Profile Permissions about how to create a Fly app profile and required permissions of the Fly app profile.

*Note: If you want to perform Exchange Online tenant discovery or Exchange Online to Exchange Online migrations, make sure the account that authorizes the app has a mailbox (either by assigning the Exchange license or using PowerShell to create a mailbox).

*Note: You need to assign the Exchange Administrator role to the AvePoint Fly app in the following situations. Refer to How to Assign the Exchange Administrator Role to an App? for instructions.

If you do not want to assign the Exchange administrator role to the app authorization user, you can add custom roles to the app to ensure the availability of above functions. Refer to How to Add Custom Roles to an App? for details.

#Custom App Profile Permissions

With the Tenant Owner and Service Administrator role, you can create a custom app profile in AvePoint Online Services > Management > App management to connect to the Microsoft 365 tenant using a custom Azure app.

Refer to the following procedures to create a custom app profile:

1. Prepare a certificate in Microsoft Entra ID. Refer to Prepare a Certificate for the Custom Azure App for more information.

   You can ignore this step if you have a certificate.

2. Create a custom Azure app in Microsoft Entra ID. Refer to Create Custom Azure Applications for more information.

3. Connect your tenant to AvePoint Online Services.

4. Create an App Profile for a Custom Azure App in AvePoint Online Services.

*Note: After you re-authorize the app profile, you need to wait about one hour before using the app profile for your migration to refresh the token if there are permissions updated.

Refer to the following tables to add API permissions required by Exchange Online.

Note the following:

API	Permission	Type	Purpose
Office 365 Exchange Online	full_access_as_app(Use Exchange Web Services with full access to all mailboxes)	Application	Retrieve and migrate items from all mailboxes.*Note: If you do not want to add this permission to the app, you can create an RBAC assignment for the app to only access to specified mailboxes. Refer to the option 3 in the How to Migrate Mailboxes without the ApplicationImpersonation Role? section for details.
Office 365 Exchange Online	Exchange.ManageAsApp(Manage Exchange As Application)	Application	Migrate Google groups and mailbox aliases.
Microsoft Graph	User.Read.All(Read and write all users’ full profiles)	Application	Retrieve the information of Microsoft 365 user profiles.
Microsoft Graph	Calendars.ReadWrite(Read and write calendars in all mailboxes)	Application	Required if you want to keep the source Response statuses of event attendees to the destination.
Microsoft Graph	Group.ReadWrite.All(Read and write all groups)	Application	Required when you do not assign the Exchange Administrator role to the app. Retrieve Microsoft 365 Group mailboxes and mailbox types, and create Microsoft 365 Group mailboxes in the destination.

For easy use, you can directly use the following commands to add required API permissions through Manifest for Microsoft 365 Commercial tenants.

"requiredResourceAccess": [

{

"resourceAppId": "00000003-0000-0000-c000-000000000000",

"resourceAccess": [

{

"id": "62a82d76-70ea-41e2-9197-370581804d09",

"type": "Role"

},

{

"id": "df021288-bdef-4463-88db-98f22de89214",

"type": "Role"

},

{

"id": "ef54d2bf-783f-4e0f-bca1-3210c0444d99",

"type": "Role"

}

]

},

{

"resourceAppId": "00000002-0000-0ff1-ce00-000000000000",

"resourceAccess": [

{

"id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",

"type": "Role"

},

{

"id": "dc50a0fb-09a3-484d-be87-e023b12c6440",

"type": "Role"

}

]

}

],

#Service Account Permissions

The Tenant Owner and Service Administrators can also create a service account profile for Microsoft 365 to connect AvePoint Online Services to your Microsoft 365 tenant.

*Note: Users with Multi-Factor Authentication (MFA) enabled cannot be used as the service account to perform migrations. You can use a delegated app profile instead.

Make sure the service account has a mailbox (either by assigning the Exchange license or using PowerShell to create a mailbox) and meets the following requirements:

*Note: To make sure the source service account has a mailbox, go to the Microsoft 365 admin center > Users > Active users, and select Exchange Online under the Licenses and apps tab of the service account.

Required Permission	Note
ApplicationImpersonation role or Full Access permission to destination mailboxes in the migration	Microsoft has announced the retirement of the ApplicationImpersonation role in Exchange Online. Refer to Impact and Solutions for the Retirement of the ApplicationImpersonation Role in Exchange Online for details.If you do not migrate Google groups in the migration, you can grant the Full Access permission without adding the ApplicationImpersonation role.
Mail Recipients role	Retrieve mailboxes when performing Gmail migrations.
Mail Recipient Creation role	Required if you want to create shared mailboxes and resource mailboxes in the destination.
Distribution Groups role	Required if you want to migrate Google groups to distribution groups.
Security Group Creation and Membership role	Required if you want to migrate Google groups to mail-enabled security groups. If the service account is the Exchange Administrator, this role is not required.
Groups administrator role in the admin centers	Required if you want to migrate Google groups to existing Microsoft 365 Groups.

What permissions are required if I also use an app profile?

If you use both service account and app profile authentications for the destination Exchange Online, and the app profile has the Exchange Administrator role, there are no permission requirements for the service account. If the app profile does not have the Exchange Administrator role, some service account permissions will not be required and you need to make sure the service account has a mailbox and the following permissions:

*Note: To make sure the destination service account has a mailbox, go to the Microsoft 365 admin center > Users > Active users, and select Exchange Online under the Licenses and apps tab of the service account.

Destination Service Account Permissions	Note
Mail Recipients role	Retrieve mailboxes when performing Gmail migrations.
Mail Recipient Creation role	Required if you want to create shared mailboxes and resource mailboxes in the destination.
Distribution Groups role	Required if you want to migrate Google groups to distribution groups.
Security Group Creation and Membership role	Required if you want to migrate Google groups to mail-enabled security groups.

#Delegated App Profile Permissions

Fly allows you to use the Fly delegated app profile or custom delegated app profile to connect to your workspace.

To use a delegated app profile, note the following:

To use the Fly delegated app profile with required permissions, refer to Fly Delegated App Profile Permissions.

To use a custom delegated app profile with required permissions, refer to the following steps:

1. After registering an app in Microsoft Entra ID, add the permissions in the table below to the app.

API	Permission	Type	Purpose
Office 365 Exchange Online	EWS.AccessAsUser.All(Access mailboxes as the signed-in user via Exchange Web Services)	Delegated	Access specified user and import data.
Office 365 Exchange Online	Exchange.Manage(Manage Exchange configuration)	Delegated	Use Exchange PowerShell to migrate mailbox permissions, distribution lists, and dynamic distribution lists.
Microsoft Graph	Domain.Read.All(Read domains)	Delegated	Create Microsoft 365 Group mailboxes.
Microsoft Graph	Group.ReadWrite.All(Read and write all groups)	Delegated	Create Microsoft 365 Group mailboxes.

"requiredResourceAccess": [

{

"resourceAppId": "00000003-0000-0000-c000-000000000000",

"resourceAccess": [

{

"id": "2f9ee017-59c1-4f1d-9472-bd5529a7b311",

"type": "Scope"

},

{

"id": "4e46008b-f24c-477d-8fff-7bb4ec7aafe0",

"type": "Scope"

}

]

},

{

"resourceAppId": "00000002-0000-0ff1-ce00-000000000000",

"resourceAccess": [

{

"id": "ab4f2b77-0b06-4fc1-a9de-02113fc2ab7c",

"type": "Scope"

},

{

"id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",

"type": "Scope"

}

]

}

],

1. Click Authentication in the left navigation of the app.

2. Click Add a platform.

3. Select Web in the Configure platforms panel.

4. In the Configure Web panel, enter the AvePoint Online Services URL: https://www.avepointonlineservices.com for your commercial environment or https://usgov.avepointonlineservices.com for your U.S. Government environment in the Redirect URIs field.

5. 

6. Click Configure.

7. Select the Access tokens and ID tokens checkboxes on the Authentication page.

   

8. Click Save.

9. Create an app profile for the app using the Custom mode in AvePoint Online Services by referring to Consent to a Custom Azure App with Delegated Permissions.

10. *Note: When consenting to the app, if you have granted the admin consent and allowed public client flows for the permissions, you can choose to use the Global Administrator consent or the User consent method. If not, you can only use the Global Administrator consent method.