Google Workspace Integration Guide
The following instructions are for configuring an integration of Google Workspace to facilitate log ingestion into Secureworks® Taegis™ XDR.
Before You Begin ⫘
Collection of Google Workspace logs uses two APIS:
Both APIs are part of the Google Workspace Admin SDK API. To enable XDR to query this API for data, several prerequisite steps are required, including:
- An active Google Workspace account and access to an administrator role
- A Google API Console Project
Complete these prerequisites steps as documented at Google Workspace Reports API: Prerequesites.
Important
This guide assumes these prerequisite steps are complete before beginning setup.
The following sections guide you through:
- Creating a service account with access to the Admin SDK API and creating credentials for this account
- Enabling domain-wide delegation for the service account
- Creating or using an existing user for the service account to impersonate when querying the Admin SDK Reports API
- Adding credentials to XDR to enable integration
- Adding the username of the user to impersonate to XDR to enable integration
- Enabling XDR to integrate with the Reports And Alert Center API for log collection
Note
Lag time—the delay between the time an event occurs and when it is available for collection—is expected for a variety of the logs supported for collection. Find Google’s documentation for data retention and lag times in the following Google Workspace Admin Guide article: Data retention and lag times.
Data Provided from Integrations ⫘
| Antivirus | Auth | CloudAudit | DHCP | DNS | Encrypt | HTTP | Management | Netflow | NIDS | Thirdparty | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Google Workspace | D, V | V | V |
Y = Normalized | D = Out-of-the-Box Detections | V = Vendor-Specific Detections
Note
XDR detectors are not guaranteed to be triggered, even if a data source's logs are normalized to a schema associated with a given detector. However, you can create Custom Alert Rules to generate alerts based on normalized data from a data source.
Create a Service Account Credential ⫘
Create a service account and corresponding credential in the Google console API project that you created in the prerequisite steps using the Google Workspace Admin Guide article Reports API: Prerequesites.
Google Cloud Hierarchy - Projects
- Log in to your Google Workspace admin account from the Google Cloud Console.
- Verify that the correct project is selected from the top menu. This project is used to create a service account to enable XDR access to query login data across your organization.
Google Project Name Selection
- Navigate to the APIs Library: from the hamburger menu, select APIs and Services→Library.
- Search for the Admin SDK API and select the corresponding API card from the results.
- Click Enable to enable the Admin SDK API in this project.
- Additionally, search for the Alert Center API.
- Click Enable to to enable the Alert Center API in this project.
- Navigate to the API Credentials: from the hamburger menu, select APIs and Services→Credentials.
- Select + Create Credentials and then Service Account from the drop down menu.
Create Google Credentials
- In Service account details, enter a Service account name (see the Google Cloud documentation for User-managed service accounts). You can enter any name, but Secureworks recommends something indicating this service account is for use with XDR so it is not accidentally removed.
- The Service account ID populates automatically based on the entered account name. Optionally, you can alter this ID.
- Optionally, enter a Service account description or leave this field blank. Secureworks recommends a description indicating this is in use for enabling XDR.
- Choose DONE.
Create Google Service Account
- From the Service Accounts table, select the service account that was created.
Select Service Account
- Record the Unique ID value displayed. Make a note of it as you will be prompted for this when delegating domain-wide delegation in the next section.
Google Service Account Unique ID
- From the Keys menu, select the Add Key drop down and choose Create new key.
Create New Key
- Select JSON as the key type, then select CREATE.
Important
A JSON file is saved to your local filesystem. Store the file securely because it cannot be recovered if lost, and contains secure credentials to access this service account and data from your Google organization. You will be prompted to upload this file to XDR in the Enter Credentials section.
Delegate Domain-Wide Authority to the Service Account ⫘
The service account created in Steps 10-13: Service Account Details requires access to the user data on behalf of users in the domain. This step enables service account access to the Admin SDK API for the domain, instead of only in the project it was created. This is referred to as delegating domain-wide authority.
Google Cloud Hierarchy - Organization
- Log in to the Google Admin Console.
- Navigate to the API Controls: from the hamburger menu, select Security→Access and data control→API controls.
Google Admin API Controls
- Select MANAGE DOMAIN WIDE DELEGATION.
Google Manage Domain Wide Delegation
- Select Add new.
Google Domain Wide Delegation - Add New
- In the Client ID field, enter the Unique ID recorded from the Create a Service Account step.
- In OAuth scopes, enter the following:
https://www.googleapis.com/auth/admin.reports.audit.readonly
https://www.googleapis.com/auth/admin.reports.usage.readonly
https://www.googleapis.com/auth/apps.alerts
- Select AUTHORIZE.
Google Domain Wide Delegation - Authorize
Create or Select an Existing User for Impersonation ⫘
To access the Reports and Alert APIs, a user with the Reports administrator and Alert Center view access privileges must be enabled. When XDR collects logs from your organization, it uses the service account to request a token used to impersonate a user with this access. All audited actions performed by XDR are recorded as this user. Because of this, Secureworks recommends that a new user be created only to be used as impersonation by XDR. An existing user with the correct privileges can also be used.
- To create a new user, see Option 1: Create a New User for Impersonation.
- To use an existing user, see Option 2: Use an Existing User for Impersonation.
Option 1: Create a New User for Impersonation ⫘
- Log in to the Google Admin Console.
Tip
Optionally, you can create a custom administrator role to further restrict access beyond that of the pre-built admin roles. To do this, navigate to the Admin roles menu: from the Hamburger menu, select Account→Admin roles and proceed to the next step. If you wish to only use a pre-built role, skip to Step 30.
- Select Create New Role.
Google Create Custom Admin Role
- Enter a Name and Description for the role info, then select CONTINUE.
Google Name Custom Role
- From the Security section, select the Reports privilege. Additionally, from the Services→Alert Center section, select the View access privilege, and then CONTINUE.
Google Select Privilege
-
Review the Review Privileges screen for accuracy, then click CREATE ROLE.
-
Navigate to the Users Directory: from the hamburger menu, select Directory→Users.
-
Select Add new user.
Google Add User
- Enter the corresponding user information. Secureworks recommends that the name indicates that this user is in use by XDR and should not be removed.
Google Create User
- Select the username of the user that was created from the Users table.
- Select ASSIGN ROLES from Admin roles and privileges.
Google Add Admin Role
- A list of admin roles appears. Select either the custom role you created or any role with the Reports admin privilege and Alert Center view access privilege, click the toggle from the Assigned state column so the role shows as Assigned, and then select SAVE
Google Save Pre-Built Admin Role
- Record the email of this user for the next step in this guide, Enter Service Account Credentials and Username Information.
Option 2: Use an Existing User for Impersonation ⫘
- Log in to the Google Admin Console.
- Navigate to the Users Directory: from the hamburger menu, select Directory→Users.
- From the list of users in the table, select a user with access to the Reports admin privilege and Alert Center view access privilege. Record the email for the next step in this guide, Enter Service Account Credentials and Username Information.
Note
To verify if a user has this privilege, select the username, expand the Admin Roles and privileges table, and verify that the Reports privilege and Alert Center view access is assigned.
Enter Service Account Credentials and Username Information ⫘
- Log in to XDR and navigate to Integrations → Cloud APIs.
- Select Set Up Google Integrations.
- In the XDR Configuration window, enter the following:
- Integration Name—Any user-friendly name to uniquely identify this integration.
- Email—the email address copied in the user impersonation section. This user will be shown for all audited reports of actions taken by the integration when collecting data.
- Select Upload Key File and navigate to the JSON service account key downloaded in the section to create a service account credential.
Add Google Workspace Integration
- Select Done to save the integration and begin collection of Google Workspace logs. When navigating to Integrations → Cloud APIs, XDR now displays the following integrations:
- Google Workspace (name entered during integration steps) — This is a holder integration to display the overall health of this integration. If any of the following collection categories become unhealthy, this category will additionally become unhealthy.
- Google Workspace Login (name entered during integration steps) — This displays the health of the login activity report.
- Google Workspace Admin (name entered during integration steps) — This displays the health of the admin activity report.
- Google Workspace Chrome (name entered during integration steps) — This displays the health of the chrome activity report.
- Google Workspace Alert (name entered during integration steps) — This displays the health of retrieving Alert Center alerts.