Connect Incydr to Gmail

Overview

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

When you add Gmail as a data connection, you must authorize Incydr 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 Incydr 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, Incydr temporarily streams files from your cloud storage or email service to the Incydr cloud to calculate the file hash. (Incydr 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. 

File contents are never stored or written to disk during this process.

Before you begin

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

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

Authorize Incydr's connection to Gmail

Step 1: Connect Incydr to Gmail

1. Sign in to the Incydr console.
2. 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.
      
3. Authorize the Incydr 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 Incydr console and paste it in the Client ID field.
   6. Copy the OAuth scopes from the Incydr console and paste it in the OAuth scopes (comma-delimited) field.
   7. Click Authorize.
      The Incydr email service is added to the API client table.

Step 2: Add users

1. Return to the Incydr console.
2. 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.
   
3. 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 Incydr.

Step 3: Verify your Google Workspace administrator email

1. In Add data connection, click Continue.
   The Verify panel appears.
   
2. 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.
3. Click Authorize.
   Gmail is added as an email data connection.

Next steps

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

• Common use cases for investigating security incidents with Forensic Search
• How to use Forensic Search

Attachments

When a monitored user emails an attachment, Incydr captures the attached file contents, plus extensive metadata about the file (including the email addresses of the sender and recipients). For a detailed list of all metadata, see the File event metadata reference.

You can also use the Google Admin console to open and view attachments for further investigation.

Troubleshooting

Issues in your Gmail environment can cause errors with the Incydr 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:

• Resolve "There is an issue with the connection" error
• Resolve email domain already exists error
• Resolve slowed performance of Google Drive and Gmail data collection
• Reconfigure scoping for user and group monitoring

External resources

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

Related topics

• Introduction to adding data connections 
• Data Connections reference 
• Deauthorize and resume monitoring a data connection
• Permissions required for the Gmail connector