Using Delegation with G Suite
Forensic Email Collector allows you to acquire data from multiple end users in a 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 G Suite 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 G Suite, 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 G Suite 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 G Suite account that manages the target organization. You will likely need the assistance of the IT representative of the target G Suite 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".
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 G Suite 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 G Suite organization. You can achieve this as follows:
1. Visit the G Suite domain's Admin Console at http://admin.google.com/
2. Select the Security control
3. Choose Advanced settings
4. Click the Manage API client access link
5. Populate the Client Name textbox with the Unique ID of the service account you created (see step 1.11 above).
6. Populate the One or More More API Scopes textbox with the following string:
7. Click the Authorize button
At this point, your service account has domain-wide authority to access Gmail and Google Calendar 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 G Suite 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 API client access page (step 2.4 above) and click the Remove link to remove the service account's access to the G Suite organization.
The authoritative documentation on domain-wide delegation from Google can be found here: https://developers.google.com/admin-sdk/directory/v1/guides/delegation