Google Workspace
Last updated
Last updated
This is a combined document for enabling the Dropzone AI Data Source and Alert Source for Google Workspace.
The Dropzone AI platform integrates with Google Workspace APIs for ingesting alerts such as phishing reports and enriching investigations with data from Google Workspace such as directory information. This document describes how to set up API credentials and install them into the Dropzone platform.
To enable these integrations you will perform the following actions:
Enable domain-wide delegation in Google Workspace
Create a Google Workspace admin role
Select integration parameters, such as which alert types to sync
The Dropzone platform has a dedicated service account for your organization. This service account uses domain-wide delegation to gain access to specific API scopes within your organization.
The following steps walk you through granting access to the Google service account used by your Dropzone platform.
Navigate to your Dropzone AI tenant home page e.g. https://mycompany.dropzone.ai
Click System > Integrations
Click "Data Sources" in the top left corner
Find the Google Workplace tile and click "Connect"
Record the "CLIENT ID" field which will be used in the Google Admin interface
Next, enable the Dropzone AI application domain-wide delegation access to your Google Workspace environment.
As a full Google Workspace admin, perform the following steps:
Go to https://admin.google.com
In the sidebar, navigate to "Security" > "Access and Data Control" > "API Controls"
At the bottom, click Manage Domain Wide Delegation
Click "Add New" API Client
Enter the Client ID in the pop up
This is the ~21 digit number you recorded from the Dropzone UI earlier
Grant access to the following scopes by copy/pasting them into the "OAuth Scopes" line one-by-one
https://www.googleapis.com/auth/apps.alerts
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.reports.audit.readonly
https://www.googleapis.com/auth/admin.reports.usage.readonly
https://www.googleapis.com/auth/admin.directory.group.readonly
Click "Authorize" to finish
Dropzone uses the Google Workspace Admin API to find information from your environment using a user within your org that has an Admin Role with necessary privileges.
The user you select could be a real human or a dedicated integration user. We suggest the latter to assure that personnel changes do not affect your integration. The integration user does not need a Google Workspace license, so it may be a free "Cloud Identity" user.
Note that Dropzone may request more permissions in the future as we add features.
Regardless which privileges you enable for your admin role, the Dropzone platform is restricted to the scopes that you granted in the "Set Up Domain Wide Delegation" section above.
To create and associate the new role you will perform the following actions:
Go to Account > Admin Roles > Create New Role
Name: "Dropzone AI Role"
Description: "Dropzone AI integrations"
Click "Continue"
You'll now be on the "Select Privileges" page
On this page enable the following:
Admin console privileges
Organizational Units > Read
Users > Read
Google Vault > Manage Audits
Gmail > Email log search
Gmail > Access Admin Quarantine
Gmail > Access Restricted Quarantines
Security Center > "This user has full ..." > Audit and Investigation > View
Security Center > "This user has full ..." > Audit and Investigation > View sensitive content
Security Center > Activity Rules > View
Security Center > Activity Rules > Manage
Alert Center > Full access
DLP > View DLP rule
DLP > Manage DLP rule
Reports
Admin API privileges
Organizational Units > Read
Users > Read
Groups > Read
Click "Continue"
There are two sections of this user interface, the "Admin Console Privileges" at top and "Admin API Privileges" further down the page; make sure you configure all the permissions from both sections.
Assign the new role to a Google Workspace user:
Go to https://admin.google.com
In the sidebar, navigate to Account > Admin Roles
Hover over the role you created and click "Assign Admin"
Click "Assign Members" to add the role to the user you want for the Dropzone integration
Pick an existing admin or an account you created specifically for the Dropzone integration
The Data source integration allows Dropzone AI to interact with Google Workspace to gather information for use in investigation analysis and interactive chat.
You'll need the following information:
| Dropzone Field | Source |
|---|---|
Admin Email | The email address of the admin in the new Dropzone AI role |
Customer ID | Your Google Workspace customer id |
The Customer ID can be found can be found at admin.google.com > Account > Account Settings (https://admin.google.com/ac/accountsettings) or in the output of gam info domain. It's typically a ~9 character string starting with C.
To enable the Data Source integration, do the following:
Navigate to your Dropzone AI tenant home page e.g. https://mycompany.dropzone.ai
Click System > Integrations
In the upper left click on the "Data Sources" button in the upper left do configure the Google Workspace Data Source integration
Click "Data Sources" in the top left corner
Find the "Google Workspace" tile and click "Connect"
Input the "Admin Email" and "Customer ID"
Click "Test & Save" to finish
If you have any errors engage your Dropzone AI support representative.
The Alert source integration allows Dropzone AI to pull alerts from Exchange Online and Microsoft Defender for investigation.
You'll need the following information:
| Dropzone Field | Source |
|---|---|
Admin Email | The email address of the admin in the new Dropzone AI role |
Customer ID | Your Google Workspace customer id |
The Customer ID can be found can be found at admin.google.com > Account > Account Settings (https://admin.google.com/ac/accountsettings) or in the output of gam info domain. It's typically a ~9 character string starting with C.
To enable the Alert Source integration, do the following:
Navigate to your Dropzone AI tenant home page e.g. https://mycompany.dropzone.ai
Click System > Integrations
In the upper left click on the "Alert Sources" button in the upper left do configure the Google Workspace Alert Source integration
Click "Alert Sources" in the top left corner
Find the "Google Workspace" tile and click "Connect"
Input the "Admin Email" and "Customer ID"
Dropzone can investigate phishing emails via multiple mechanisms.
| Method | Notes | Requirements | Configuration |
|---|---|---|---|
Google Workspace Phishing Alerts | Dropzone processes Google Workspace phishing alerts. [Google phishing alerts may take up to 4 hours to appear](https://support.google.com/a/answer/9104586 after users click the "Report Phishing" button in Gmail) | None - this is a built-in Google Workspace capability | Leave "Enable mailbox-based phishing analysis" unchecked |
Dedicated phishing mailbox | Dropzone polls a dedicated Google Workspace account for phishing emails to analyze | You must instruct your employees to forward suspected emails to a dedicated email box, or have a third-party reporting tool (typically a Gmail add-on) that creates the emails in the target mailbox | Check "Enable mailbox-based phishing analysis" and fill out "Phishing Processing via Mailbox" section |
If you want to use Google Workspace Phishing Alerts you are done — you may press "Test & Save" now
If you want to process phishing emails from a dedicated box, then do the following:
Enter the email address of your dedicated phishing account in "Phishing Account Email Address"
Set a Gmail filter if only some of the messages in this phishing account should be processed. For example some third-party tools may modify the subject to include "Phishing Alert", in which case you can use a Gmail filter like subject:"Phishing Alert" to limit processing to these messages
If you use a third-party tool that includes the original email as an attachment then check the "Prefer RFC822 message attachment, when present" button
Click "Test & Save" to finish
You should begin ingesting alerts immediately.
If you have any errors engage your Dropzone AI support representative.
