Skip to main content

Setting up the Service Account and enable the APIs within Google Workspace for CloudM Migrate

  • Updated

This setup is for both a source Google Workspace account and a Destination Google Workspace account. 

 

Migrating from Google Vault

If you are migrating from Google Vault, billing must be enabled for the Google project being used for the migration. This is necessary to avoid very low Google Vault export quota limits. 

 

Automated Process (Recommended method)

This method uses a Powershell script to automate the majority of the process, making sure that the correct Scopes and APIs are applied, with only a few simple manual steps required.

It is easier and quicker than the full manual process, and less prone to error.

Before you start, you will need:

  • An account in GCP with permissions to create a project (resourcemanager.projects.create role) or owner on existing project,
  • The ability to run Powershell Script as Administrator,
  • A browser window open and authenticated into the GCP tenant. This must be the last browser tab you have used.

 

To create a service account and obtain the private key for the account:

  1. Install Google Cloud SDK using the instructions provided by Google here,
  2. Once Google Cloud SDK has finished installing, download the GCP_Configuration.ps1 file to your desktop,
  3. Click on your Desktop Search icon (next to the Start Icon) and search for Windows Powershell
  4. Select Run as Administrator
  5. On the GCP_Configuration.ps1 file, select Shift and right click. Select Copy as Path.
  6. In the Windows Powershell window, enter CD and a space, then press the up arrow key on your keyboard until you see the first half of the file path and select enter. It will look similar to: 
      • CD C:\Users\(your name)\Desktop
  1. On the next line, press the up arrow key on your keyboard until you see & ‘.\GCP_Configuration.ps1 and press enter.
    • If you see a security error that the Powershell Script is unsigned, run “Set-ExecutionPolicy Restricted”.
  2. On the Project ID line, enter a unique Project ID name.
  3. On the Service Account ID, enter a Service Account name. It can be the same as the Project ID name.
  4. On the Scope line, enter one of the following to specify the scopes to be assigned:
    • All (for Full scopes) - Recommended for Google to Google
    • Standard
    • SourceLimited
    • DestinationLimited
    • Vault
    • Storage

Powershell_service_account.png

  1. The Powershell script will run, setting up the service account and enabling the scopes. This may take a few minutes to complete.
  2. Once the Powershell has finished, you will need to manually complete a few easy steps (Steps 1 to 4 as detailed below) to complete the OAuth and Domain Wide Delegation configuration, with instructions and URLs displayed.
  3. For Step 1 - Configure OAuth Consent, copy the displayed URL and paste into a browser. Sign in to GCP with a full admin account. 
  4. On the OAuth consent screen, set the User Type to Internal and select Create.
  5. On the next screen, set the App name to CloudM Migrate, and add a User Support email and a Developer Contact email address.
  6. Select Save and Continue.
  7. For Step 2 - Service Account Domain Wide Delegation, copy the displayed URL in the Powershell window and paste into a browser.
  8. On the Service Accounts screen, click on the down arrow before SHOW DOMAIN-WIDE DELEGATION, check the Enable Google Workspace Domain-wide Delegation checkbox and select Save.
  9. For Step 3 - Configure Google Workspace Domain Wide Delegation using the following ClientId and Scopes, copy the displayed URL in the Powershell window and paste into a browser.
  10. On the Security > API Controls > Domain-wide Delegation screen, select Add new to display the Add a new client ID pop-up box.
  11. Copy and paste the Client ID and OAuth Scopes from the Powershell window into the specified fields and select AUTHORIZE.

Add_a_new_ClientID.png

  1. Now, from the Step 4 - Service Account details for use in CloudM Migrate section of the Powershell script, copy the Service account email address that you need later when configuring the platform in CloudM Migrate.
  2. The P12 file that you will also need when configuring the platform in CloudM Migrate can be found in C:\CloudM\GCPConfig, along with a gcp_config log for the process.

 

Manual Process

To create a service account and obtain the private key for the account

  1. Open a web browser and sign in as an administrator for the required platform.
  2. Go to cloud.google.com/console
  3. Click the project selection menu in the blue navigation bar (1).
  4. Next to ‘Select from’ ensure the correct Organization you are creating the service account for is selected (2).
  5. Click ‘NEW PROJECT’ (3).

Manual_Service_Account.PNG

  1. Enter a project name.
  2. Ensure the correct organization is selected.
  3. The location can be left as the default or changed at your discretion.
  4. Click CREATE.

New_Project.PNG

  1. Click on the “Menu” icon next to "Google Cloud Platform" in the top left of the page.
  2. Click 'APIs & Services', then 'Credentials'.

API_Services_Credentials.PNG

  1.  Click CREATE CREDENTIALS, then select 'Service account'.

Create_Creds.PNG

  1.  Enter a service account name.
  2. Click ‘CREATE’.

Service_Account.PNG

  1. In the ‘Select a role’ menu, click ‘Project’, then select ‘Owner’. This step is optional.
  2. Click CONTINUE.
  3. The Grant users access to this service account section that is displayed next is optional, and can be left blank. Click DONE to continue.
  4. Click on OAuth consent screen.

