Join our Newsletter — 33% off our NHI Course
Home› Guides› Google Workspace Audit Log Detection Guide: Events, Retention…
Guide SOC & Detection Engineering

Google Workspace Audit Log Detection Guide: Events, Retention and Detection Rules

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 13 min read
On this page

Google Workspace records almost every security relevant action in its audit logs, but the logs are spread across dozens of applications, kept for only six months and delayed by minutes to hours, so most tenants have the data and still miss the attack. Account takeover, malicious OAuth grants, new admin roles, domain-wide delegation changes and mass Drive sharing all leave specific events in the Admin SDK Reports API. This guide is for detection engineers and Workspace administrators who need to know which log answers which question, what the exact event names are, how to get the data into a SIEM before it ages out, and which detections to build first. It complements the Google Workspace Security Guide, which covers configuration, and does not repeat it.

This is an independent guide from NHI Mgmt Group, based on Google Workspace's public documentation as of November 2026. It is not sponsored or reviewed by Google. Product features change, so confirm settings against Google's current documentation.

Key takeaways

  • Six months, then gone. Google states that Admin, login, Drive, Gmail, OAuth Token, SAML, Groups and Rules log events are retained for six months, and administrators cannot change that, so export is the only way to keep longer history.
  • Lag varies by log. Admin and login events arrive within minutes, but OAuth Token events can take up to a few hours and Groups up to a couple of hours, which shapes alert latency and incident timelines.
  • Start with four logs. login, admin, token and drive cover account takeover, privilege changes, OAuth abuse and data exfiltration.
  • OAuth grants are the NHI signal. The token log's authorize event shows which app, client ID and scopes a user granted, which is where consent phishing and risky integrations surface.
  • Domain-wide delegation changes are critical events. AUTHORIZE_API_CLIENT_ACCESS lets a service account act as any user for the listed scopes and deserves an immediate alert every time.

The log sources and what each answers

All Workspace audit data is exposed through the Admin SDK Reports API activities.list method, selected by applicationName. Google lists more than forty application names. The table shows the ones that matter most for detection.

applicationNameQuestion it answersTypical detections
loginWho signed in, how, and what Google flaggedSuspicious logins, 2SV disabled, recovery details changed, leaked password disables
adminWhat administrators changed in the Admin consoleAdmin role grants, security setting changes, API client access, SSO changes
tokenWhich third-party apps users authorised and revokedNew high-risk scopes, unknown client IDs, mass grants to one app
driveFile access, sharing and visibility changesExternal sharing bursts, public links, mass downloads
samlSign-ins to SAML apps through Google as identity providerAccess to sensitive apps after a suspicious login
user_accountsUser level account security changesPassword and 2SV changes by the user
groups, groups_enterpriseGroup membership and settingsExternal members added to privileged groups
gmailMessage activity (time range limited to 30 days per API request)Delivery of phishing to many users, forwarding
context_aware_accessAccess denials by context-aware access rulesRepeated denials from unmanaged devices
rules, mobile, chrome, gcpData protection rules, devices, browser, and Google Cloud activityDLP rule hits, device compromise, risky extensions

MITRE ATT&CK v20 names Google Workspace audit as a log source (for example gcp:workspaceaudit and saas:googleworkspace) for data components including User Account Authentication, Cloud Storage Access and Web Credential Usage, which is useful when you record coverage. See the Log Source Coverage Matrix Template.

Retention, lag and getting the data out

LogLag stated by GoogleRetention
AdminA few minutesSix months
LoginA few minutesSix months
User account eventsTens of minutesSix months
DriveA few minutesSix months
GmailA few minutesSix months
OAuth TokenUp to a few hoursSix months
SAMLA few minutesSix months
GroupsTens of minutes, possibly a couple of hoursSix months
RulesNear real timeSix months

Export options

  • Reports API polling: a collector calls activities.list for each application on a schedule. It works on every edition. The Gmail application requires both start and end time and a range of no more than 30 days, and a request without an end time returns at most the most recent 180 days. Poll with an overlap window to absorb lag, and de-duplicate on event ID.
  • BigQuery export: Google documents export of activity and usage data to BigQuery for Frontline Standard and Plus, Enterprise Standard and Plus, Education Standard and Plus, and Enterprise Essentials Plus. The export runs approximately daily, so it suits retention and hunting rather than real-time alerting.
  • Retention target: keep at least 12 months in the SIEM or warehouse. Breaches are often discovered months after initial access, and six months of native retention is not enough to scope them. See the SaaS Audit Log Retention and Licensing Guide.

Where identity fits: the collector and OAuth apps

