Ctrlk
Knowledge BaseRelease NotesRequest Demo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Google Workspace Logs

Panther supports pulling logs directly from Google Workspace

Overview

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.

Panther pulls Google Workspace logs for the following applications:

  • Access Transparency

  • Admin

  • Calendar

  • Chat

  • Chrome

  • Classroom

  • Context-Aware Access

  • Data Studio (Looker Studio)

  • Drive

  • GCP

  • Gemini for Workspace

  • Gmail

  • Groups

  • Groups Enterprise

  • Keep

  • Login

  • Meet

  • Mobile

  • Rules

  • SAML

  • Token

  • User Accounts

  • Vault

How to onboard Google Workspace logs to Panther

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.

Prerequisites

To complete the steps below, your Google user must:

Step 1: Create a new Google Workspace source in Panther

  1. In the left sidebar menu of the Panther Console, click Log Sources.

  2. Click Create New.

  3. Search for “Google Workspace,” then click its tile.

  4. On the slide-out panel, click Start Setup.

  5. On the Configuration page, configure the following field:

    • Name: Enter a descriptive name for the source e.g., My Google Workspace logs.

  6. Click Setup.

Step 2: Create and configure a Google Cloud app

Before setting up a Google Cloud app, you'll need to choose an authentication method. You can use a Service Account, Workload Identity Federation, or OAuth —see the top-level tabs below.

