Setup guide

Page every user to read isAdmin, isDelegatedAdmin, isEnrolledIn2Sv, isEnforcedIn2Sv, suspended, lastLoginTime and orgUnitPath.

↳ This is already the read-only variant; do not authorise admin.directory.user, which permits creating and deleting users.

Call users.tokens.list to enumerate the third-party OAuth clients each user has actually granted, and the scopes they hold.

↳ No read-only variant exists - this scope also permits revoking tokens and application-specific passwords. If the tenant refuses it, drop it and derive app grants from the token audit log instead, at the cost of missing grants older than the lookback window.

List admin roles and role assignments so privilege can be joined to identities.

↳ Already read-only; admin.directory.rolemanagement would allow creating and assigning roles.

List verified domains so the audit can tell internal sharing from external sharing.

Resolve org unit paths and IDs when the audit is scoped to a sub-tree rather than the whole customer.

↳ Optional - omit if you always audit the entire customer.

Read the login, token, drive and admin audit logs via Reports activities.list.

↳ This is the only audit-log scope; it cannot be narrowed to a single application.

Pull the per-user usage report (accounts:is_2sv_enrolled, accounts:is_super_admin) to cross-check Directory counts.

↳ Optional - skip if you trust the Directory enumeration and do not need the reconciliation step.

With useDomainAdminAccess=true, list shared drives and their permissions to find files exposed to anyone or to an external domain.

↳ Broad and restricted by Google - it grants read access to every file in the tenant. Only authorise it when the operator asks for files-depth Drive analysis; the audit-log-only pass needs just admin.reports.audit.readonly.

List Alert Center alerts (government-backed attack warnings, suspicious login alerts, leaked password alerts) to corroborate audit-log findings.

↳ Optional - omit if the tenant does not use Alert Center.

Cause: The service account's numeric Client ID is not registered under Domain-wide delegation, or the scope string you requested is not byte-for-byte present in the authorised list. Google matches scopes exactly - authorising admin.directory.user does not cover a request for admin.directory.user.readonly.

Fix: Admin console > Security > Access and data control > API controls > Manage Domain Wide Delegation. Confirm the Client ID matches the service account's Unique ID, then edit the entry so its scope list contains every scope your code requests, character for character. Wait a few minutes and retry.

Cause: The delegation is configured but GOOGLE_WORKSPACE_ADMIN_SUBJECT is not a super admin, is suspended, is unlicensed, or does not hold the privilege behind the endpoint you called (for example roleAssignments requires role management privileges).

Fix: Point the subject at an active super admin listed under Admin console > Account > Admin roles > Super Admin > Admins. Do not impersonate the service account itself - it has no Workspace identity.

Cause: The access token was minted with a narrower scope list than the endpoint requires - typically calling users.tokens.list without admin.directory.user.security, or Reports without admin.reports.audit.readonly.

Fix: Add the missing scope both to the SCOPES list in your code and to the domain-wide delegation entry, then mint a fresh token; cached credentials keep the old scope set.

Cause: GOOGLE_WORKSPACE_ADMIN_SUBJECT does not resolve to a real user in the tenant - usually a typo, a wrong domain, an alias that is not the primary address, or a deleted account.

Fix: Use the account's primary email exactly as shown in Admin console > Directory > Users. Aliases and secondary-domain addresses are unreliable for impersonation.

Cause: The API is not enabled in the Google Cloud project that owns the service account key.

Fix: Open the link in the error body, or go to APIs & Services > Library in that exact project, and enable Admin SDK API (plus Google Drive API and Google Workspace Alert Center API if used). Allow a minute for propagation.

Cause: Per-user token enumeration or unpaged Reports queries are firing thousands of serialised calls against the Admin SDK's per-minute quota.

Fix: Back off exponentially on 429 and 503, cap concurrency, scope the run to an org unit, and sample users rather than sweeping all of them on tenants above a few thousand seats.

Cause: Not an error - the Drive audit log is unavailable on the tenant's licence tier (Business Starter) or the requested window predates data retention, so the Reports API returns an empty page.

Fix: Confirm the tenant is Business Standard or above before promising Drive coverage, and record the absence as an explicit coverage gap rather than reporting zero external sharing.