The collector itself is a non-human identity with read access to every user's activity. Usually it is a Google Cloud service account using domain-wide delegation to impersonate an administrator, or an OAuth client authorised by an admin, with the scope https://www.googleapis.com/auth/admin.reports.audit.readonly.

  • Least privilege: grant only the read-only reports scope to the collector's client ID, impersonate a dedicated admin with a custom role limited to reports, and never reuse a broader integration.
  • Key handling: prefer workload identity federation or short-lived credentials over downloaded service account keys. See the Google Workspace Domain-Wide Delegation Security Guide.
  • Monitor the monitor: alert on any change to the collector's API client access entry and on the collector's own token activity from unexpected IPs.
  • Third-party apps: every OAuth grant a user makes appears in the token log. Grants are where non-human identities enter the tenant without a provisioning process. See the Consent Phishing and Illicit OAuth Grants Guide.

Event reference for detection

LogEvent nameWhy it matters
loginlogin_success, login_failure, login_challengeBaseline sign-ins; login_type shows google_password, saml, reauth; is_suspicious flags Google's view
loginsuspicious_login, suspicious_programmatic_login, suspicious_login_less_secure_appGoogle risk detection for the account
loginuser_signed_out_due_to_suspicious_session_cookiePossible session cookie theft
login2sv_disable, recovery_email_edit, recovery_phone_edit, passkey_removedAttacker persistence after takeover
loginemail_forwarding_out_of_domainMail forwarding to an external address
logingov_attack_warning, account_disabled_password_leak, account_disabled_hijackedHigh-severity Google warnings that should page the SOC
adminGRANT_ADMIN_PRIVILEGE, ASSIGN_ROLE, ADD_PRIVILEGE, CREATE_ROLENew administrators or broader roles
adminAUTHORIZE_API_CLIENT_ACCESS, REMOVE_API_CLIENT_ACCESSDomain-wide delegation granted or removed; parameters include client name and scopes
adminTOGGLE_SSO_ENABLEDIdentity provider trust changed
adminADD_TO_TRUSTED_OAUTH2_APPS, UNBLOCK_ALL_THIRD_PARTY_API_ACCESS, ADD_TO_CAA_EXEMPT_OAUTH2_APPSApp access controls loosened
adminCHANGE_TWO_STEP_VERIFICATION_ENROLLMENT_PERIOD_DURATION, CHANGE_ALLOWED_TWO_STEP_VERIFICATION_METHODS2SV enforcement weakened
adminGENERATE_2SV_SCRATCH_CODES, CHANGE_PASSWORD, CREATE_EMAIL_MONITOR, MAIL_ROUTING_DESTINATION_ADDEDAdmin actions that can hand an attacker an account or a copy of mail
tokenauthorize, revoke, deny, request, activityclient_id, app_name, client_type and scope identify the app and its reach
driveSharing and visibility change events; request_accessvisibility values such as public_on_the_web, people_with_link and shared_externally, with target_user

For Drive, filter on primary_event = true, because one user action can produce several events and only primary events represent the main action.

Detections to build first

DetectionLogicATT&CK
Account takeover chainsuspicious_login or a success from a new country, followed within 24 hours by 2sv_disable, recovery change or email_forwarding_out_of_domainT1078.004 Cloud Accounts, T1556.006 Multi-Factor Authentication, T1114.003 Email Forwarding Rule
Password sprayingMany login_failure events across many users from one IP or ASN, then a successT1110.003 Password Spraying
New super admin or privileged roleGRANT_ADMIN_PRIVILEGE or ASSIGN_ROLE outside a change ticket, or by an admin who signed in suspiciouslyT1098.003 Additional Cloud Roles
Domain-wide delegation grantedAny AUTHORIZE_API_CLIENT_ACCESS, with higher severity where API_SCOPES include Gmail, Drive or directory scopesT1098.001 Additional Cloud Credentials
Risky OAuth grantauthorize for a client ID not on the approved list, with mail, Drive, Chrome Web Store or admin scopes; or many users granting the same new app in a dayT1528 Steal Application Access Token, T1550.001 Application Access Token
Identity provider changeTOGGLE_SSO_ENABLED or changes to SSO profilesT1484.002 Trust Modification
Mass external sharingA user changes visibility to public_on_the_web or shares to an external domain on many files in an hourT1537 Transfer Data to Cloud Account, T1213 Data from Information Repositories
App controls loosenedUNBLOCK_ALL_THIRD_PARTY_API_ACCESS, ADD_TO_TRUSTED_OAUTH2_APPS or CAA exemption addedT1484 Domain or Tenant Policy Modification

Tune the account takeover chain on Google's own flags first, because they need no baseline. Write portable rules where possible: see the Sigma Rules Guide.

Triage: what to pull for each alert

Workspace alerts are only as good as the context gathered in the first 30 minutes. Build these pivots into the SIEM so an analyst does not have to query each application by hand.

