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. 

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 Which Items will Migrate with MigrationWiz? article will still migrate. 

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.4. For separate service accounts, follow all steps below. 

 

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 Drive API
    • Google Calendar API
    • Gmail API
    • Contacts API
    • Admin SDK
      Note: 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 on Security

Click on Advanced Settings

Click Manage API Client Access.

OR If your account shows the latest UI updates from Google, as shown below:New_Google_Admin_APP_Access_Control.JPG

Go to the G Suite admin page at google.com

Click on Security

Click Advanced Settings

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

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

 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

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

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

During the project creation process, 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?
2 out of 4 found this helpful