# Google Workspace Logs
## Overview
Panther can fetch [Google Workspace](https://workspace.google.com/) (known formerly as G Suite) log events by querying the [Google Workspace Reports API](https://developers.google.com/admin-sdk/reports/v1/get-start/getting-started). Panther will query the Reports API for new events every 60 seconds.
Google Workspace applications Panther pulls logs for
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:
* Be authorized to read your organization's activity records
* If your user does not have this privilege, follow [these Google Workspace instructions](https://support.google.com/a/answer/2406043) 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](https://docs.panther.com/enrichment/google-workspace)) have read user privileges
### Step 1: Create a new Google Workspace source in Panther
1. In the left sidebar menu of the Panther Console, click **Configure** > **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](https://cloud.google.com/iam/docs/service-account-overview), [Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation), or [OAuth](https://developers.google.com/identity/protocols/oauth2) —see the top-level tabs below.
{% tabs %}
{% tab title="Service account" %}
1. Create a new app in Google Cloud:
1. Log in to your [Google Cloud console](https://console.developers.google.com/project).
2. Click **+ Create project.**\
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.\
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.**\
* You will be redirected to a new screen.
3. [Create a new Google Cloud service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts).
4. [Generate a JSON key file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) 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](https://support.google.com/a/answer/9807615?hl=en).
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](https://docs.panther.com/enrichment/google-workspace), to the right of **User Profiles**, click the toggle `ON`.
* Note the [prerequisites for enabling Google Workspace profiles](https://docs.panther.com/enrichment/google-workspace#prerequisites-for-google-workspace-user-profiles).
* 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.\
4. Click **Setup**. You will be directed to a success screen:
* You can optionally enable one or more [Detection Packs](https://docs.panther.com/detections/panther-managed/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.
{% endtab %}
{% tab title="Workload Identity Federation" %}
1. Create a new app in Google Cloud:
1. Log in to your [Google Cloud console](https://console.developers.google.com/project).
2. Click **+ Create project.**\
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.\
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.**\
* You will be redirected to a new screen.
3. [Create a new Google Cloud service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts).
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](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds) documentation.
1. As you are [defining an attribute mapping(s) and condition](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#mappings-and-conditions), take note of the following examples:
* Example [attribute mappings](https://cloud.google.com/iam/docs/workload-identity-federation#mapping):
* Example [attribute condition](https://cloud.google.com/iam/docs/workload-identity-federation#conditions):\
`attribute.account==""`
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](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws), 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](https://docs.cloud.google.com/iam/docs/workload-download-cred-and-grant-access#download-configuration), 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?](https://help.panther.com/articles/6633569239-why-does-setting-up-google-workspace-with-workload-identity-federation-in-panther-require-an-admin-user-email-for-impersonation?lang=en) 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](https://support.google.com/a/answer/9807615?hl=en).
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](https://docs.panther.com/enrichment/google-workspace), to the right of **User Profiles**, click the toggle `ON`.
* Note the [prerequisites for enabling Google Workspace profiles](https://docs.panther.com/enrichment/google-workspace#prerequisites-for-google-workspace-user-profiles).
* 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.\
4. Click **Setup**. You will be directed to a success screen:
* You can optionally enable one or more [Detection Packs](https://docs.panther.com/detections/panther-managed/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.
{% endtab %}
{% tab title="OAuth" %}
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](https://console.developers.google.com/project).
2. Click **+ Create project.**\
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.\
7. In the top search bar, search for "OAuth consent screen," then select the matching result.\
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**.\
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.**\
* 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.**\
* 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.\
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](#step-1-create-a-new-google-workspace-source-in-panther).
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](https://docs.panther.com/enrichment/google-workspace), to the right of **User Profiles**, click the toggle `ON`.
* Note the [prerequisites for enabling Google Workspace profiles](https://docs.panther.com/enrichment/google-workspace#prerequisites-for-google-workspace-user-profiles).
* 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.\
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**.
7. 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](https://docs.panther.com/detections/panther-managed/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.
{% endtab %}
{% endtabs %}
## Panther-managed detections
See [Panther-managed](https://docs.panther.com/detections/panther-managed) rules for Google Workspace in the [panther-analysis GitHub repository](https://github.com/panther-labs/panther-analysis/tree/master/rules) (in directories prefixed with `gsuite_`).
## Supported log types
Panther pulls data from Google's [Reports Activities API](https://developers.google.com/admin-sdk/reports/reference/rest/v1/activities) which includes admin activity, login activity, token activity, Google Drive activity, and more.
This data gets stored as both [`GSuite.ActivityEvent`](#gsuite.activityevent) and [`GSuite.Reports`](#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?](https://help.panther.com/articles/4763221133-what-is-the-difference-between-the-panther-log-types-gsuite-reports-and-gsuite-activityevent)
{% hint style="info" %}
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.
{% endhint %}
### 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.](https://developers.google.com/admin-sdk/reports/v1/reference/activities/list#response)
```yaml
fields:
- name: id
required: true
description: Unique identifier for each activity record.
type: object
fields:
- name: applicationName
description: Application name to which the event belongs.
type: string
- name: customerId
description: The unique identifier for a Google Workspace account.
type: string
- name: time
description: Time of occurrence of the activity.
type: timestamp
timeFormat: rfc3339
isEventTime: true
- name: uniqueQualifier
description: Unique qualifier if multiple events have the same time.
type: string
- name: actor
description: User doing the action.
type: object
fields:
- name: email
description: The primary email address of the actor. May be absent if there is no email address associated with the actor.
type: string
indicators:
- email
- name: profileId
description: The unique Google Workspace profile ID of the actor. May be absent if the actor is not a Google Workspace user.
type: string
- name: callerType
description: The type of actor.
type: string
- name: key
description: Only present when callerType is KEY. Can be the consumer_key of the requestor for OAuth 2LO API requests or an identifier for robot accounts.
type: string
- name: kind
required: true
description: The type of API resource. For an activity report, the value is reports#activities.
type: string
- name: ownerDomain
description: This is the domain that is affected by the report's event. For example domain of Admin console or the Drive application's document owner.
type: string
indicators:
- domain
- name: ipAddress
description: IP address of the user doing the action. This is the Internet Protocol (IP) address of the user when logging into Google Workspace which may or may not reflect the user's physical location. For example, the IP address can be the user's proxy server's address or a virtual private network (VPN) address. The API supports IPv4 and IPv6.
type: string
indicators:
- ip
- name: type
description: Type of event. The Google Workspace service or feature that an administrator changes is identified in the type property which identifies an event using the eventName property. For a full list of the API's type categories, see the list of event names for various applications above in applicationName.
type: string
- name: name
description: Name of the event. This is the specific name of the activity reported by the API. And each eventName is related to a specific Google Workspace service or feature which the API organizes into types of events.
type: string
- name: parameters
description: Parameter value pairs for various applications. For more information about eventName parameters, see the list of event names for various applications above in applicationName.
type: json
```
### GSuite.Reports
{% hint style="warning" %}
We recommend using [`GSuite.ActivityEvent`](#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.
{% endhint %}
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.](https://developers.google.com/admin-sdk/reports/v1/reference/activities/list#response)
schema: GSuite.Reports
description:
referenceURL: https://developers.google.com/admin-sdk/reports/v1/reference/activities/list#response
fields:
- name: id
required: true
description: Unique identifier for each activity record.
type: object
fields:
- name: applicationName
description: Application name to which the event belongs.
type: string
- name: customerId
description: The unique identifier for a Google Workspace account.
type: string
- name: time
description: Time of occurrence of the activity.
type: timestamp
timeFormat: rfc3339
isEventTime: true
- name: uniqueQualifier
description: Unique qualifier if multiple events have the same time.
type: string
- name: actor
description: User doing the action.
type: object
fields:
- name: email
description: The primary email address of the actor. May be absent if there is no email address associated with the actor.
type: string
indicators:
- email
- name: profileId
description: The unique Google Workspace profile ID of the actor. May be absent if the actor is not a Google Workspace user.
type: string
- name: callerType
description: The type of actor.
type: string
- name: key
description: Only present when callerType is KEY. Can be the consumer_key of the requestor for OAuth 2LO API requests or an identifier for robot accounts.
type: string
- name: kind
required: true
description: The type of API resource. For an activity report, the value is reports#activities.
type: string
- name: ownerDomain
description: This is the domain that is affected by the report's event. For example domain of Admin console or the Drive application's document owner.
type: string
indicators:
- domain
- name: ipAddress
description: IP address of the user doing the action. This is the Internet Protocol (IP) address of the user when logging into Google Workspace which may or may not reflect the user's physical location. For example, the IP address can be the user's proxy server's address or a virtual private network (VPN) address. The API supports IPv4 and IPv6.
type: string
indicators:
- ip
- name: events
description: Activity events in the report.
type: array
element:
type: object
fields:
- name: type
description: Type of event. The Google Workspace service or feature that an administrator changes is identified in the type property which identifies an event using the eventName property. For a full list of the API's type categories, see the list of event names for various applications above in applicationName.
type: string
- name: name
description: Name of the event. This is the specific name of the activity reported by the API. And each eventName is related to a specific Google Workspace service or feature which the API organizes into types of events.
type: string
- name: parameters
description: Parameter value pairs for various applications. For more information about eventName parameters, see the list of event names for various applications above in applicationName.
type: array
element:
type: object
fields:
- name: name
description: The name of the parameter.
type: string
- name: value
description: String value of the parameter.
type: string
- name: intValue
description: Integer value of the parameter.
type: bigint
- name: boolValue
description: Boolean value of the parameter.
type: boolean
- name: multiValue
description: String values of the parameter.
type: array
element:
type: string
- name: multiIntValue
description: Integer values of the parameter.
type: array
element:
type: bigint
- name: messageValue
description: 'Nested parameter value pairs associated with this parameter. Complex value type for a parameter are returned as a list of parameter values. For example, the address parameter may have a value as [{parameter: [{name: city, value: abc}]}]'
type: json
- name: multiMessageValue
description: List of messageValue objects.
type: array
element:
type: json