Once you create a Google Workspace log source in Panther, you cannot change the authentication method. Choose your preferred authentication method carefully before proceeding with the setup, as this choice is permanent for the log source.

  1. Create a new app in Google Cloud:

    1. Log in to your Google Cloud console.

    2. Click + Create project. In Google Cloud console, the "+Create Project" button appears at the top of the page under the search bar. In this image, there is a teal circle around it.

    3. Enter a descriptive Project name (e.g. Panther Integration) and choose a Location.

    4. Click Create.

      • It will take a few seconds to create the project. Once created, you will see a notification on the page.

    5. On the left sidebar menu, click the three lines icon, then Cloud Overview > Dashboard.

    6. 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. At the top of the Google Cloud dashboard, there is a dropdown. "Panther integration test" has been selected, and the select box is circled.

  2. Enable the Admin SDK API:

    1. In the search bar, enter"Admin SDK API," and select Admin SDK API.

    2. On the Admin SDK API page, click Enable. In the Google Cloud console, an Admin SDK API page is shown. An Enable button is circled.

      • You will be redirected to a new screen.

  3. Create a new Google Cloud service account.

  4. Generate a JSON key file for the service account:

    1. In the IAM & Admin section, click Service Accounts.

    2. On the row of the service account you just created, click Actions, then Manage keys.

    3. Click Add Key > Create new key.

    4. Under Key type, select JSON, then click Create.

      • A JSON file will be downloaded.

    Keep this file in a safe place—it contains the credentials for this service account.

  5. Enable Domain-wide delegation:

    1. On the row of the service account you just created, click Actions, then Manage details.

    2. Click Advanced settings, then copy the Client ID.

    3. Click View Google Workspace Admin Console.

    4. Sign in with an Administrator account.

    5. Click Security → Access and data control → API controls.

    6. Click Manage Domain-wide delegations.

    7. Click Add new.

    8. Fill in the fields:

      1. Client ID: enter the Client ID you copied above.

      2. OAuth scopes (comma-separated, no spaces): enter https://www.googleapis.com/auth/admin.reports.audit.readonly

        • (Optional) If user profiles are desired, also enter (separated by a comma) https://www.googleapis.com/auth/admin.directory.user.readonly

    9. Click Authorize.

  6. Choose the Google Admin user to impersonate when retrieving data. You have two options :

    • Use a SuperAdmin account: This is simpler to set up but grants broader permissions than strictly necessary.

    • Follow the principle of least privilege (recommended): Create and use a dedicated Google Workspace user with only the required permissions

      1. Create a custom admin role in Google Workspace with minimal permissions.

      2. Grant the minimum required permissions to the role:

        1. Required: Reports → Audit/Usage read access

        2. Optional: Directory → Users read access (if using user profiles)

        3. Optional: Vault → Google Vault Access All Logs

      3. Assign this custom role to a dedicated Google Workspace user.

  7. Finish the source setup in Panther:

    1. Under Provide pulling configuration & JSON Keyfile, upload your JSON key file.

    2. In the Admin User Email field, enter the email address of the Google Admin user that the service account will impersonate (chosen in previous step).

    3. On the Enrichment page, if you would like to enable Google Workspace User Profiles, to the right of User Profiles, click the toggle ON.

    4. Click Setup. You will be directed to a success screen:

      The success screen reads, "Everything looks good! Panther will now automatically pull & process logs from your account"

      • You can optionally enable one or more Detection Packs.

      • If you have not done so already, click Attach or Infer Schemas to attach one or more schemas to the source.

      • 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.

  1. Create a new app in Google Cloud:

    1. Log in to your Google Cloud console.

    2. Click + Create project. In Google Cloud console, the "+Create Project" button appears at the top of the page under the search bar. In this image, there is a teal circle around it.

    3. Enter a descriptive Project name (e.g. Panther Integration) and choose a Location.

    4. Click Create.

      • It will take a few seconds to create the project. Once created, you will see a notification on the page.

    5. On the left sidebar menu, click the three lines icon, then Cloud Overview > Dashboard.

    6. 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. At the top of the Google Cloud dashboard, there is a dropdown. "Panther integration test" has been selected, and the select box is circled.

  2. Enable the Admin SDK API:

    1. In the search bar, enter "Admin SDK API," and select Admin SDK API.

    2. On the Admin SDK API page, click Enable. In the Google Cloud console, an Admin SDK API page is shown. An Enable button is circled.

      • You will be redirected to a new screen.

  3. Create a new Google Cloud service account.

    1. On the row of the service account you just created, note down the Email. You will need this in the next steps.

  4. Configure Workload Identity Federation with AWS by following the Configure Workload Identity Federation with AWS or Azure documentation.

    1. As you are defining an attribute mapping(s) and condition, take note of the following examples:

      • Example attribute mappings:

        Google
        AWS

        google.subject

        assertion.arn.extract('arn:aws:sts::{account_id}:')+":"+assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')

        attribute.account

        assertion.account

      • Example attribute condition: attribute.account=="<PANTHER_AWS_ACCOUNT_ID>"

      The value of the google.subject attribute cannot exceed 127 characters. You may use Common Expression Language (CEL) expressions to transform or combine attributes from the token issued by AWS. The expression suggested in the table above takes this limit into account, and is an attempt at transforming the ARN into a value that uniquely identifies Panther entities. For more information on the AWS attributes, see "Example 2 - Called by user created with AssumeRole" on this AWS documentation page.

    2. When you are adding a provider to your identity pool, select AWS.

    3. Go to IAM & Admin → Workload Identity Federation.

      1. Click the display name of the Workload Identity Pool you just created.

      2. Note down the IAM principal shown on this page. You'll need it in the next steps.

  5. Grant IAM Permissions

    1. Go to IAM & Admin → Service Accounts

    2. On the row of the service account you just created, click on the Email

    3. Go to “Principals with access” tab

    4. Click “Grant access”

    5. In “New principals” field, you must add two entries.

      1. First principal: the Workload Identity principal

        1. The IAM principal you copied earlier will look similar to this:

        2. Modify this value by:

          • Replacing principal:// with principalSet://

          • Removing everything starting from /subject/

          • Replacing it with /*

        3. After the change, it should look like this:

        4. Paste this modified value into the New principals field.

      2. Second principal: the service account email

        1. Paste the service account email address you noted in an earlier step.

          1. Example format:

      3. Ensure both entries are present.

    6. In the "Assign roles" field, select Service Account Token Creator role

    1. Click on “Save”

  6. Download the credentials configuration file, which will be used in Panther to authenticate to the Google Workspace logs API.

  7. Enable Domain-wide delegation:

    1. Go to IAM & Admin → Service Accounts

    2. On the row of the service account you just created, click Actions, then Manage details.

    3. Click Advanced settings, then copy the Client ID.

    4. Click View Google Workspace Admin Console.

    5. Sign in with an Administrator account.

    6. Click Security → Access and data control → API controls.

    7. Click Manage Domain-wide delegations.

    8. Click Add new.

    9. Fill in the fields:

      1. Client ID: enter the Client ID you copied above.

      2. OAuth scopes (comma-separated, no spaces): enter https://www.googleapis.com/auth/admin.reports.audit.readonly

        • (Optional) If user profiles are desired, also enter (separated by a comma) https://www.googleapis.com/auth/admin.directory.user.readonly

    10. Click Authorize.

  8. Select the Google admin user account that the service account will impersonate when retrieving data. See Why is an admin user email required for impersonation? for more information. You have two options:

    • Use a SuperAdmin account: This is simpler to set up but grants broader permissions than strictly necessary.

    • Follow the principle of least privilege (recommended): Create and use a dedicated Google Workspace user with only the required permissions.

      1. Create a custom admin role in Google Workspace with minimal permissions.

      2. Grant the minimum required permissions to the role:

        1. Required: Reports → Audit/Usage read access

        2. Optional: Directory → Users read access (if using user profiles)

        3. Optional: Vault → Google Vault Access All Logs

      3. Assign this custom role to a dedicated Google Workspace user.

  9. Finish the source setup in Panther:

    1. Under Provide pulling configuration & Credential Configuration File, upload your credential configuration file.

    2. In the Admin User Email field, enter the email address of the Google Admin user that the service account will impersonate (chosen in previous step).

    3. On the Enrichment page, if you would like to enable Google Workspace User Profiles, to the right of User Profiles, click the toggle ON.

    4. Click Setup. You will be directed to a success screen:

      The success screen reads, "Everything looks good! Panther will now automatically pull & process logs from your account"

      • You can optionally enable one or more Detection Packs.

      • If you have not done so already, click Attach or Infer Schemas to attach one or more schemas to the source.

      • 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.

  1. On the Credentials page, copy the redirect URL and store it in a secure location. You will need this in the next steps.

  2. Create a new app in Google Cloud:

    1. Log in to your Google Cloud console.

    2. Click + Create project. In Google Cloud console, the "+Create Project" button appears at the top of the page under the search bar. In this image, there is a teal circle around it.

    3. Enter a descriptive Project name (e.g. Panther Integration) and choose a Location.

    4. Click Create.

      • It will take a few seconds to create the project. Once created, you will see a notification on the page.

    5. On the left sidebar menu, click the three lines icon, then Cloud Overview > Dashboard.

    6. 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. At the top of the Google Cloud dashboard, there is a dropdown. "Panther integration test" has been selected, and the select box is circled.

    7. In the top search bar, search for "OAuth consent screen," then select the matching result. The search bar at the top of Google Cloud Console has the search term "oauth consent screen" typed in it. the first result, "OAuth consent screen," is circled

    8. On the OAuth consent screen page, click Get Started.

  3. Configure your new Google Cloud app and enable Admin SDK API:

    1. 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.

      • Audience: Select Internal.

      • Developer contact information: Enter your email address.

      • Leave the other fields blank.

    2. Click Save and continue.

    3. On the Data access > Scopes page, click Add or remove scopes.

    4. In the Manually add scopes section, enter https://www.googleapis.com/auth/admin.reports.audit.readonly

      • (Optional) if user profiles are desired, also enter https://www.googleapis.com/auth/admin.directory.user.readonly

    5. Click Add to table and Update. In the Manually add scopes section of the Google Cloud page, a URL has been entered. There is an arrow pointing from the Add to table button to the Update button.

    6. Click Save.

    7. In the search bar, search for "Admin SDK API," and select Admin SDK API.

    8. On the Admin SDK API page, click Enable. In the Google Cloud console, an Admin SDK API page is shown. An Enable button is circled.

      • You will be redirected to a new screen.

  4. Create OAuth credentials for your new Google Cloud app:

    1. In the lefthand navigation menu, click Credentials.

    2. At the top of the page, click +Create Credentials.

    3. Click OAuth client ID. In Google Cloud console, the Credentials link in the left sidebar is highlighted. There is an arrow pointing from it to the "+ Create Credentials" link. There is an arrow pointing from "+ Create Credentials" to one of the dropdown options, "OAuth Client ID"

      • You will be redirected to a different page.

    4. On the Create OAuth client ID page, in the Application type field, select Web application and type in a friendly Name, e.g., Panther.

    5. Scroll down to the Authorized redirect URIs section, and click + Add URI.

    6. In the URIs 1 field, paste the redirect URL you copied above, in Step 2.1. This is found in the Panther Console on the log source's Set Credentials page. There is an "Authorized Redirect URIs" header. There is a field labeled "URIs 1". At the bottom, there is a blue "Create" button.

    7. Click Create.

    8. 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.

  5. Finish Google Workspace source setup in Panther:

    1. Open the browser window or tab where you began the log source setup in the Panther Console earlier in this documentation.

    2. 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.

    3. Click Continue.

    4. On the Enrichment page, if you would like to enable Google Workspace User Profiles, to the right of User Profiles, click the toggle ON.

    5. Click Setup.

    6. 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.

      A Google prompt is titled "Panther integration app wants to access your Google Account." Below, it says, "This will allow Panther integration app to: View audit reports for your G Suite domain." Below, there are Allow and Cancel buttons.

    7. You will be directed back to the Panther Console, where you will see a success screen:

    The success screen reads, "Everything looks good! Panther will now automatically pull & process logs from your account"

    • 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.

      The "Trigger an alert when no events are processed" toggle is set to YES. The "How long should Panther wait before it sends you an alert that no events have been processed" setting is set to 1 Day

Panther-managed detections

See Panther-managed rules for Google Workspace in the panther-analysis GitHub repository (in directories prefixed with gsuite_).

Supported log types

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 stored as both GSuite.ActivityEvent and GSuite.Reports log types—while these two schemas contain the same data, it's recommended to use Gsuite.ActivityEvent because it flattens the events, making the fields easier to reference in queries and detections.

While both schemas capture the same data, they store it differently in the data lake. For example, GSuite.Reports may have a slightly smaller number of logs in the data lake because multiple events are wrapped in one payload. In GSuite.ActivityEvent, however, each event becomes a single event in Panther. More information about this behavior can be found in the Knowledge Base article: What is the difference between the Panther log types GSuite.Reports and GSuite.ActivityEvent?

While Google Workspace logs are stored in both the GSuite.ActivityEvent and GSuite.Reports tables in your data lake, the data is only counted once against your ingestion quota.

GSuite.ActivityEvent

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.

GSuite.Reports

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.

PreviousGitLab LogsNextHeroku Logs

Last updated

Was this helpful?