In addition to Gmail source support and Google Docs in-migration conversion, we have added the ability to configure and use a delegated service account to handle authentication for all of your G Suite users, be they Google Drive or Gmail.
This article sets out the once-off configuration steps required to create and use a delegated service account.
In order to create an authorized service account to use with Simply Migrate to access user’s data, your G Suite admin will need to perform some steps to create the service account and grant it the appropriate access. Once done that account can then be used to migrate all users with no further authentication requirements.
- Create a Service Account and download the JSON credential file.
- Delegate domain-wide authority to your service account.
- Create jobs using the downloaded credential file.
Step 1: Creating a Project and Service Account
Fortunately, Google has provided a setup wizard to simplify this procedure. The following steps cover using this wizard, if you prefer to do it manually refer to the referenced link above.
- Open the Google API setup tool:
- Select Yes then Agree and Continue to Create a project
Note: This wizard will create a project and enable the Gmail, Drive, Calendar and Contacts APIs in one simple step, if you are familiar with the G Suite admin console you can do this manually from APIs & Services menu.
- Once the project is created click Go to credentials:
- The Setup Wizard will continue and try to suggest the appropriate credentials, however, we know what we need so from step 1 click the text link service account (highlighted in yellow):
- Follow the wizard to create a service account:
- Fill in the details as follows:
Name: Provide a name for the account
Role: Select Project -> Service Account Actor
Furnish a new private key: Check, and select JSON for Key type
Enable G Suite Domain-wide Delegation: Check, product name: Simply Migrate
- Click Create
Note: a .JSON file will be downloaded to your computer containing the private key and service account details. This file must be kept securely!
(Example service account json file – details changed for obvious reasons)
- From the JSON file take note of the following details which will be needed in the next section: Client ID and Client Email.
- Finally with your service account created you can return to the APIs & services – Dashboard, to confirm, monitor and adjust any API settings.
Note: Using this wizard you can see that multiple APIs have been enabled, if however you only require Drive access you can disable any other APIs from the Dashboard.
Step 2: Delegate authority to your service account
The next step is to grant the service account access to the G Suite domain’s user data, this also needs to be performed by an administrator of the G Suite.
- Open the G Suite domain’s Admin Console: http://admin.google.com/
- Select Security from the list of controls. If you don’t see Security listed, select More controls from the gray bar at the bottom of the page, then select Security from the list of controls.
- Select Advanced settings from the list of options.
- Select Manage API client access in the Authentication section.
- In the Client name field enter the service account’s Client ID.
- In the One or More API Scopes field enter the list of scopes that your application should be granted access to.
For example to access Gmail, Drive, Calendar and Contacts as configured in the previous section enter the following comma separated list: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.metadata, https://www.googleapis.com/auth/gmail.labels, https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/calendar,
- Click Authorize to confirm the access rights.
Once the API client is authorized you are ready to start migrating data.
For more details on the above configured Scopes, they provide access to the following resources that are required depending on the Source / Target you are migrating. If you only require for example Google Drive data access, then the Gmail related scopes can be omitted and vice versa.
Scopes required for Gmail (including Google Calendar) support
- https://www.googleapis.com/auth/drive (NOTE: this is required for Calendar support as attachments are stored in drive)
Scopes required for Google Drive support
Step 3: Configuring Simply Migrate to use the service account
In the final step of this process, we need to configure the above settings for use in Simply Migrate, this is done as follows:
- On each migration machine, the OAuthApplication for Google must be created using the Scopes configured above.
- New jobs are then created using the .json file stored locally on the migration machine for authentication.
Configure the SimplyMigrate Google OAuth Application settings
Open the Simply Migrate Management Shell and enter the following command, including all of the scopes configured above.
PS> New-SMOAuthConfig -Type Google -ApplicationId "na" -ClientSecret "na" -ExtraData "https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/drive.metadata,https://www.googleapis.com/auth/gmail.labels,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/contacts"
The Client ID and Secrets are not provided in the command line, they will be contained in the JSON file allowing multiple service accounts to be used (e.g. you’ll need a different one for the source and target if migrating between G Suite domains).
The result should look like this:
Type : Google ApplicationId : na ClientSecret : na CallbackUrl : ExtraData : https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/drive.metadata,https://www.googleapis.com/auth/gmail.labels,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/contacts
Create a job using the service account JSON
Finally, you can now create your jobs using the JSON credential file created previously. In the following example, I’ll create a simple report target Gmail job to illustrate how to input the JSON file using the SourceAuthCode (or TargetAuthCode) job option in the place of any credentials.
PS> New-SMJob -Source GMail -SourceInput "firstname.lastname@example.org" -SourceAuthCode "C:\Temp\My Project-66d7047fc054.json" -Target ReportOnly
Once created, the job can be run as normal.