Google Workspace - Reports API

📘

TL;DR

To integrate Google Workspace with Query:

• Activate the required Google Workspace Admin SDK API from a Google Cloud Project.
• Create a Service Account, assign it Google Workspace admin & domain-wide delegation and create a JSON key.
• Configure a Google Workspace - Directory API Connector with your Service Account JSON Key details.
• Use Query to search for information on Login, Drive, Token, Admin, and Drive applications within Google Workspace Reports for usage by Incident Response (IR), Investigations, Threat Hunting, Audit, and Security Operations teams.

Overview

Google Workspace (formerly known as G-Suite) is a cloud-based productivity suite that offers tools for collaboration, communication, and organization, such as Gmail, Google Drive, Google Calendar, and Google Meet. It enables businesses to streamline workflows, manage files securely, and collaborate in real-time across various locations and devices.

Security and IT personnel use Google Workspace to manage user access, enforce security policies, and monitor activity, helping protect organizational data through advanced security features like two-step verification, data loss prevention (DLP), and mobile device management (MDM). Google Workspace's centralized admin console provides IT teams with powerful tools for user management, security insights, and policy enforcement to safeguard company information.

As of 1 DEC 2024, Query integrates with Google Workspace across three distinct Connectors associated with data surfaced by the following APIs: Directory API, Reports API and the Gmail Messages API. This separation of Connectors by API allows customers to assign different Service Accounts, different delegations, and limit overall access to certain APIs to different Teams and Organizations within Query. The following capabilities are supported from the aforementioned APIs. Refer to the API-specific documentation in Query for more information on how to configure specific connectivity.

All federated searches have their searches and results expressed in the terms of the Query Data Model (QDM), which is based on the Open Cybersecurity Schema Framework (OCSF). Each API source is normalized into a specific QDM/OCSF Event Class to standardize and normalize the data for increased situational awareness, ease of aggregation of filtering, and easy pivoting.

Executing federated searches with Query allows you to pull all relevant data for your search criteria back in a parallelized, normalized, and standardized format without ever moving or duplicating the data into another data repository.

📘

A bit on Reports API Normalization for login

The Reports API Activity of Logins (applicationName=login) covers everything from authentication, suspicious activity, inbox filtering events, and user/membership/token changes so specific Event Names are normalized into different QDM Event Classes.

Account Change: 2sv_enroll,2sv_disable,recovery_email_edit,recovery_phone_edit,recovery_secret_qa_edit,password_edit

API Activity: blocked_sender

Authentication: Everything else!

Prerequisites

To use any of the three Google Workspace Connectors, you must first ensure that you are on a paid tier of Google Workspace (e.g., Business Starter, Business Standard, Enterprise) otherwise you will not have access to the APIs. Additionally, you should have Super Admin, Admin, or a similarly privileged role for your Google Workspace Admin portal to be able to complete or verify completeness of the following steps.

1. Firstly, ensure you have access to a Google Cloud project with an Owner role, or have permissions to enable Google Workspace APIs. For more information see the Create a Google Cloud project section of the Google Workspace Guide.
2. Next, enable the Admin SDK API and Gmail API by navigating to the menu in your Google Cloud project and navigating to More Products --> Google Workspace --> Product Library and toggling the APIs. For more information see the Enable Google Workspace APIs section of the Google Workspace Guide. You can alternatively enable these APIs with the gcloud CLI.

gcloud services enable admin.googleapis.com

3. Next, follow the steps detailed in the Service account credentials section of the the Create access credential section of the Google Workspace Guide. At a high level you will create an IAM Service Account, assign it as an Admin, toggle domain-wide delegation, and generate a JSON Service Account Key.
4. Finally, Verify admin privileges of a delegated administrator in your Workspace directory to specify as the Delegated Administrator. This ensures that every Report in the Reports API can be retrieved.

👍

On NHI security

NHI - or, Non-Human Identities - such as your GCP Service Account JSON Keys are extremely sensitive. Query securely stores the Client Secret in a dedicated AWS Secrets Manager Secret per Connector per Tenant.

While this requires you to configure Connectors per individual Google Workspace tenant and continue to enter in your credentials, every copy is stored as securely as each other with minimum necessary permissions that only allows the specific piece of serverless infrastructure to retrieve the secret, it is never cached or persisted outside of the Secret.

Setting up the Google Workspace - Reports API Connector

Use the following steps to create a new Query Federated Search Connector for Google Workspace - Directory API.

