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. 
    • This is mandatory. The Powershell script will not work if Google Cloud SDK is not installed. 
  2. Ensure that the Google Cloud SDK is initialized by running the “gcloud init” command, and follow the instructions.
  3. Once Google Cloud SDK has finished installing, download the GCP_Configuration.ps1 file to your desktop,
    • You can also copy the script into a Notepad++, saving it as GCP_Storage_Configuration and applying the Windows Powershell file type to it.
  4. Click on your Desktop Search icon (next to the Start Icon) and search for Windows Powershell, right click on it to display options and select Run as Administrator
  5. On the GCP_Configuration.ps1 file, select Shift and right click. Select Copy as Path.
    • This will copy the entire file path.
  6. In the Windows Powershell window, enter CD and a space, paste the path into the Powershell script, then click the up button on your keyboard until you see the first half of the file path only (folder path) and select enter. It will look similar to: CD C:\Users\(your name)\Desktop
    • If the (your name) value has a space in it anywhere, you will need to enclose the file path in quotation marks (") as Windows cannot parse the spaces. It should now look like: CD "C:\Users\(your name)\Desktop"
  1. On the next line, type in .\GCP_Configuration.ps1 and press enter.
    • If you see a security error that the Powershell Script is unsigned, run “Set-ExecutionPolicy Unrestricted”.
  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
  1. On the KeyType line, enter one of the following to specify the key type:
    • P12
    • JSON

PowershellArguments.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 - 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.
  8. On the Security > API Controls > Domain-wide Delegation screen, select Add new to display the Add a new client ID pop-up box.
  9. 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 3 - 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 AND CONTINUE’.

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. Go back to Credentials and select the new Service account.
  3. Select the KEYS tab at the top of the screen, and click the ‘ADD KEY’ dropdown.
  4. Click ‘Create new key’.

Create_new_kkey.png

  1. Select ‘P12’ or JSON (depending on which format you want to use), and then click ‘CREATE’ - This will download the required 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.  In the list of Service accounts , open the account you have just created. Click the copy icon to take a note of the Unique ID. This Client ID 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 30-34 to enable each of the required APIs:
    • Admin SDK
    • Google Drive API
    • Gmail API
    • Google Calendar API
    • People API
    • Tasks API
    • Forms 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 needs to  be enabled for all migrating users.

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/forms,
  • 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/forms,
  • 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/forms,
  • 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/forms,
  • 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.