Set up Google API for Migrating Mailboxes

Using the Google API for migration allows mailboxes to be migrated even when IMAP is disabled on the Google tenant. This article covers setup, frequently asked questions, and the difference between API and IMAP endpoints.

MigrationWiz now offers G Suite (Google API) as a source endpoint when your destination endpoint is also the G Suite (Google API), in addition to the G Suite (IMAP) source endpoint. As this is a new feature, we want to give you an overview of the changes, and how to utilize this functionality.

How is this different from the IMAP endpoint?

Many corporate policies disable IMAP automatically due to security concerns. While this can usually be worked around, it adds another step to the complexity of the process. With the API endpoint, that step is skipped.

Changing from IMAP to API does not make your company or client less secure, however. With this feature, you can use your own G Suite account for the migration, rather than using a BitTitan service account. This also increases your throughput and circumvents a known issue on IMAP that causes problems with the end-user credentials.

The API endpoint is also faster than IMAP, allowing you to complete your migration and get back to work sooner. 

What items will migrate with this endpoint?

All items listed in our MigrationWiz: Migrated and Not Migrated Items article will still migrate. Note that these items will vary by source and destination, so check the proper environment listings carefully. This list is updated frequently, so we strongly suggest checking back regularly during your migration project.

How does this change my migration process?

If you’re still using the IMAP endpoint, there are no changes to the existing process. If you choose the new G Suite (Google API) endpoint, you will be prompted to upload your credentials via JSON during the setup steps below.

Can I switch between the IMAP and API endpoints during a single migration?

No. Each endpoint uses a different watermark. Switching the endpoints mid-stream will cause duplicates at the destination, so MigrationWiz will present an error if this is attempted.

If my source and destination are both the API endpoint, do I need separate service accounts?

You can either create separate service accounts for the source and destination, or have a common service account. If you have a common service account, skip Steps 1-3 below and begin with Step 4. For separate service accounts, follow all steps below. 

People API

Contacts API sunsetting and adoption of People API

Google is shutting down the Contacts API on June 15th 2021. Click here to read the official announcement from Google. As per guidelines from Google, MigrationWiz is switching over to use People API.

  • Effective June 3rd, 2021, all new mailbox migration projects set up with Google as source or destination will use People API. Please refer to respective migration guide to capture relevant details required for project setup.

    • All existing projects which are set up before the People API change is implemented on June 1st will continue to use Contacts API by default.  We would recommend completing such projects before June 15th. After June 15th, such projects may encounter errors while migrating contacts.

Here is the summary of new changes required during project setup:

With the implementation of People API to migrate contacts, please make note of the following limitations/known behaviors:

    1. We are unable to update "Other Contacts" at destination (Google). 

      1. When you select the advanced option to migrate 'Other Contacts', Contacts appearing under the ‘Other Contacts’ label in the source will be migrated to the destination with the label 'Suggested contacts'. 

      2. Please note that the contact information for 'Other Contacts' migrated to the destination will only support name, email, and phone numbers. Other fields are not supported.

    2. Hidden contacts from source (Google) will not retain the 'hidden' property when migrated to the destination. These contacts will show up under the main contact lists as well as with associated labels.

Migrating with Google API

Prerequisites:

  • Subscription to Google Cloud Platform.
  • Google Super Administrator account.
  • Ability to set up a service account on the G Suite tenant.
  • Service account must be set up before the MigrationWiz project is created.

Step 1: Create a Google Project:

  1. Go to the Google Cloud Platform (GCP) Console and sign in as a super administrator. Choose one of the options below:
    • If you haven't used the Google Cloud Platform Console before, agree to the Terms of Service and click Create Project.
    • If you have used Google Cloud Platform Console before, at the top of the screen next to your most recent project name, click Down to open your projects list. Then, click New Project.
  2. Enter a project name and click Create.

