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 delegation, you do not have to track down each end-user and authenticate into their mailbox individually.
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, delegation can be a great time saver if you are planning to acquire a large number of mailboxes.
In order to use delegation with Google Workspace, you need to do the following:
- 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.
- 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:
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, and Google Drive API to your project by searching for them and clicking their ENABLE button. FEC will use these APIs for the acquisition.
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.
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
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:
8. Click the Authorize button
At this point, your service account has domain-wide authority to access Gmail, Google Calendar, and Google Drive in a read-only manner.
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.
The authoritative documentation on domain-wide delegation from Google can be found here: https://developers.google.com/admin-sdk/directory/v1/guides/delegation