Setup guide

Enumerate and inspect users in the tenant (directory.users.list / users.get) to build inventories and verify the credential chain.

↳ Use this readonly scope instead of https://www.googleapis.com/auth/admin.directory.user, which also permits create, update, suspend and delete.

List groups and their settings for access-review and membership-mapping tasks.

↳ Drop entirely if the task never touches groups; use admin.directory.group only when writes are required.

Read group memberships (members.list) to resolve who is in which group.

↳ This is the narrowest scope that satisfies members.list; admin.directory.group.readonly also works but additionally exposes group metadata, so grant this one alone when only memberships are needed.

Read the org unit tree so users can be attributed to the correct OU.

↳ Omit unless OU structure is actually needed; user records already carry orgUnitPath.

List admin roles and role assignments to identify privileged accounts during a review.

↳ Highly sensitive; grant only for privilege-audit work and never pair it with the writable admin.directory.rolemanagement scope.

Pull login, admin, drive and token audit activity from the Reports API.

↳ For aggregate counts only, https://www.googleapis.com/auth/admin.reports.usage.readonly exposes far less per-event detail.

Enumerate and read files as the impersonated user when the task inspects Drive content.

↳ Prefer https://www.googleapis.com/auth/drive.metadata.readonly when only file names, owners and sharing state are needed - it never exposes file contents.

List and read messages in an impersonated mailbox for e-discovery or migration checks.

↳ Use https://www.googleapis.com/auth/gmail.metadata for headers and labels without message bodies; never request https://mail.google.com/ unless full IMAP-equivalent access is genuinely required.

Read calendars and events for the impersonated user (events.list).

↳ https://www.googleapis.com/auth/calendar.events.readonly is narrower when only event data, not calendar metadata, is needed.

Read Cloud Identity groups and memberships, including dynamic and security groups the Directory API does not fully expose.

↳ Skip unless Cloud Identity group semantics are required; the Directory API covers ordinary Workspace groups.

Lets the runtime principal call signJwt on the service account so a delegated token can be minted without ever creating a downloadable private key.

↳ Grant on the individual service account resource, not at project level, and only to the specific runtime principal.

Enable admin.googleapis.com and the other Workspace APIs on the Cloud project.

↳ Needed only during setup by the human operator; revoke afterwards. Never grant it to the Workspace service account itself.

Create the service account and, in keyed mode, manage its keys.

↳ Setup-time only for the human operator; roles/iam.serviceAccountKeyAdmin alone suffices if the account already exists.

Cause: The service account's numeric OAuth client ID has not been authorized in the Admin console, the wrong value (usually the service account email or key ID) was pasted into the Client ID field, or the grant is still pending Multi-party approval.

Fix: Re-copy uniqueId with `gcloud iam service-accounts describe SA_EMAIL --format='value(uniqueId)'` and add it at https://admin.google.com/ac/owl/domainwidedelegation. If a wrong client ID was saved, delete the row and re-add it - the client ID field cannot be edited. Wait up to 24 hours (usually under 5 minutes) for propagation.

Cause: The client ID is authorized but one or more of the scopes in the token request are absent from the Admin console grant.

Fix: Open Manage Domain Wide Delegation > the client row > View details, compare against the scopes your code requests, then EDIT and add the missing ones. The two lists must match byte-for-byte, including the https:// prefix.

Cause: Delegation is configured, but the impersonated subject is not a Workspace administrator with the privilege the Admin SDK call needs.

Fix: Assign the subject an admin role in Admin console > Account > Admin roles (for example User Management Admin for directory reads), or impersonate an account that already holds one. Re-mint the token afterwards - existing tokens do not pick up new privileges.

Cause: The sub / with_subject value is not a real active user in the tenant - it is suspended, deleted, in a different domain, or has never signed in and accepted the Terms of Service.

Fix: Verify the address in Admin console > Directory > Users, confirm status is Active, and have the account sign in once. Do not use a group address or an alias as the subject.

Cause: Clock skew on the signing host, or an exp claim more than 3600 seconds after iat.

Fix: Sync the host clock with NTP and set exp = iat + 3600 at most. Prefer the google-auth library or signJwt over hand-built JWTs so the claims are generated correctly.

Cause: admin.googleapis.com is not enabled on the Cloud project that owns the service account, or enablement has not propagated yet.

Fix: Run `gcloud services enable admin.googleapis.com --project=PROJECT_ID`, confirm with `gcloud services list --enabled`, wait 1-2 minutes, and retry. Check you are looking at the project that owns the service account, not the one your CLI defaults to.

Cause: The access token was issued with fewer scopes than the call requires - typically because a scope was added in code but never added to the Admin console grant, so the token silently came back reduced.

Fix: Call https://oauth2.googleapis.com/tokeninfo?access_token=... and diff the returned scope string against what you requested. Add any missing scope to the Admin console grant, then mint a fresh token.

Cause: The organization enforces the constraints/iam.disableServiceAccountKeyCreation org policy.

Fix: Do not request a policy exception. Switch to the keyless path: enable iamcredentials.googleapis.com, grant the runtime principal roles/iam.serviceAccountTokenCreator on the service account, and mint tokens via projects.serviceAccounts.signJwt.

Cause: customer=my_customer was used while impersonating a subject outside the tenant you meant to query, or a literal customer ID was mistyped.

Fix: Read the real customer ID from Admin console > Account > Account settings > Profile > Customer ID and pass it explicitly, and confirm the subject belongs to that tenant.

Cause: Admin SDK per-user and per-project QPS limits were exceeded, commonly by unthrottled parallel enumeration across many impersonated subjects.

Fix: Add exponential backoff with jitter, cap maxResults at 500, reuse tokens for their full hour, and spread work across subjects rather than hammering one. Request a quota increase in APIs & Services > Admin SDK API > Quotas if sustained volume is genuinely needed.