Google Workspace Incident Response: Admin SDK, Vault, and OAuth Token Forensics

Cybersecurity

A working Workspace IR runbook covering Admin SDK audit logs, Vault legal holds, OAuth token review, Drive sharing audits, Gmail filter inspection, login challenges, and the recovery sequence.

By Arjun Raghavan, Security & Systems Lead, BIPI · June 8, 2024 · 8 min read

Google Workspace incidents look like M365 incidents from a distance and diverge sharply up close. The Admin Console gives you a starting view, but real IR happens against the Admin SDK Reports API and BigQuery exports if you have them enabled.

1. Reports API as the source of truth

The Reports API has applications like login, admin, drive, token, user_accounts, and saml. Each application is its own audit stream. The login stream catches password reset, suspicious login, 2-step verification disabled. The token stream catches OAuth authorization, scope grants, and revocations.

GET https://admin.googleapis.com/admin/reports/v1/activity/users/alex@contoso.com/applications/token?startTime=2024-05-25T00:00:00Z

If you have the Workspace logs export to BigQuery turned on (Enterprise plans), query the activity dataset directly. It is the same data with a better query surface and longer retention.

2. OAuth token review

OAuth abuse against Workspace is common. The token stream shows each authorization event. Filter to authorize events with scopes that include mail.google.com or drive (not just drive.file). Cross-reference with the app's client ID in the Admin Console's API Access screen to confirm whether the app is trusted, blocked, or unreviewed.

From the Admin Console you can revoke an app for a single user or block it tenant-wide. For incidents, block tenant-wide. The 'trusted apps' allowlist is also where attackers persist if they convince an admin to add their app.

3. Gmail filter and forwarding audit

Gmail filters are the inbox-rule equivalent. The Admin SDK exposes user settings via the Gmail API. Filters that forward, archive, or delete are the red flags.

GET https://gmail.googleapis.com/gmail/v1/users/alex@contoso.com/settings/filters and GET .../settings/forwardingAddresses

Look for any forwardingAddress not pre-approved by your domain forwarding policy. The presence of a forwardingAddress alone is not abuse; the verification email goes to the destination, so attackers often complete the loop through the compromised inbox.

4. Drive sharing exposure scope

Drive is where data lives. The drive activity stream logs view, edit, download, and shared events. During an incident, the shared-externally events in the compromise window define your exposure.

• Filter activity to event_name in ('change_user_access','change_acl_editors','create_link_share').
• For each affected file, pull current permissions via the Drive API and revoke external access.
• Use the Drive audit log's source_copy_id to detect files copied to external Drive accounts, which is harder to remediate.

5. Login challenge logs and account takeover

The login stream has events like login_success, login_failure, login_challenge, and suspicious_login. A pattern of login_challenge followed by login_success from a new geography within minutes is classic adversary-in-the-middle. Cross-check with 2sv_disable events: if 2SV was disabled, that is a critical step in the attacker's persistence.

Containment is straightforward but the order matters. Use the Admin Console superadmin actions or call the Directory API.

1. Suspend the user: POST /admin/directory/v1/users/{userKey} with suspended=true. The user cannot sign in but data remains accessible to admins.
2. Sign the user out of all sessions: POST /admin/directory/v1/users/{userKey}/signOut
3. Reset password forcing change at next login.
4. Reset 2-step verification backup codes and re-enroll security keys.
5. Audit and remove malicious OAuth tokens, Gmail filters, forwarding addresses, and external Drive shares.

6. Vault for evidence preservation

Before you let HR or IT delete anything, put a Vault hold on the user's mail, Drive, Chat, and Meet. Holds preserve content even if the user later deletes or the account is removed. Each hold is tied to a matter; matters can stay open for the duration of the investigation and any subsequent legal action.

Workspace IR is fast when the Reports API queries are pre-written, Vault matters are templated, and the on-call has tenant-wide OAuth blocklist permission. Build those before the first incident, not during.

Read more field notes, explore our services, or get in touch at info@bipi.in. Privacy Policy · Terms.