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,tokenanddrivecover account takeover, privilege changes, OAuth abuse and data exfiltration. - OAuth grants are the NHI signal. The
tokenlog'sauthorizeevent 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_ACCESSlets 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.
| applicationName | Question it answers | Typical detections |
|---|---|---|
login | Who signed in, how, and what Google flagged | Suspicious logins, 2SV disabled, recovery details changed, leaked password disables |
admin | What administrators changed in the Admin console | Admin role grants, security setting changes, API client access, SSO changes |
token | Which third-party apps users authorised and revoked | New high-risk scopes, unknown client IDs, mass grants to one app |
drive | File access, sharing and visibility changes | External sharing bursts, public links, mass downloads |
saml | Sign-ins to SAML apps through Google as identity provider | Access to sensitive apps after a suspicious login |
user_accounts | User level account security changes | Password and 2SV changes by the user |
groups, groups_enterprise | Group membership and settings | External members added to privileged groups |
gmail | Message activity (time range limited to 30 days per API request) | Delivery of phishing to many users, forwarding |
context_aware_access | Access denials by context-aware access rules | Repeated denials from unmanaged devices |
rules, mobile, chrome, gcp | Data protection rules, devices, browser, and Google Cloud activity | DLP 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
| Log | Lag stated by Google | Retention |
|---|---|---|
| Admin | A few minutes | Six months |
| Login | A few minutes | Six months |
| User account events | Tens of minutes | Six months |
| Drive | A few minutes | Six months |
| Gmail | A few minutes | Six months |
| OAuth Token | Up to a few hours | Six months |
| SAML | A few minutes | Six months |
| Groups | Tens of minutes, possibly a couple of hours | Six months |
| Rules | Near real time | Six months |
Export options
- Reports API polling: a collector calls
activities.listfor 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
tokenlog. 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
| Log | Event name | Why it matters |
|---|---|---|
| login | login_success, login_failure, login_challenge | Baseline sign-ins; login_type shows google_password, saml, reauth; is_suspicious flags Google's view |
| login | suspicious_login, suspicious_programmatic_login, suspicious_login_less_secure_app | Google risk detection for the account |
| login | user_signed_out_due_to_suspicious_session_cookie | Possible session cookie theft |
| login | 2sv_disable, recovery_email_edit, recovery_phone_edit, passkey_removed | Attacker persistence after takeover |
| login | email_forwarding_out_of_domain | Mail forwarding to an external address |
| login | gov_attack_warning, account_disabled_password_leak, account_disabled_hijacked | High-severity Google warnings that should page the SOC |
| admin | GRANT_ADMIN_PRIVILEGE, ASSIGN_ROLE, ADD_PRIVILEGE, CREATE_ROLE | New administrators or broader roles |
| admin | AUTHORIZE_API_CLIENT_ACCESS, REMOVE_API_CLIENT_ACCESS | Domain-wide delegation granted or removed; parameters include client name and scopes |
| admin | TOGGLE_SSO_ENABLED | Identity provider trust changed |
| admin | ADD_TO_TRUSTED_OAUTH2_APPS, UNBLOCK_ALL_THIRD_PARTY_API_ACCESS, ADD_TO_CAA_EXEMPT_OAUTH2_APPS | App access controls loosened |
| admin | CHANGE_TWO_STEP_VERIFICATION_ENROLLMENT_PERIOD_DURATION, CHANGE_ALLOWED_TWO_STEP_VERIFICATION_METHODS | 2SV enforcement weakened |
| admin | GENERATE_2SV_SCRATCH_CODES, CHANGE_PASSWORD, CREATE_EMAIL_MONITOR, MAIL_ROUTING_DESTINATION_ADDED | Admin actions that can hand an attacker an account or a copy of mail |
| token | authorize, revoke, deny, request, activity | client_id, app_name, client_type and scope identify the app and its reach |
| drive | Sharing and visibility change events; request_access | visibility 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
| Detection | Logic | ATT&CK |
|---|---|---|
| Account takeover chain | suspicious_login or a success from a new country, followed within 24 hours by 2sv_disable, recovery change or email_forwarding_out_of_domain | T1078.004 Cloud Accounts, T1556.006 Multi-Factor Authentication, T1114.003 Email Forwarding Rule |
| Password spraying | Many login_failure events across many users from one IP or ASN, then a success | T1110.003 Password Spraying |
| New super admin or privileged role | GRANT_ADMIN_PRIVILEGE or ASSIGN_ROLE outside a change ticket, or by an admin who signed in suspiciously | T1098.003 Additional Cloud Roles |
| Domain-wide delegation granted | Any AUTHORIZE_API_CLIENT_ACCESS, with higher severity where API_SCOPES include Gmail, Drive or directory scopes | T1098.001 Additional Cloud Credentials |
| Risky OAuth grant | authorize 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 day | T1528 Steal Application Access Token, T1550.001 Application Access Token |
| Identity provider change | TOGGLE_SSO_ENABLED or changes to SSO profiles | T1484.002 Trust Modification |
| Mass external sharing | A user changes visibility to public_on_the_web or shares to an external domain on many files in an hour | T1537 Transfer Data to Cloud Account, T1213 Data from Information Repositories |
| App controls loosened | UNBLOCK_ALL_THIRD_PARTY_API_ACCESS, ADD_TO_TRUSTED_OAUTH2_APPS or CAA exemption added | T1484 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 type | Pivot queries | Decision point |
|---|---|---|
| Suspicious login | All login events for the user in 7 days; token grants since the login; saml app sign-ins; drive sharing changes | Any persistence change (2SV, recovery, forwarding, new grant) means treat as confirmed takeover |
| Admin role grant | Actor's last sign-ins and is_suspicious flag; other admin events by the same actor in the session; change ticket | No ticket and an unusual actor means revoke the role, then investigate |
| Delegation grant | Client name and API_SCOPES; which Google Cloud project owns the client ID; who requested it | Unknown owner or mail and Drive scopes means remove the entry pending review |
| Risky OAuth grant | Every user who granted the same client_id; its activity events and num_response_bytes; scopes | Data access volume and scopes decide whether to block the app tenant wide |
| Mass sharing | File count, target_user domains, doc_type; the user's login context | Sharing 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
revokeevents 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
- Create the collector identity with only the reports read-only scope, record its client ID, and add an alert on changes to it.
- Backfill the full six months available for login, admin, token and drive so baselines start with history.
- 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.
- Pilot with the Workspace admin team for two weeks, tuning out sanctioned admin automation and known integrations by client ID.
- Add BigQuery export where the edition allows, for long-term retention and hunting, and reconcile daily counts against the API feed.
- Rollback: if a rule floods the queue, move it to a dashboard rather than deleting it, and keep collection running regardless.
- 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
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | AU-2, AU-6, AU-11, AU-12, SI-4 | Event selection, review, retention, generation and monitoring |
| NIST CSF 2.0 | DE.CM-01, DE.AE-02 | Monitoring and analysis |
| CIS Controls v8.1 | Control 8 Audit Log Management | Centralised collection and at least 90 days of retention |
| ISO/IEC 27001:2022 | Annex A 8.15 Logging, 8.16 Monitoring activities | Logging 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_eventand 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_ACCESSand 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_warningandaccount_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
- Google for Developers: Admin SDK Reports API, Activities: list
- Google for Developers: Login Audit Activity Events
- Google for Developers: OAuth Token Audit Activity Events
- Google for Developers: Admin Domain Settings Events
- Google for Developers: Admin Security Settings Events
- Google Workspace Admin Help: Data retention and lag times
- Google Workspace Admin Help: About reporting logs and BigQuery
- MITRE ATT&CK: Cloud Accounts
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