Oauth_consent_screen.PNG

  1. Under User Type, select ‘Make Internal’.
  2. Select EDIT APP. Enter an application name and enter a Support email and a Developer Contact Email.

Edit_apps.png

  1. Click SAVE AND CONTINUE.
  2. Navigate back to the ‘Credentials’ page.
  3. Click the edit button (pencil icon) on the service account that was created (1).

Service_Account_2.png

  1. Expand the ‘SHOW/HIDE DOMAIN WIDE DELEGATION’ dropdown (1) and check the ‘Enable G Suite Domain-wide Delegation’ checkbox to enable it (2). Select Save.

Domain-Wide_Delegation.png

  1. Select the KEYS tab at the top of the screen, and click the ‘ADD KEY’ dropdown.
  2. Click ‘Create new key’.

Create_new_kkey.png

  1. Select ‘P12’, then click ‘CREATE’ - This will download the private P12 key file to be imported into CloudM Migrate.

Private_Key.png

  1. Close the ‘Private key password’ screen (1) as this is not needed.

Private_Key_2.PNG

  1. Navigate back to the APIs & Services > Credentials screen.
  2. Notice the Oauth 2.0 Client ID has now appeared. Click the copy icon to take a note of the client ID. This will need to be added to Google Workspace later.
  3. Take a note of the Service Account Email. This will need to be added to CloudM Migrate later.
  4. Navigate to the APIs & Services > Dashboard page.
  5. Click ‘ENABLE APIS AND SERVICES’.

Enable_APIs.png

  1. In the ‘Search for APIs & Services’ search box, enter ‘Admin SDK’.
  2. Click on Admin SDK API

Admin_SDK.PNG

  1. Click ENABLE.
  2. The Admin SDK overview page is now shown. Click ‘APIs & Services’ to navigate back to the main APIs & Services page.
  3.  Repeat steps 33-37 to enable each of the required APIs:
    • Admin SDK
    • Google Drive API
    • Gmail API
    • Google Calendar API
    • People API
    • Tasks API
    • Groups Migration API
    • G Suite Vault API (if you are migrating from Google Vault).
    • Cloud Storage (if you are Migrating from Google Storage).
  1. If migrating Google Drive, open the Google Workspace Admin console and navigate to Apps > Google Workspace > Drive and Docs > Features and Applications and enable 'Allow users to access Google Drive with the Drive SDK API':

Drive_SDK.png

  1. Open the Google Workspace admin console and navigate to ‘Security > API Controls > Domain-wide Delegation’ and click on Manage Domain-wide Delegation. Here is a direct link: https://admin.google.com/ac/owl/domainwidedelegation?hl=en
  2. Click ‘Add new’ then enter the Client ID, the relevant OAuth scopes listed next, and then click ‘AUTHORIZE’. 

Add_a_new_ClientID.png

 

If 'Use Limited Scopes' is going to be set as 'False' (default) in the Migration Settings section for the platform in CloudM Migrate, use the full scopes listed here:

  • https://www.googleapis.com/auth/admin.directory.resource.calendar,
  • https://www.googleapis.com/auth/gmail.settings.sharing,
  • https://mail.google.com/,
  • https://sites.google.com/feeds/,
  • https://www.googleapis.com/auth/admin.directory.group,
  • https://www.googleapis.com/auth/admin.directory.user,
  • https://www.googleapis.com/auth/apps.groups.migration,
  • https://www.googleapis.com/auth/calendar,
  • https://www.googleapis.com/auth/drive,
  • https://www.googleapis.com/auth/drive.appdata,
  • https://www.googleapis.com/auth/email.migration,
  • https://www.googleapis.com/auth/tasks,
  • https://www.googleapis.com/auth/gmail.settings.basic,
  • https://www.googleapis.com/auth/contacts,
  • https://www.googleapis.com/auth/contacts.other.readonly,
  • https://www.googleapis.com/auth/contacts.readonly,
  • https://www.googleapis.com/auth/directory.readonly,
  • https://www.googleapis.com/auth/user.addresses.read,
  • https://www.googleapis.com/auth/user.birthday.read,
  • https://www.googleapis.com/auth/user.emails.read,
  • https://www.googleapis.com/auth/user.gender.read,
  • https://www.googleapis.com/auth/user.organization.read,
  • https://www.googleapis.com/auth/user.phonenumbers.read,
  • https://www.googleapis.com/auth/userinfo.email,
  • https://www.googleapis.com/auth/userinfo.profile

 

