Authorize GWMME for your account

Before you use Google Workspace Migration for Microsoft Exchange (GWMME), authorize it for your account.

Step 1: Create a service account

Expand all  |  Collapse all & go to top

How you create the service account depends on whether you want to run an automated script (recommended) or manually create the account.

Option 1: Use an automated script to create the account

This GitHub script is not supported by Google Workspace support. If you have issues using the script, follow the steps to manually create the account instead. Learn more about using the script.

1. Sign in as a super administrator and, in a browser window, open Cloud Shell.
2. In the shell, to start the automated script, enter the following command:

   python3 <(curl -s -S -L https://git.io/gwmme-create-service-account)

3. Complete the steps in the Cloud Shell window.
4. Click Download to download the JSON file that contains the service account's client ID to your computer.
5. Set up your migration. For details, go to Migrate data with GWMME.

Learn more about using the script.

Option 2: Manually create a service account

Step 1: Create a project

1. Go to Google Cloud and sign in as a super administrator. If it's your first time signing in to the console, agree to the Terms of Service.
2. Click IAM & AdminManage Resources. You might have to click Menu first.
3. At the top, click Create Project and enter a project name.
4. (Optional) To add the project to a folder, for Location, click Browse, navigate to the folder, and click Select.
5. Click Create.
6. By default, only the creator of the project has rights to manage the project. To ensure the project can be maintained if the creator leaves the organization, you should assign at least one other person the role of Project Owner. For details, go to Manage access to projects, folders, and organizations.

Step 2: Turn on the APIs for the service account

1. Check the box next to your new project.
2. Click APIs & ServicesLibrary. You might have to click Menu first.
3. For each API you require (below), click the API name and then Enable:
   • Admin SDK
   • Google Calendar API
   • Contacts API
   • Gmail API
   • Groups Migration API

   Tip: If you can't find the API, specify the API name in the search box.

Step 3: Set up the OAuth consent screen

Tip: When adding the email addresses below, use shared administrator email accounts.

1. Click APIs & ServicesOAuth consent screen. You might have to click Menu first.
2. For User Type, select Internal.
3. Click Create.
4. For App name, add the name of your application. 
5. Select a User support email for users to contact with questions.
6. For Developer contact information, enter email addresses so Google can contact you about changes to your project.
7. Click Save and ContinueSave and ContinueBack to Dashboard.

Step 4: Create the service account

1. Click APIs & ServicesCredentials. You might have to click Menu first.
2. Click Create CredentialsService account.
3. For Service account name, enter a name for the service account and optionally add a description. 
4. Click Create and ContinueDone.
5. Make a note of the Unique ID value for the service account. You'll need it later. This value is also the service account’s client ID.

   Tip: You can also find the value on the Details tab of the service account or in the JSON file.

6. Click DoneSave.
7. At the top, click KeysAdd KeyCreate new key.
8. Make sure the key type is set to JSON and click Create.

   You'll get a message that the service account's private key JSON file was downloaded to your computer.

9. Make a note of the file name and where your browser saves it. You'll need it later.
10. Click Close.

Step 2: Authorize your client ID in the Admin console

Expand all  |  Collapse all & go to top

If you used an automated script to create your service account, you can skip this step.

How you authorize depends on the type of account you're migrating from.

Option 1: Not migrating from a Google Workspace account

Perform these steps on the target account.

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  SecurityAccess and data controlAPI controlsManage Domain Wide Delegation.
   You must be signed in as a super administrator for this task.
3. Click Add new and enter your service account client ID.

   You can find the ID (also known as the Unique ID) in the JSON file that you downloaded when you created the service account or in Google Cloud (click IAM & AdminService accountsthe name of your service account).

4. For OAuth scopes, copy and paste the following comma-delimited list of scopes:

   https://www.googleapis.com/auth/contacts,
   https://www.googleapis.com/auth/admin.directory.group.readonly,
   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/gmail.insert,
   https://www.googleapis.com/auth/gmail.labels

5. Click Authorize.
6. Point to the new client ID, click View details, and make sure that every scope is listed.

   If a scope is not listed, click Edit, enter the missing scope, and click Authorize. You can't edit the client ID.

Changes can take up to 24 hours but typically happen more quickly. Learn more

Option 2: Migrating from a Google Workspace account

The steps you need to take vary depending on your setup. If you have:

• Google Workspace source and target domains that are different—Authorize GWMME on both your source domain and target domain by following steps 1 and 2 (below, on this page).
• Google Workspace source and target domains that are the same—Authorize GWMME only on your target domain by following step 2 (below, on this page).
• Added passwords in your control CSV file—Authorize GWMME only on your target domain by following step 2 (below, on this page). Then, give your source account access for less-secure apps. For details, go to Step 2: Allow less secure apps to access accounts.

Step 1: Authorize GWMME on your source domain

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  SecurityAccess and data controlAPI controlsManage Domain Wide Delegation.
   You must be signed in as a super administrator for this task.
3. Click Add new and enter your service account client ID.

   You can find the ID (also known as the Unique ID) in the JSON file that you downloaded when you created the service account or in Google Cloud (click IAM & AdminService accountsthe name of your service account).

4. For OAuth scopes, copy and paste the following scope:

   https://www.googleapis.com/auth/gmail.imap_admin

5. Click Authorize.
6. Next, complete step 2 below.

Step 2: Authorize GWMME on your target domain

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  SecurityAccess and data controlAPI controlsManage Domain Wide Delegation.
   You must be signed in as a super administrator for this task.
3. Click Add new and enter your service account client ID.

   You can find the ID (also known as the Unique ID) in the JSON file that you downloaded when you created the service account or in Google Cloud (click IAM & AdminService accountsthe name of your service account).

4. For OAuth scopes, copy and paste the following comma-delimited list of scopes:

   https://www.googleapis.com/auth/contacts,
   https://www.googleapis.com/auth/admin.directory.group.readonly,
   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/gmail.insert,
   https://www.googleapis.com/auth/gmail.labels

5. If your Google Workspace source and target domains are the same, add the following scope:

   https://www.googleapis.com/auth/gmail.imap_admin

6. Click Authorize.
7. Point to the new client ID, click View details, and make sure that every scope is listed.

   If a scope is not listed, click Edit, enter the missing scope, and click Authorize. You can't edit the client ID.

Changes can take up to 24 hours but typically happen more quickly. Learn more

Step 3: Set up your migration

For details, go to Migrate data with GWMME.

_{Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.}