Step 2: Enable APIs for Service Account

  1. From the Google Cloud Platform Console, click Menu (Google_Menu.png) > APIs & Services > Library.
  2. Enable the following APIs by selecting the specific API and clicking Enable. Repeat for each API:
    • Google Calendar API
    • Gmail API
    • Contacts API
    • People API
    • Admin SDK

Make sure that the Gmail, Calendar, and Contacts services are enabled within the Google tenant. You can control services for your users using the instructions on this page: Control who can access G Suite and Google Services.

Step 3: Create Customer Tenant Service Account

  1. From the Google Cloud Platform Console, click Menu (Google_Menu.png) > IAM & Admin > Service accounts.
  2. Click Create Service Account and enter a name.
  3. Click Create.
  4. Assign the role of Owner to the new Service Account by selecting Owner from the Role Dropdown menu.
  5. Click Continue.
  6. Click Done.
  7. Click the three dots to the right of the service account and select Create Key.
  8. Make sure that JSON is selected and click Create.
    • Make sure that you download the key as a JSON file and make a note of the name and location of the file. This JSON file will be used when setting up the migration endpoint in the Mailbox Migration project.
    • The JSON file must contain information in the following fields: “type”, “private key”, and “client email”. If these mandatory fields are empty the file upload during endpoint creation will fail.
  9. Click Close.

Step 4: Setting the Scopes for the migration

  1. From the Google Cloud Platform Console, click Menu (Google_Menu.png) > IAM & Admin > Service accounts.
  2. Find the service account that was set up in Step 3.
  3. Find the Unique ID field for that service account and copy the ID number. This is the Client ID number that will be used in a later step.
    • This field often needs to be added to the view. Click on the Column display options button (UniqueID2.png) and add a checkmark to Unique ID, then click OK.
    • This Client ID should be considered similar to Administrator account passwords and handled securely.

You will now have one of two options, depending on if the Google UI has been updated in your tenant.

Old Google Tenant:

Go to the G Suite admin page at google.com.

Click Security.

Click Advanced Settings.

Click Manage API Client Access.

OR If your account shows the latest UI updates from Google:

Go to the G Suite admin page at google.com.

Click Security.

Click API Controls.

Under ‘Domain-wide delegation’, click Manage domain-wide delegation.

On the Manage domain-wide delegation page, click Add new.

In the Client Name field, paste the Unique ID copied above.

 Once these steps are complete:

  1. Enter one of the following groups of scopes into the OAuth Scopes (comma-delimited) field, depending on whether G Suite is the Source or Destination.

G Suite as the Source (read-only scopes):
https://mail.google.com/, https://www.google.com/m8/feeds, https://www.googleapis.com/auth/contacts.readonly, https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/drive, https://sites.google.com/feeds/, https://www.googleapis.com/auth/gmail.settings.sharing, https://www.googleapis.com/auth/gmail.settings.basic,https://www.googleapis.com/auth/contacts.other.readonly 

G Suite as the Destination (full scopes):
https://mail.google.com/, https://www.google.com/m8/feeds, https://www.googleapis.com/auth/contacts.readonly, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/drive, https://sites.google.com/feeds/, https://www.googleapis.com/auth/gmail.settings.sharing, https://www.googleapis.com/auth/gmail.settings.basic,https://www.googleapis.com/auth/contacts.other.readonly 

9. Click Authorize.

You should now see your specific Unique ID and the scopes listed, similar to what is shown below:

40520a97-ba80-46f1-ae4b-710e52fe251f.png

 2c5866c2-efbb-499f-89a2-e55f36b8f5e7.png

Step 5: Set up the Google API endpoint during project creation

1. During the project creation process in MigrationWiz, click New for the Endpoint.
2. From the dropdown menu, select G Suite (Gmail API).
3. Click Select File.
4. Navigate to and select the JSON file that contains the Google Service Account key that was saved during the service account setup process.
5. Enter the super administrator email address.
6. Click Add.

Was this article helpful?
7 out of 17 found this helpful