Skip to content
Forestall

Domain-Wide Delegation

Copy page

This guide details how to authorize your Service Account to access Google Workspace data by setting up Domain-Wide Delegation (DwD). This process allows the service account to “impersonate” your Admin Email to read users, groups, devices, organizational units, admin roles and group settings.

Domain-Wide Delegation is required whether you prepared the service account with the Copy PS script or in the Google Cloud Console.

🔐 Prerequisites

Before starting, ensure you have:

  1. The Client ID: This is the numeric OAuth2 Client ID of your Service Account. The Copy PS script prints it at the end of its run (Client ID (DWD)). You can also find it in the client_id field of the JSON key file, or in the GCP Console under IAM & Admin > Service Accounts.
  2. Super Admin Access: You must be a Super Admin in the Google Admin Console.

Manage Domain Wide Delegation

Step 1: Navigate to API Controls

  1. Log in to the Google Admin Console.
  2. In the left-hand menu, navigate to Security > Access and data control > API controls.
  3. Scroll down to the Domain-wide delegation section at the bottom.
  4. Click MANAGE DOMAIN WIDE DELEGATION.

Step 2: Register the API Client

DWD Add New Button

  1. On the Domain-wide Delegation page, click the Add new button next to the “API clients” list.
  2. A dialog box will appear. Enter the following information:
    • Client ID: Paste the numeric Client ID for your Service Account.
    • OAuth Scopes: Copy and paste the following comma-separated list into the field:

Add a new Client ID and OAuth Scopes

https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/cloud-identity.devices.readonly,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/apps.groups.settings
  1. Click Authorize.

📋 Authorized Scopes Reference

Once authorized, your Service Account will be able to perform the following functions:

Scope Shown in the Forestall panel as Purpose
admin.directory.user.readonly AdminDirectoryUserReadonly Read user accounts.
admin.directory.group.readonly AdminDirectoryGroupReadonly Read groups and their memberships.
admin.directory.customer.readonly AdminDirectoryCustomerReadonly Read organization-level (customer) information.
cloud-identity.devices.readonly CloudIdentityDevicesReadonly Read managed devices.
admin.directory.orgunit.readonly AdminDirectoryOrgunitReadonly Read the organizational unit structure.
admin.directory.rolemanagement.readonly AdminDirectoryRolemanagementReadonly Read admin roles and their assignments.
apps.groups.settings AppsGroupsSettings Read group settings, such as who may join or post to a group.
admin.directory.user.security AdminDirectoryUserSecurity Read the third-party OAuth tokens users have granted.

The Test on the GCP Configuration page checks all eight scopes. Each one appears in the Required Permissions panel.

✅ Verification

  1. Check the list of API Clients to ensure your Client ID appears with the correct scopes.
  2. Return to the GCP Configuration page in Forestall.
  3. Enter the Admin Email (the person being impersonated) and click Test.
  4. If the test passes, every entry under Required Permissions turns green and the Service Account is authorized to “act as” the admin for these tasks.

Domain-Wide Delegation is extremely powerful. Grant only the scopes listed above and nothing more. All of them are read-only except admin.directory.user.security, which Forestall uses only to read OAuth tokens.

Was this page helpful?

Thank you for your feedback.