Using Delegation with Google Workspace

Forensic Email Collector allows you to acquire data from multiple end-users in a Google Workspace (formerly called G Suite) organization using a service account. Using domain-wide delegation of authority, you do not have to track down each end-user and authenticate into their mailbox individually.

In order to use domain-wide delegation with Google Workspace, you need to do the following:

1

Create a service account and its credentials in Google API Console. At the end of this step, you will have a JSON file containing the private key of your service account. You will also know the Unique ID of your service account.

2

Delegate domain-wide authority to the above service account in the Google Admin console of the target organization.

Here is how you can complete the two steps above:

1

 Create A Service Account and Its Credentials in Google API Console

You should start by opening a new browser window and logging into the Google Workspace account that manages the target organization. You will likely need the assistance of the IT representative of the target Google Workspace organization.

1. Visit Google API Console here: https://console.developers.google.com

2. Click on the Select a project dropdown on the top of the page and click on the NEW PROJECT button on the window that opens.

3. Give your project a name and create it. Our sample project is called "FEC Delegation".

4. Select the newly created project from the Select a project dropdown on the top of the page.

5. Click on the Library menu item on the left side of the page.

6. From the API Library, add the Gmail API, Google Calendar API, Google Drive API, and Admin SDK API to your project by searching for them and clicking their ENABLE button. FEC will use these APIs for the acquisition.

Note: The Admin SDK API is only needed to enumerate target mailboxes. It can be excluded if the list of target mailboxes will be supplied manually.

7. Visit the Service Accounts page here: https://console.developers.google.com/iam-admin/serviceaccounts

8. Click on the + CREATE SERVICE ACCOUNT button on the top menu and create a new service account. You can name it as you wish, such as "FEC Delegation Service Account".

Click CREATE and then DONE. No need to fill out the optional details.

9. Click the action menu of the newly created service account and choose the Create Key menu item.

10. Export the private key in JSON (default) format.

11. Click on the service account to reveal its details and write down its Unique ID as shown below. The Unique ID will be used in the Google Admin console in step 2 below.

2

 Delegate Domain-wide Authority to The Service Account

Now that we have created the service account and exported its private key, it's time to delegate domain-wide authority to the service account so that it can be used to access user data within the Google Workspace organization. You can achieve this as follows:

1. Visit the Google Workspace domain's Admin Console at http://admin.google.com/ and log in with a Super Admin account

2. Select the Security control

3. Choose API controls

4. Click the MANAGE DOMAIN WIDE DELEGATION button at the bottom of the page — as of this writing, this takes you to https://admin.google.com/ac/owl/domainwidedelegation

5. Click Add new

6. Populate the Client ID textbox with the Unique ID of the service account you created (see step 1.11 above).

7. Populate the OAuth Scopes textbox with the following string:

email,https://www.googleapis.com/auth/calendar.events.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly 

Note: The https://www.googleapis.com/auth/admin.directory.user.readonly scope is only needed to enumerate target mailboxes using FEC's Explore Mailboxes feature. The scope can be excluded if the list of target mailboxes will be supplied manually.

Similarly, you can customize the scopes for the type of acquisitions you plan to perform. For instance, if you are not going to collect Calendar or Drive data, the corresponding Calendar and Drive scopes can be excluded.

8. Click the Authorize button

Using The Service Account with FEC

Once you have your service account, you can use it with FEC as follows:

1. Start a Google Workspace acquisition as usual.

2. On the connection settings page, check the Use Domain-wide Delegation checkbox and load the .JSON file you exported in step 1.10 above by clicking the LOAD PRIVATE KEY button.

3. Click NEXT and proceed with the acquisition.

Removing Domain-wide Authority

Once the acquisition is complete, go back to the  MANAGE DOMAIN WIDE DELEGATION page (step 2.4 above) and click the Delete button to remove the service account's access to the Google Workspace organization.