Alert typePivot queriesDecision point
Suspicious loginAll login events for the user in 7 days; token grants since the login; saml app sign-ins; drive sharing changesAny persistence change (2SV, recovery, forwarding, new grant) means treat as confirmed takeover
Admin role grantActor's last sign-ins and is_suspicious flag; other admin events by the same actor in the session; change ticketNo ticket and an unusual actor means revoke the role, then investigate
Delegation grantClient name and API_SCOPES; which Google Cloud project owns the client ID; who requested itUnknown owner or mail and Drive scopes means remove the entry pending review
Risky OAuth grantEvery user who granted the same client_id; its activity events and num_response_bytes; scopesData access volume and scopes decide whether to block the app tenant wide
Mass sharingFile count, target_user domains, doc_type; the user's login contextSharing to personal domains after a suspicious login is exfiltration until shown otherwise

Containment actions that leave evidence

  • Accounts: reset the password, sign the user out of all sessions, revoke application specific passwords and review 2SV methods. Each action is itself logged in admin, which keeps the timeline complete.
  • Apps: revoke tokens for the client ID across users and add it to the blocked apps list. The resulting revoke events confirm the removal.
  • Delegation: remove the API client access entry and disable or rotate the service account's keys in Google Cloud, then check Google Cloud audit logs for use of the key. See the Google Cloud Audit Logs and Log Sinks Guide.
  • Preserve first: export the relevant events to the case record before any change, because native retention keeps rolling.

Rolling it out

  1. Create the collector identity with only the reports read-only scope, record its client ID, and add an alert on changes to it.
  2. Backfill the full six months available for login, admin, token and drive so baselines start with history.
  3. Enable alerting in stages: Google's high-severity warnings and admin role changes first (low noise), then OAuth grants against an approved app list, then Drive sharing rules.
  4. Pilot with the Workspace admin team for two weeks, tuning out sanctioned admin automation and known integrations by client ID.
  5. Add BigQuery export where the edition allows, for long-term retention and hunting, and reconcile daily counts against the API feed.
  6. Rollback: if a rule floods the queue, move it to a dashboard rather than deleting it, and keep collection running regardless.
  7. Test quarterly with authorised actions: grant a test app a scope, assign a test role, share a test file publicly, and confirm each alert fires within the expected lag.

Measuring it

  • Collection health: hours since the last event per application, with an alert when login or admin is silent for more than an hour during working time.
  • History depth: months of searchable Workspace history, target 12 or more.
  • Time to detect: median minutes from event time to alert for admin role and delegation events, measured in quarterly tests.
  • OAuth hygiene: number of authorised client IDs not on the approved list, trending down.
  • Precision: true positive rate per rule after tuning.

Framework mapping

FrameworkReferenceRelevance
NIST SP 800-53 Rev. 5AU-2, AU-6, AU-11, AU-12, SI-4Event selection, review, retention, generation and monitoring
NIST CSF 2.0DE.CM-01, DE.AE-02Monitoring and analysis
CIS Controls v8.1Control 8 Audit Log ManagementCentralised collection and at least 90 days of retention
ISO/IEC 27001:2022Annex A 8.15 Logging, 8.16 Monitoring activitiesLogging and monitoring of a cloud service

Common failure patterns

  • Relying on the Admin console only: the investigation tool is useful, but six months of retention and manual search mean history is lost before most investigations start.
  • Ignoring token lag: OAuth Token events can arrive hours late. Polling windows that do not overlap lose events, and timelines built in the first hour of an incident miss grants.
  • Treating every OAuth grant as user choice: one consent to a malicious app with Chrome Web Store publishing rights can be enough to ship a malicious extension update. An approved app list and an alert on high-impact scopes would have flagged the grant.
  • No alert on delegation: domain-wide delegation entries are rarely changed, so each new one should be reviewed. Many tenants find old entries for integrations nobody owns.
  • Counting every Drive event: one share produces several events, so volume thresholds built on all events fire constantly. Filter on primary_event and count distinct files and distinct external domains instead.
  • Over-scoped collector: using a general admin integration to read logs turns the SIEM connector into a path to the whole tenant.

Practitioner checklist

  • Collect login, admin, token, drive, saml and groups logs into the SIEM with overlapping poll windows.
  • Keep at least 12 months of Workspace audit history outside Google.
  • Run the collector with only the reports read-only scope and alert on changes to it.
  • Alert on every AUTHORIZE_API_CLIENT_ACCESS and every admin role grant.
  • Maintain an approved OAuth client ID list and alert on grants outside it with high-impact scopes.
  • Page on Google's high-severity login warnings such as gov_attack_warning and account_disabled_hijacked.
  • Correlate suspicious logins with 2SV, recovery and forwarding changes within 24 hours.
  • Detect bursts of public or external Drive sharing using primary events only.
  • Test the top detections quarterly and record time to alert against the lag Google states for each log.

Standards and references

Related NHI Mgmt Group resources: Google Workspace Security Guide · Google Workspace Domain-Wide Delegation Security Guide · OAuth Token Theft Incident Playbook · Microsoft 365 Unified Audit Log Guide for Detection

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.