Connect Code42 to Gmail

Overview

To help protect you from data loss, you can use Code42 to investigate attachments sent through your organization's Google Gmail user accounts.

When you add Gmail as a data connection, you must authorize Code42 as a registered client API using your administrator account in Google Workspace (formerly G Suite). Once connected, we monitor your organization's Gmail environment from that point forward to capture information about the attachments that a user has emailed.

This article explains how to add Gmail as a data connection.

Considerations

The following considerations apply to Gmail. See also the considerations applicable to all email services.

To allow Code42 access to Gmail, you must be a Google Workspace administrator with a Super Admin role. See Permissions required for the Gmail connector for more information.
You cannot edit the authenticating administrator information once you register the email service. If you need to change that information, you must deauthorize the Gmail connection and then add it again as a new connection.

Monitoring and alerting tools may report download activity
When ongoing file activity is detected, Code42 temporarily streams files from your cloud storage or email service to the Code42 cloud to calculate the file hash. (Code42 does not calculate hash value during the initial inventory process.)

This appears in your vendor logs as users downloading files. The requesting service's IP address may point to Microsoft Azure hosts. Consider adding these IP addresses to your allowlist to reduce false alerts in your vendor logs, keeping in mind that these addresses can change.

Code42 never stores file contents or writes them to disk during this process.

Before you begin

Before you authorize the Code42 connection to your Gmail environment, complete these steps:

Verify that you have one of the required Google plans.
Identify the users you want the connection to monitor.
Verify the permissions you need for the Gmail connector.

Authorize Code42's connection to Gmail

Step 1: Connect Code42 to Gmail

Sign in to the Code42 console.
Add the Gmail connection:
1. Select Administration > Integrations > Data Connections.
2. Click Add data connection.
  The Add data connection panel opens.
3. From Data connection, select Google Gmail under Email services.
  Note the Client ID and OAuth scopes details that appear on the bottom of the screen. You enter this information into the Google Admin console later in this procedure.
4. Enter a display name. This display name must be unique.
Authorize the Code42 app in Google:
1. Go to your Google Admin console and log in using your Google Workspace administrator username and password. This email address must be associated with a Google Workspace administrator that has the Super Admin role.
  
  Requires Super Admin role
  This email address must be associated with a Google Workspace administrator that has the Super Admin role.
2. Go to Security > Access and data control > API controls.
3. At the bottom of the page in the Domain wide delegation panel, click Manage domain wide delegation.
  You may need to scroll to see the Domain wide delegation panel. Do not confuse the Manage domain wide delegation link in this panel with the Manage third-party app access link in the App access control panel. When you click Manage domain wide delegation, the Domain-wide delegation page displays.
4. Click Add new.
  The Add a new client ID window displays.
5. Copy the Client ID from the Code42 console and paste it in the Client ID field.
6. Copy the OAuth scopes from the Code42 console and paste it in the OAuth scopes (comma-delimited) field.
7. Click Authorize.
  The Code42 email service is added to the API client table.

Step 2: Add users

Return to the Code42 console.
In Add data connection, select I've completed these steps under Complete these steps in Google Workspace and then click Continue.
The Add users panel appears.
Select one of the following options:
- All: Monitors emails for all users with Gmail accounts in your environment.
- Specific users: Monitors only the Gmail user accounts you designate.
  1. Click Upload .CSV file.
  2. Select the scoping CSV file that contains a list of only those Gmail users you want to monitor.
- Specific groups: Monitors only the users with Gmail accounts that are in the Google groups you designate.
  1. Click Upload .CSV file.
  2. Select the scoping CSV file that contains a list of only those Google groups you want to monitor. Gmail account users that are in those groups are monitored by Code42.

Step 3: Verify your Google Workspace administrator email

In Add data connection, click Continue.
The Verify panel appears.
Enter the Google Workspace username that you used earlier to log in to the Google Admin console.

Requires Super Admin role
This email address must be associated with a Google Workspace administrator that has the Super Admin role.
Click Authorize.
Gmail is added as an email data connection.

Next steps

Once you have added Gmail as a data connection, learn more about:

Gmail attachment metadata

Once you complete authorization, file and message information about email attachments becomes available in Forensic Search from that point forward. When a user emails an attachment, information about that attachment typically becomes available in Forensic Search within 30 minutes. This attachment information includes:

Filename
Hash, when available
Email address of the sender and recipients

Use the Google Admin console to open and view attachments for further investigation.

Troubleshooting

Issues in your Gmail environment can cause errors with the Code42 connection. When such issues occur, the Gmail connection in the Data Connections table is highlighted in red and an error message is displayed at the top of the screen. When this occurs, click the Gmail connection in the Data Connections table. The detail panel opens and lists the specific error so that you can resolve it.

Refer to these articles to troubleshoot specific errors that can appear for the Gmail connection in the Data Connections list:

External resources

Google: Apply policies to different users
Google: OAuth 2.0 Scopes for Google APIs