Google Workspace Audit Logs

Google Workspace Audit Logs track user activity and administrative actions within Google Workspace services such as Gmail, Google Drive, and Google Meet. These logs capture details like login attempts, file access, sharing actions, and configuration changes. They are essential for monitoring user behavior, auditing data access, investigating security incidents, and ensuring compliance with organizational policies and regulations.

Connecting Google Workspace requires a Google Workspace administrator who can:

Create a GCP project and service account
Perform domain-wide delegation in the Google Admin Console

Important: While the source tile will display as "Google Workspace" in the RunReveal dashboard, the logs will show the sourceType as gsuite and will be stored in the gsuite_logs table in the log explorer. This naming convention is maintained for backward compatibility.

Setup

Set up a Google Cloud project and service account

Go to the Google Cloud Console.
Create a new project or select an existing one.
Navigate to APIs & Services > Dashboard.
Click + ENABLE APIS AND SERVICES, search for Admin SDK API, and enable it.
Go to Credentials > + CREATE CREDENTIALS > Service account and create a service account (for example, runreveal-workspace-logs).
Open the service account details and copy its Client ID (numeric). You need this for domain-wide delegation.

Grant domain-wide delegation in Google Admin Console

Domain-wide delegation is required for both authentication methods below. Workload Identity Federation does not replace this step.

Go to the Google Admin Console.
Navigate to Security > Access and data control > API controls (older consoles: Security > API controls).
Under Domain-wide delegation, click Manage Domain Wide Delegation.
Click Add new and enter the service account Client ID.
In the OAuth Scopes field, enter:
https://www.googleapis.com/auth/admin.reports.audit.readonly
Click Authorize.

Authenticate RunReveal to the service account

RunReveal can authenticate as your service account with either a JSON service account key or Workload Identity Federation with AWS (no long-lived private key stored in RunReveal).

If you already configured WIF for GCS or GCP Pub/Sub Queue, you can reuse the same pool and provider—grant access to this Workspace service account and download a config for it.

Service account keys

Open the service account in GCP → Keys → Add Key → Create new key → JSON.
Download the key file. You will paste or upload it in RunReveal (type will be service_account).

Add the Google Workspace source to RunReveal

In the RunReveal dashboard, select Google Workspace on the sources page.

Give your source a name.
Set Subject to a Google Workspace administrator email in your domain (the account the service account impersonates). This is required for both auth methods.
Choose a GCP Auth Method:

Service account key

Select Service account key, then paste the service account JSON into Credential or upload the file.

Workload Identity Federation with AWS

Select Workload Identity Federation with AWS, then:

Role based auth — paste your IAM role ARN, or leave blank to use the RunReveal-provided role (arn:aws:iam::253602268883:role/runreveal_identity_federation).
External ID — must match the sts:ExternalId condition on your role trust policy (if you set one).
Identity Provider Config — paste or upload the WIF client config downloaded from GCP (type: external_account), not a service account private key.

Click Verify Settings and Connect to save your new source.

Troubleshooting

Symptom	What to check
Auth / token errors on verify or poll	Credential JSON type matches the auth method (`service_account` vs `external_account`); Subject is a Workspace admin
`unauthorized_client` / insufficient scopes	Domain-wide delegation Client ID matches the service account; scope is exactly `https://www.googleapis.com/auth/admin.reports.audit.readonly`
WIF assume-role failures	External ID matches AWS trust; attribute value uses assumed-role ARN form, not the bare `arn:aws:iam::…:role/…` ARN
Admin SDK not enabled	Enable Admin SDK API on the GCP project that owns the service account

Verify It's Working

Once added the source logs should begin flowing within a minute.

You can validate we are receiving your logs by running the following SQL query.

SELECT * FROM runreveal.logs WHERE sourceType = 'gsuite' LIMIT 1

Schema

The following columns are exposed for this source. RunReveal applies schema normalization across all sources, ensuring uniform field names and data types for cross-source queries and reusable detection logic.

Table: google_workspace_logs (46 columns)

Column	Type
`workspaceID`	String
`sourceID`	String
`sourceType`	LowCardinality(String)
`sourceTTL`	UInt32
`receivedAt`	DateTime
`id`	String
`eventTime`	DateTime
`eventName`	String
`eventID`	String
`srcIP`	String
`srcASCountryCode`	String
`srcASNumber`	UInt32
`srcASOrganization`	String
`srcCity`	String
`srcConnectionType`	String
`srcISP`	String
`srcLatitude`	Float64
`srcLongitude`	Float64
`srcUserType`	String
`dstIP`	String
`dstASCountryCode`	String
`dstASNumber`	UInt32
`dstASOrganization`	String

Column	Type
`dstCity`	String
`dstConnectionType`	String
`dstISP`	String
`dstLatitude`	Float64
`dstLongitude`	Float64
`dstUserType`	String
`actor`	Map(String, String)
`tags`	Map(String, String)
`resources`	Array(String)
`serviceName`	String
`readOnly`	Bool
`rawLog`	String
`ownerDomain`	String
`kind`	String
`id.applicationName`	String
`id.customerID`	String
`id.uniqueQualifier`	String
`actor.email`	String
`actor.profileID`	String
`actor.callerType`	String
`actor.key`	String
`events`	Array(String)
`etag`	String

Table: gsuite_logs (46 columns)

Column	Type
`workspaceID`	String
`sourceID`	String
`sourceType`	LowCardinality(String)
`sourceTTL`	UInt32
`receivedAt`	DateTime
`id`	String
`eventTime`	DateTime
`eventName`	String
`eventID`	String
`srcIP`	String
`srcASCountryCode`	String
`srcASNumber`	UInt32
`srcASOrganization`	String
`srcCity`	String
`srcConnectionType`	String
`srcISP`	String
`srcLatitude`	Float64
`srcLongitude`	Float64
`srcUserType`	String
`dstIP`	String
`dstASCountryCode`	String
`dstASNumber`	UInt32
`dstASOrganization`	String

Column	Type
`dstCity`	String
`dstConnectionType`	String
`dstISP`	String
`dstLatitude`	Float64
`dstLongitude`	Float64
`dstUserType`	String
`actor`	Map(String, String)
`tags`	Map(String, String)
`resources`	Array(String)
`serviceName`	String
`readOnly`	Bool
`rawLog`	String
`ownerDomain`	String
`kind`	String
`id.applicationName`	String
`id.customerID`	String
`id.uniqueQualifier`	String
`actor.email`	String
`actor.profileID`	String
`actor.callerType`	String
`actor.key`	String
`events`	Array(String)
`etag`	String

On this page