1. Navigate to the Connectors page, select Add Connector, and selectGoogle Workspace - Reports API from the SIEM and Log Management category as shown below (FIG. 1). You can also search for Google Workspace - Reports API using the search bar in the Add Connector page.

   

2. In the Configure Connector tab, add the following detail as shown below (FIG. 2):

   1. Connector Alias Name: The human-readable name you want to give to this connector, you can provide the name...

   2. Default Login: Leave the default value: Default Login.

   3. GCP Service Account JSON Key Contents: The JSON contents of your GCP Service Account JSON key, copied in Step 3 of the Prerequisites section.

   4. Delegated Administrator Email: The email of a delegated administrator that has permissions to access all Reports, found in Step 4 of the Prerequisites section.

      

3. Select Save to save and activate the Connector.

4. Finally, select Test Connection from the bottom-right of the connection pane to ensure that your Google Workspace has the correct license tier, that the Admin SDK is activated, and that connectivity can be established with your credentials and delegated admin.

You will now see Google Workspace - Reports API added as an available Connector within the Query Search and Query Summary Insights UI.

Querying Google Workspace - Reports API Connectors

Within the Query Search UI, all Connectors are enabled by default. To check that your specified Connector(s) for Google Workspace - Reports API are enabled, navigate to the SIEM and Log Management section of the Selected Connectors dropdown and ensure that your specified Google Workspace - Reports API Connector(s) are are selected (denoted by a checkbox) before running your searches as shown below (FIG. 3).

Entity-based Search

The Google Workspace - Reports API Connector is a static schema Connector which means that all normalization and search translation is completely defined by the Query team. Refer back to the Introduction section and refer to the table to learn which Entities map against which Google Workspace - Reports API methods. The two details retrieved from the Reports API as of now are Mobile Devices and Users.

In the Federated Search console, select the search dropdown, ensure the Entities radio button is selected and search for your desired Entity as shown below (FIG. 4). For instance, you can search for a specific User UID or Email Address to retrieve details about them and all of their related activities such as Logins, Google Drive interactions, Token authentication, and more. These results can be further correlated against other different Query Connectors.

After selecting an Entity, most allow you to specify an Operator. This allows you to perform simple equality searches or to perform more generalized searches using Contains, Starts With, or Ends With Operators. These are fulfilled against the appropriate Google Admin SDK API methods and search parameters where possible.

When you search for multiple values that may be present across different Connectors, the Query Federated Search query planner inspects the Configure Schema metadata to ensure searches are sent to the appropriate Connectors, this operates more as a collated window function within Query and not as an expensive SQL join.

Additionally, you can specify case-sensitivity for the entire search criteria. An example of a multi-value CVE search that uses the equals operator and toggled case-sensitivity is shown below (FIG. 5).

Event-based Search

Event-based searches allow you to broadly search across the entirety of results from a downstream API, or, search for very specific results based on filters. Refer back to the Introduction section and refer to the table to learn which Events map to the Google Workspace - Reports API Connector.

In the Federated Search console, select the search dropdown, ensure the Events radio button is selected and search for your desired Event as shown below (FIG. 6), in this case select the Identity and Access Management category to find the Authentication Event Class. This will search the Login Activity reports in the Google Workspace Admin SDK, but it will also dispatch queries to other Connectors that support the Authentication Event Class such as Okta, Auth0, Entra ID, and CloudTrail Management Logs in Amazon Security Lake.

Searching from the Event will pull a sample (up to 2500) of all matching events per Connectors that are mapped to it. For more specific filtering within an Event, you can choose one or more conditions to refine a search. Selecting the plus-sign (+) dropdown next to the Event menu allows you to choose from any specific OCSF/QDM attribute in the event.

For instance, when searching for Authentication events, you can search for logins that were not authenticated by MFA by filtering for Multi Factor Authentication --> False as shown below (FIG. 7).

When adding two or more Conditions, you can further change the behavior by specifying ANY or ALL quantifiers over the filters for greater levels of specificity or more narrow-but-generalized searches, respectively, as shown below (FIG. 8). In this example, failed logins with MFA for a specific Google Workspace tenant are returned.

Resources

• Enable Google Workspace APIs
• Create access credential
• Delegate administrator privileges in Gmail

Troubleshooting Steps

• Ensure that you have the proper license for your Google Workspace tenant.
• Ensure you provided the correct GCP Service Account JSON key.
• Ensure that your Service Account is properly delegated.

If you have exhausted the above Troubleshooting list, please contact your designated Query Sales Engineer or Customer Success Manager. If you are using a free tenant, please contact Query Customer Success via the Support email in the Help section, or via Intercom within your tenant.