Google Drive Domain-Wide Delegation (DWD)
Google Drive Domain-Wide Delegation (DWD)
Edition: Enterprise only
The Google Drive DWD integration scans files and comments across an entire Google Workspace domain by impersonating users via a service account, enabling org-wide scanning without individual user consent. For single-account scanning, see the Google Drive integration instead.
Prerequisites
Requirement | Detail |
|---|---|
Google Workspace plan | Business, Enterprise, Education, or Nonprofits. |
Google Workspace Admin | Super Admin access to the Admin Console. |
GCP project | Owner or Editor access to a Google Cloud Platform project. |
Configuration
DWD setup requires four phases in Google's consoles before TruffleHog can scan: create a GCP service account, enable Domain-Wide Delegation, generate a JSON key, and authorize the service account in Google Workspace. The TruffleHog configuration itself is the fifth and final step.
Step 1: Create a GCP service account
- In the Google Cloud Console, create or select a project.
- Navigate to APIs & Services > Library and enable the following APIs: API Purpose Google Drive API Access user Drive files. Admin SDK API List users in the domain. Required only when scanning all users.
- Navigate to IAM & Admin > Service Accounts and click + Create Service Account.
- Name the account (e.g., trufflehog-drive-scanner) and click Create and Continue. Skip optional permissions and click Done.
Step 2: Enable Domain-Wide Delegation on the service account
- Click the service account you just created.
- Click Advanced settings (or Show domain-wide delegation).
- Check Enable Google Workspace Domain-Wide Delegation and click Save.
- Copy the Client ID ā a numeric string like 123456789012345678901. You'll need it in Step 4.
Step 3: Create a JSON key
- In the service account details, go to the Keys tab.
- Click Add Key > Create new key, select JSON, and click Create.
- Save the downloaded file securely. Its contents go into the service_account_json field in the TruffleHog configuration.
If your organization has disabled service account key creation (the iam.disableServiceAccountKeyCreation policy), contact your GCP Organization Admin to request an exception.
Step 4: Authorize the service account in Google Workspace
- Go to the Google Admin Console and sign in with a Super Admin account.
- Navigate to Security > Access and data control > API controls.
- Click Manage Domain Wide Delegation, then Add new.
- Enter the Client ID from Step 2.
- Enter the following OAuth scopes (comma-separated, no spaces): https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly
- Click Authorize.
The admin.directory.user.readonly scope is only required when scanning all domain users. If you provide an explicit include_users list, only drive.readonly is needed.
Step 5: Configure TruffleHog
Local configuration supports three scoping variants depending on which users you want to scan:
- All domain users ā requires a Super Admin email to enumerate users via the Admin SDK.
- Specific users only ā provide an explicit list. No Super Admin needed.
- All users except specific users ā combine domain enumeration with an exclusion list.
All domain users
Specific users only
All users except specific users
Configuration options
Field | Type | Required | Description |
|---|---|---|---|
dwd.service_account_json | string | Yes | Full contents of the service account JSON key file. |
dwd.admin_email | string | Conditional | Super Admin email used to enumerate domain users via the Admin SDK. Required when include_users is not specified. |
dwd.include_users | list | No | Explicit list of user emails to scan. When set, admin_email is not required. |
dwd.exclude_users | list | No | User emails to skip when scanning all users. Ignored when include_users is set. |
Capabilities
Feature | Supported |
|---|---|
Org-wide scanning via impersonation | ā |
Scan file contents (Docs, Sheets, Slides, Drawings) | ā |
Scan file comments and replies | ā |
Scan files in My Drive and Shared Drives | ā |
Shared file deduplication | ā |
Skip suspended and archived users | ā |
Verification checklist
After setup, confirm:
Item | Where to Find It |
|---|---|
Service Account JSON key | Downloaded in Step 3. |
Client ID authorized in Workspace | Admin Console > Security > API Controls > Domain-Wide Delegation. |
OAuth scopes match exactly | drive.readonly and admin.directory.user.readonly. |
Admin email is a Super Admin | Admin Console > Directory > Users (check role). |
DWD enabled on service account | GCP Console > Service Account > Advanced settings. |
How DWD scanning works
- Initialization. The source validates the configuration (service account JSON, admin email).
- User enumeration. If include_users is provided, that list is used directly. Otherwise, the Admin SDK (impersonating admin_email) enumerates all domain users.
- Filtering. Suspended, archived, and excluded users are skipped automatically.
- Per-user scanning. For each user, TruffleHog creates an impersonated Drive service, lists files, and scans contents and comments. Errors on a single user don't stop the scan ā it continues to the next user.
User filtering
When scanning all users (no include_users), users are filtered automatically based on their state:
User state | Behavior |
|---|---|
Active | Scanned |
Suspended | Skipped |
Archived | Skipped |
In exclude_users | Skipped |
When using include_users, the list is used as-is. If a user in the list is suspended, archived, or invalid, the impersonation fails, the error is logged, and scanning continues with the next user.
Shared file deduplication
When scanning multiple users, files shared between users are deduplicated automatically:
File type | Detection | Behavior |
|---|---|---|
Files shared from My Drive | file.Shared == true | Scanned once, skipped for subsequent users. |
Files in Shared Drives | file.DriveId != "" | Scanned once, skipped for subsequent users. |
Private files | Neither condition | Scanned (appears only for one user). |
Google file type exports
Google-native file types are exported before scanning:
Google file type | Exported as |
|---|---|
Google Docs | Plain text |
Google Sheets | CSV |
Google Slides | Plain text |
Google Drawings |
Notes
- Files larger than 10 MB are skipped. Empty files are also skipped.
- Google Groups, service accounts, and external users cannot be scanned. Groups don't have Drive storage, service accounts aren't in the Workspace user directory, and external users can't be impersonated.
Troubleshooting
Error | Cause | Solution |
|---|---|---|
unauthorized_client | DWD scopes not authorized in Workspace Admin. | Verify Client ID and scopes in Admin Console > API Controls > Domain-Wide Delegation. |
Not authorized to access this resource | Admin email is not a Super Admin. | Use a Super Admin email for admin_email. |
Invalid subject / User not found | Impersonating a non-existent user, group, or external email. | Verify the email is a valid user in the domain. |
User is suspended | Impersonating a suspended user. | Remove from include_users; auto-filtered when scanning all users. |
Service account key creation is disabled | Organization policy blocks key creation. | Contact your GCP Org Admin for an exception. |
Admin SDK API has not been enabled | API not enabled in GCP. | Enable Admin SDK API in GCP Console. |
Security and data handling
- Read-only access. The scanner only requires drive.readonly. It cannot modify, delete, or create content in Google Drive.
- No data persistence. All file content is downloaded and scanned in memory. No document content is stored by TruffleHog.
- Least-privilege scopes. Only drive.readonly and admin.directory.user.readonly are requested.
- Credential redaction. Service account JSON keys are automatically redacted from log output.
- Audit trail. Google Workspace audit logs show impersonation events from the service account.