Who is this article for?
Incydr Professional, Enterprise, Gov F2, and Horizon, yes.
Incydr Basic, Advanced, and Gov F1, yes.
CrashPlan Cloud, no.
Retired product plans, no.
CrashPlan for Small Business, no.
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.
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 your Google Workspace administrator needs below 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.
Code42 temporarily streams files from your cloud storage or email service to the Code42 cloud to calculate the file hash. This may be reported as users downloading files. The requesting service's IP address may point to Microsoft Azure hosts.
Code42 never stores file contents or writes them to disk during this process.
Authorize Code42's connection to Gmail
Step 1: Connect Code42 and Gmail
- Sign in to the Code42 console.
- Add the Gmail connection:
- Select Administration > Integrations > Data Connections.
- Click Add Data Connection.
The Add Data Connection dialog appears.
- From Data Connection, select Google Gmail under Email Services.
Note the Client ID and Scopes details that appear on the bottom of the screen. You will need this information later in this procedure.
- Enter a display name. This display name must be unique.
- Authorize the Code42 app in Google:
- Go to your Google Admin console and log in using your Google Workspace administrator email and password. This email address must be associated with a Google Workspace administrator that has the Super Admin role.
- Go to Security > Access and data control > API controls.
- In the Domain wide delegation panel, click Manage domain wide delegation.
The Domain-wide delegation page displays.
- Click Add new.
The Add a new client ID window displays.
- Copy the Client ID from the Code42 console and paste it in the Client ID field.
- Copy the Scopes from the Code42 console and paste it in the OAuth scopes (comma-delimited) field.
- Click Authorize.
The Code42 email service is added to the API client table.
Step 2: Add users
- Return to the Code42 console.
- In the Add Data Connection dialog, click Continue.
The Add Users panel appears.
- Select one of the following options:
Monitors emails for all users with Gmail accounts in your environment.
- Specific Users
Monitors only the Gmail user accounts you designate.
- Specific Groups
Monitors only the users with Gmail accounts that are in the Google groups you designate.
Step 3: Verify your Google Workspace administrator email
- In the Add Data Connection dialog, click Continue.
The Verify panel appears.
- Enter the Google Workspace email address that you used earlier to log in to the Google Admin console.
- Click Authorize.
Gmail is added as an email data connection.
Once you have added Gmail as a data connection, learn more about:
Upload a .csv file
In Step 2, if you select Specific Users or Specific Groups and click Upload .CSV file, you must upload a .csv file that lists either the specific Gmail users or groups you want to monitor.
General considerations for uploading a .csv file:
- The .csv file is limited to 1,000 entries.
- Uploading a new .csv replaces the existing list of users or groups being monitored.
Upload a .csv file listing Gmail account users
To create a list of Gmail users, see Google Workspace Admin Help. Create a .csv file from this list that contains only the users with Gmail accounts that you want to monitor. Code42 reads usernames from column headers labeled Email Address [Required], Email Address, or Emails in the .csv file. If these columns contain any entries that aren't email addresses, the upload produces an error.
Upload a .csv file listing Google groups
To create a Google group, see the Google Workspace Learning Center. After your Google groups are set up, create a .csv file that contains only the groups you want to monitor. In this file, use column headers to identify either the name or the email addresses of those groups.
- Code42 reads the names of groups from the column header labeled Group Name or Groups. Specify the names of the groups exactly as they appear in the Google Admin console.
- Code42 reads a list of email addresses associated with a group from the column header labeled Email or Email Address. In the .csv file, specify the email address associated with each group.
If the .csv file does not contain at least one of these column headers, the upload produces an error.
Code42 scans those groups to identify their users with Gmail accounts and then monitors only those email accounts. Code42 looks for users associated with Google groups as follows:
- When a group's name or email address is provided, Code42 attempts to look up users associated with that group name or group email address.
- If the group includes another group name or email address (a "nested" group), Code42 looks up users associated with that nested group as well.
- If the group name or email address cannot be found, Code42 proceeds to the next entry in the .csv file. Code42 looks for that group or email address again every 24 hours.
As users are added and removed from the monitored groups, Code42 detects these changes within 24 hours and adjusts monitoring of user email accounts accordingly.
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:
- Hash, when available
- Email address of the sender and recipients
Use the Google Admin console to open and view attachments for further investigation.
Permissions your Google Workspace administrator needs
Code42 uses API client access to connect to and monitor file activity in your Google environment. In order to grant third-party services or applications domain-wide delegation or manage API client access in the Google Admin console, you must be a Google Workspace administrator that has the Super Admin role. Code42 cannot collect data from your Google environment when the connection is authorized by a Google Workspace administrator without this role.
Permissions the Code42 service account needs
When a user emails an attachment, we collect information about the attached file and the sender and recipients for the email. To see this file activity, Code42 requires access to your Gmail environment.
In the configuration steps above, Code42 provides the client ID and scopes for you to enter in your Google Admin console. Code42 uses the following scopes:
https://www.googleapis.com/auth/admin.directory.customer.readonly https://www.googleapis.com/auth/admin.directory.group.member.readonly https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/gmail.readonly
This set of permissions means Code42 has read-only access to metadata for emails, attached files, and users within that email service. In other words, Code42 cannot make changes to the emails, data, or users in your email environment. In addition, Code42 does not monitor the contents of those files, and does not back up files in the email service.
Google uses API quotas to limit API requests from third-party integrations such as Code42. Throttling these API requests allows Google to better control their resources, but may slow down Code42 file metadata collection, especially after first enabling Code42 access to Gmail.
For faster performance, perform the following in the Google Admin console:
Email domain already exists
You can authorize a Google Workspace account for your Code42 environment only once as a cloud storage data connection (to monitor file movement in Google Drive locations) and once as an email service (to monitor file attachments sent outside your company).
When you attempt to register the same Google Workspace account for multiple cloud storage or email services, the following message appears during authorization: “A data connection with that email domain already exists.”
To resolve the issue:
- Verify that the account has been added only once as a cloud storage data connection or only once as an email service.
- Consider creating another Google Workspace account for the data you want to monitor using a new email address under a different domain. You can add multiple unique Google Workspace accounts as Code42 data connections as long as the accounts are not associated in any way (that is, the accounts use different domains or have administrators with unique email addresses).
Data connection is already registered or the email address is not valid
You can only authorize a unique Google Workspace account for one Code42 environment at a time. If you attempt to register the same Google Workspace account in multiple Code42 environments, the following message appears during authorization: “This data connection has already been registered or the email address is not valid for this domain.” For example, you register a Google Drive cloud storage data connection in one Code42 environment, then register a Gmail email service in another Code42 environment. Both belong to the same Google Workspace account.
To resolve the issue:
- Verify the Code42 environment with which the Google Workspace account has been registered. If you need to register the Google Workspace account with a different Code42 environment, first deauthorize it from the Code42 environment it is currently registered with, then wait for 90 days for the data for that data connection to be purged automatically. To purge the data for that data connection more quickly, contact your Customer Success Manager (CSM).
- Consider creating another Google Workspace account for the data you want to monitor in another Code42 environment using a new email address under a different domain.
There is an issue with the connection
Other issues—such as a change in your administrator credentials—can cause the Code42 connection to enter an Error status. When such unknown errors occur, the following error message appears in the Code42 details for that data connection:
There was an issue with the connection to <data connection>. Deauthorize <data connection> and set up a new data connection to resolve the issue, or contact Code42 for support.
To resolve this error:
- Deauthorize the data connection.
- Remove Code42's access in the email service environment:
- Set up a new Code42 data connection using your Google or Microsoft 365 administrator credentials.
If these steps don't resolve your error, contact our Customer Champions for support.
Reconfigure scoping for user and group monitoring
If needed, you can reconfigure the connection's scoping to add new users or groups or switch from monitoring specific users to monitoring specific groups.
- Deauthorize the connection.
Code42 removes the connection's configuration and authorization information immediately after you deauthorize it.
- Set up a new connection to the environment by clicking Add Data Connection on the Data Connections screen.
- In the Add Users step of the authorization process, select the appropriate monitoring option, and then upload a new .csv file containing the updated users or groups you want to monitor.