Google Workspace Logs
Panther supports pulling logs directly from Google Workspace
Last updated
Was this helpful?
Panther supports pulling logs directly from Google Workspace
Last updated
Was this helpful?
Panther can fetch Google Workspace (known formerly as G Suite) log events by querying the Google Workspace Reports API. Panther will query the Reports API for new events every 60 seconds.
In order for Panther to access the Google Workspace Reports API, you need to create and configure a Google Cloud app, and provide its credentials to Panther.
For the steps below to yield a successful integration, your Google user must be authorized to read your organization's activity records. If your user does not have this privilege, follow these Google Workspace instructions to create a new role with Reports access and assign the role to your user. If you plan to enable pulling Google Workspace user profiles, your user role must also have read user privileges.
In the left sidebar menu of the Panther Console, click Configure > Log Sources.
Click Create New.
Search for “Google Workspace,” then click its tile.
On the slide-out panel, click Start Setup.
On the Configuration page, configure the following field:
Name: Enter a descriptive name for the source e.g., My Google Workspace logs.
Click Setup.
On the Credentials page, copy the redirect URL and store it in a secure location. You will need this in the next steps.
Log in to your Google Cloud console.
Enter a descriptive Project name (e.g. Panther Integration) and choose a Location.
Click Create.
It will take a few seconds to create the project. Once created, you will see a notification on the page.
On the left sidebar menu, click the three lines icon, then Cloud Overview > Dashboard.
On the OAuth consent screen page, for User Type, select Internal.
Click Create.
On the OAuth consent screen > Branding page, fill in the following information:
App name: Enter your project name or project ID.
User support email: Select your email address.
Developer contact information: Enter your email address.
Leave the other fields blank.
Click Save and continue.
On the Data access > Scopes page, click Add or remove scopes.
In the Manually add scopes section, paste https://www.googleapis.com/auth/admin.reports.audit.readonly
(Optional) if user profiles are desired also paste scope:
https://www.googleapis.com/auth/admin.directory.user.readonly
Click Save.
In the top search bar, search for "Enable APIs & services" then select the matching result.
In the search bar, search for "Admin SDK API," and select Admin SDK API.
You will be redirected to another screen.
In the lefthand navigation menu, click Credentials.
At the top of the page, click +Create Credentials.
You will be redirected to a different page.
On the Create OAuth client ID page, in the Application type field, select Web application and type in a friendly Name, e.g., Panther.
Scroll down to the Authorized redirect URIs section, and click + Add URI.
Click Create.
A pop up modal will display a Client ID and Client Secret. Using a secure method, make note of the ClientID and Client Secret. You will need to provide them in the Panther Console to pull your reports.
Open the browser window or tab where you began the log source setup in the Panther Console earlier in this documentation.
On the Credentials page, enter the Client ID and Client Secret provided in your Google Cloud console.
If you did not save these values during the previous steps, you can find them in the Google Cloud console under APIs & Services > Credentials > OAuth 2.0 Client IDs.
Click Setup.
On the Enrichment page, if you would like to enable Google Workspace User Profiles, to the right of User Profiles, click the toggle ON.
Click Setup.
On the Verification page, click Grant Access.
This will prompt you to authorize the Google Workspace App you created earlier to pull Google Workspace logs from your account.
Click Allow.
You will be directed back to the Panther Console, where you will see a success screen:
You can optionally enable one or more Detection Packs.
The Trigger an alert when no events are processed setting defaults to YES. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.
See Panther-managed rules for Google Workspace in the panther-analysis GitHub repository (in directories prefixed with gsuite_).
Panther pulls data from Google's Reports Activities API which includes admin activity, login activity, token activity, Google Drive activity, and more.
This data gets mapped to both the GSuite.ActivityEvent and GSuite.Reports log types— while these two schemas contain the same data, we recommend using Gsuite.ActivityEvent because it flattens the events, making the fields easier to reference in queries and detections.
Contains the activity events for a specific account and application, such as the Admin console application or the Google Drive application.
Reference: Google Workspace Documentation on Reports API Activities List.
We recommend using GSuite.ActivityEvent instead of GSuite.Reports. While both schemas contain the same data, the structure of GSuite.ActivityEvent is flatter, and therefore easier to reference in queries and detections.
Contains the activity events for a specific account and application, such as the Admin console application or the Google Drive application.
Reference: Google Workspace Documentation on Reports API Activities List.
Click + Create project.
If the project you just created is not already selected in the dropdown at the top of the page, open the dropdown and select it.
In the top search bar, search for "OAuth consent screen," then select the matching result.
Click Add to table and Update.
On the Admin SDK API page, click Enable.
Click OAuth client ID.
In the URIs 1 field, paste the redirect URL provided in the Panther Console on the log source's Set Credentials page. You should have obtained this value earlier in the documentation while creating the log source in the Panther Console.
If you toggled User Profiles ON, also set a Refresh period (min). This represents the cadence at which Panther will update profile data with what is stored in Google Workspace.
