Using Domain-wide Delegation with Google Workspace

Forensic Email Collector (FEC) 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.

Note

Completing the below steps should take about 10 minutes if you have the necessary credentials. This may not be practical for collecting just one or two mailboxes from a Google Workspace organization. On the other hand, domain-wide delegation can be a great time saver if you are planning to collect data from a large number of users.

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

1. PART I - 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. PART II - Delegate domain-wide authority to the above service account in the Google Admin console of the target organization.

   IMPORTANT This part requires a Super Admin account. You will likely need the assistance of the IT representative of the target Google Workspace organization.

Here is how you can complete the two steps above:

PART I - Create A Service Account and Its Credentials in Google API Console

Tip

You can create the service account using an account from the target Google Workspace organization, or an external account such as a free Gmail account.

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”. No need to specify a Parent resource.

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”.

   

9. Click Create and continue Create and continue and then Done Done . No need to fill out the optional details.

10. Click the action menu of the newly-created service account and choose the Manage keys menu item.

    

11. Click Add key > Create new key > JSON > Create. This will cause a new JSON key to be created and downloaded. Save the key to your computer.

    

    Note

    Service account key creation may be disabled in some Google Workspace organizations. You can work around this in two ways:

    1. The above steps regarding the creation of a service account do not have to be performed on the target organization’s Google Workspace environment. You can create the service account in a different (even free) Google account and bring the service account from the outside for authorization.

    2. If you prefer to create the service account in the target organization, service account key creation can be enabled by setting the iam.disableServiceAccountKeyCreation Boolean constraint to ‘false’ as described here.

12. Click on the service account to reveal its details and write down its Unique ID as shown below. Alternatively, you can open the JSON file exported above and find the Unique ID value in the client_id field.

    The Unique ID will be used in the Google Admin console in Part II below.

    

PART II - 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. Navigate to Security > Access and data control > API controls

3. 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

4. Click Add new

5. Populate the Client ID textbox with the Unique ID of the service account you created in Part I.

6. 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

   Tip

   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.

7. Click the Authorize button

   

Note

If you recently authorized the above scopes, the authorization may take some time to take effect—especially in large organizations. If you receive an error during authentication, we recommend waiting for half an hour and trying again.

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 Part I above by clicking the LOAD PRIVATE KEY LOAD PRIVATE KEY button.

   

3. Click NEXT NEXT and proceed with the acquisition.

Removing Domain-wide Authority

Once the acquisition is complete, go back to the MANAGE DOMAIN WIDE DELEGATION page in Part II and click the Delete Delete button to remove the service account’s access to the Google Workspace organization.

Further Reading

The authoritative documentation on domain-wide delegation from Google can be found here: Delegate domain-wide authority to the service account