Google Workspace - Directory 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.
• Retrieve your Customer ID (Tenant ID) from the Google Workspace Admin console.
• Configure a Google Workspace - Directory API Connector with your Customer ID and Service Account JSON Key details.
• Use Query to search for information on Users and Devices within a Google Workspace directory 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.

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.

To connect a Google Workspace - Directory API Connector with Query Federated Search you'll need to execute 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. To retrieve the Customer ID for your Google Workspace tenant from the Admin console navigate to Account --> Account settings and copy the value underneath the Profile header as shown below (FIG. 1).

   

   
   

   👍

   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 - Directory 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 - Directory API from the Identity and HR category as shown below (FIG. 2). You can also search for Google Workspace - Directory API using the search bar in the Add Connector page.

   

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

   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. Customer ID: The Customer ID of your Google Workspace tenant, copied in Step 4 of the Prerequisites section.

   4. GCP Service Account JSON Key Contents: The JSON contents of your GCP Service Account JSON key, copied in Step 3 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 Customer ID.

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

Querying Google Workspace - Directory API Connectors

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

Entity-based Search

The Google Workspace - Directory 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 - Directory API methods. The two details retrieved from the Directory 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. 5). For instance, you can search for a specific User UID or Email Address to retrieve details about them and their mobile devices from the directory, these 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. 6).

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 - Directory 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. 7), in this case select the Discovery category to find the Device Inventory Info Event Class. You can also search across all Connectors normalized to Device Inventory Info such as Jamf, Microsoft Intune, Crowdstrike, or other data lake or SIEM resources mapped to Device Inventory Info such as asset data from ITSM and CAASM reports, and otherwise.

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 HTTP Activity events, you can specify a specific mobile device hostname by filtering for Device --> Hostname as shown below (FIG. 8).

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. 9). In this case a multiple values were used to search for Non-Compliant devices (that are reporting as compromised) that checked in the last 30 days and are running an Android OS.

Resources

• Enable Google Workspace APIs
• Create access credential

Troubleshooting Steps

• Ensure that you have the proper license for your Google Workspace tenant.
• Ensure you provided the correct Customer ID and 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.