If 'Source Platform Migration Settings > Google Workspace > Email Options > Use Limited Scopes' is set to 'True', use the following scopes:

  • https://www.googleapis.com/auth/gmail.labels,
  • https://www.googleapis.com/auth/gmail.readonly,
  • https://www.googleapis.com/auth/admin.directory.resource.calendar,
  • https://www.googleapis.com/auth/gmail.settings.sharing,
  • https://sites.google.com/feeds/,
  • https://www.googleapis.com/auth/admin.directory.group,
  • https://www.googleapis.com/auth/admin.directory.user,
  • https://www.googleapis.com/auth/apps.groups.migration,
  • https://www.googleapis.com/auth/calendar,
  • https://www.googleapis.com/auth/drive,
  • https://www.googleapis.com/auth/drive.appdata,
  • https://www.googleapis.com/auth/email.migration,
  • https://www.googleapis.com/auth/tasks,
  • https://www.googleapis.com/auth/gmail.settings.basic,
  • https://www.googleapis.com/auth/contacts,
  • https://www.googleapis.com/auth/contacts.other.readonly,
  • https://www.googleapis.com/auth/contacts.readonly,
  • https://www.googleapis.com/auth/directory.readonly,
  • https://www.googleapis.com/auth/user.addresses.read,
  • https://www.googleapis.com/auth/user.birthday.read,
  • https://www.googleapis.com/auth/user.emails.read,
  • https://www.googleapis.com/auth/user.gender.read,
  • https://www.googleapis.com/auth/user.organization.read,
  • https://www.googleapis.com/auth/user.phonenumbers.read,
  • https://www.googleapis.com/auth/userinfo.email,
  • https://www.googleapis.com/auth/userinfo.profile

 

If 'Destination Platform Migration Settings > Google Workspace > Email Options > Use Limited Scopes' is set to 'True', use the following scopes:

  • https://www.googleapis.com/auth/gmail.labels,
  • https://www.googleapis.com/auth/gmail.insert,
  • https://www.googleapis.com/auth/admin.directory.resource.calendar,
  • https://www.googleapis.com/auth/gmail.settings.sharing,
  • https://sites.google.com/feeds/,
  • https://www.googleapis.com/auth/admin.directory.group,
  • https://www.googleapis.com/auth/admin.directory.user,
  • https://www.googleapis.com/auth/apps.groups.migration,
  • https://www.googleapis.com/auth/calendar,
  • https://www.googleapis.com/auth/drive,
  • https://www.googleapis.com/auth/drive.appdata,
  • https://www.googleapis.com/auth/email.migration,
  • https://www.googleapis.com/auth/tasks,
  • https://www.googleapis.com/auth/gmail.settings.basic,
  • https://www.googleapis.com/auth/contacts,
  • https://www.googleapis.com/auth/contacts.other.readonly,
  • https://www.googleapis.com/auth/contacts.readonly,
  • https://www.googleapis.com/auth/directory.readonly,
  • https://www.googleapis.com/auth/user.addresses.read,
  • https://www.googleapis.com/auth/user.birthday.read,
  • https://www.googleapis.com/auth/user.emails.read,
  • https://www.googleapis.com/auth/user.gender.read,
  • https://www.googleapis.com/auth/user.organization.read,
  • https://www.googleapis.com/auth/user.phonenumbers.read,
  • https://www.googleapis.com/auth/userinfo.email,
  • https://www.googleapis.com/auth/userinfo.profile

 

Migrating from Google Vault?

If you are migrating from Google Vault, use these API Scopes:

  • https://www.googleapis.com/auth/admin.directory.resource.calendar,
  • https://www.googleapis.com/auth/gmail.settings.sharing,
  • https://mail.google.com/,
  • https://sites.google.com/feeds/,
  • https://www.googleapis.com/auth/admin.directory.group,
  • https://www.googleapis.com/auth/admin.directory.user,
  • https://www.googleapis.com/auth/apps.groups.migration,
  • https://www.googleapis.com/auth/calendar,
  • https://www.googleapis.com/auth/drive,
  • https://www.googleapis.com/auth/drive.appdata,
  • https://www.googleapis.com/auth/email.migration,
  • https://www.googleapis.com/auth/tasks,
  • https://www.googleapis.com/auth/gmail.settings.basic,
  • https://www.googleapis.com/auth/ediscovery,
  • https://www.googleapis.com/auth/ediscovery.readonly,
  • https://www.googleapis.com/auth/devstorage.read_write,
  • https://www.googleapis.com/auth/contacts,
  • https://www.googleapis.com/auth/contacts.other.readonly,
  • https://www.googleapis.com/auth/contacts.readonly,
  • https://www.googleapis.com/auth/directory.readonly,
  • https://www.googleapis.com/auth/user.addresses.read,
  • https://www.googleapis.com/auth/user.birthday.read,
  • https://www.googleapis.com/auth/user.emails.read,
  • https://www.googleapis.com/auth/user.gender.read,
  • https://www.googleapis.com/auth/user.organization.read,
  • https://www.googleapis.com/auth/user.phonenumbers.read,
  • https://www.googleapis.com/auth/userinfo.email,
  • https://www.googleapis.com/auth/userinfo.profile

 

Service Account and Scopes Propagation Time

Similarly with the Service account and APIs, adding the Client and Scopes in the Google Workspace console may be subject to a propagation time of up to two hours.

Selecting Check Connections for your Google Workspace platform in CloudM Migrate may not be successful immediately.

Comments

0 comments

Please sign in to leave a comment.