Skip to main content
Prowler for Google Workspace uses a Service Account with Domain-Wide Delegation to authenticate to the Google Workspace Admin SDK. This allows Prowler to read directory data on behalf of a super administrator without requiring an interactive login.

​
Required OAuth Scopes

Prowler requests the following read-only OAuth 2.0 scopes from the Google Workspace Admin SDK:
ScopeDescription
https://www.googleapis.com/auth/admin.directory.user.readonlyRead access to user accounts and their admin status
https://www.googleapis.com/auth/admin.directory.domain.readonlyRead access to domain information
https://www.googleapis.com/auth/admin.directory.customer.readonlyRead access to customer information (Customer ID)
The delegated user must be a super administrator in your Google Workspace organization. Using a non-admin account will result in permission errors when accessing the Admin SDK.

​
Setup Steps

​
Step 1: Create a GCP Project (if needed)

If you don’t have a GCP project, create one at https://console.cloud.google.com. The project is only used to host the Service Account — it does not need to have any Google Workspace data in it.

​
Step 2: Enable the Admin SDK API

  1. Go to the Google Cloud Console
  2. Select your project
  3. Navigate to APIs & Services → Library
  4. Search for Admin SDK API
  5. Click Enable

​
Step 3: Create a Service Account

  1. In the Google Cloud Console, navigate to IAM & Admin → Service Accounts
  2. Click Create Service Account
  3. Give it a descriptive name (e.g., prowler-googleworkspace-reader)
  4. Click Create and Continue
  5. Skip the optional role and user access steps — click Done
The Service Account does not need any GCP IAM roles. Its access to Google Workspace is granted entirely through Domain-Wide Delegation in the next steps.

​
Step 4: Generate a JSON Key

  1. Click on the Service Account you just created
  2. Go to the Keys tab
  3. Click Add Key → Create new key
  4. Select JSON format
  5. Click Create — the key file will download automatically
  6. Store it securely (e.g., ~/.config/prowler/googleworkspace-sa.json)
This JSON key grants access to your Google Workspace organization. Never commit it to version control, share it in plain text, or store it in an insecure location.

​
Step 5: Configure Domain-Wide Delegation in Google Workspace

  1. Go to the Google Workspace Admin Console
  2. Navigate to Security → Access and data control → API controls
  3. Click Manage Domain Wide Delegation
  4. Click Add new
  5. Enter the Client ID of the Service Account (found in the JSON key as client_id, or on the Service Account details page)
  6. In the OAuth scopes field, enter the following scopes as a comma-separated list:
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly
  1. Click Authorize
Domain-Wide Delegation must be configured by a Google Workspace super administrator. It may take a few minutes to propagate after saving.

​
Step 6: Store Credentials Securely

Set your credentials as environment variables: 
export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/googleworkspace-sa.json"
export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
Alternatively, if you need to pass credentials as a string (e.g., in CI/CD pipelines): 
export GOOGLEWORKSPACE_CREDENTIALS_CONTENT=$(cat /path/to/googleworkspace-sa.json)
export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"

​
Credential Lookup Order

Prowler resolves credentials in the following order:
  1. GOOGLEWORKSPACE_CREDENTIALS_FILE environment variable
  2. GOOGLEWORKSPACE_CREDENTIALS_CONTENT environment variable
The delegated user must be provided via the GOOGLEWORKSPACE_DELEGATED_USER environment variable.

​
Best Practices

  • Use environment variables — Never hardcode credentials in scripts or commands
  • Use a dedicated Service Account — Create one specifically for Prowler, separate from other integrations
  • Use read-only scopes — Prowler only requires the three read-only scopes listed above
  • Restrict key access — Set file permissions to 600 on the JSON key file
  • Rotate keys regularly — Delete and regenerate the JSON key periodically
  • Use a least-privilege super admin — Consider using a dedicated super admin account for Prowler’s delegated user rather than a personal admin account
# Secure the key file
chmod 600 /path/to/googleworkspace-sa.json

​
Troubleshooting

​
GoogleWorkspaceMissingDelegatedUserError

The delegated user email was not provided. Set it via environment variable: 
export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"

​
GoogleWorkspaceNoCredentialsError

No credentials were found. Ensure either GOOGLEWORKSPACE_CREDENTIALS_FILE or GOOGLEWORKSPACE_CREDENTIALS_CONTENT is set.

​
GoogleWorkspaceInvalidCredentialsError

The JSON key file is malformed or cannot be parsed. Verify the file was downloaded correctly and is valid JSON: 
python3 -c "import json; json.load(open('/path/to/key.json'))" && echo "Valid JSON"

​
GoogleWorkspaceImpersonationError

The Service Account cannot impersonate the delegated user. This usually means Domain-Wide Delegation has not been configured, or the OAuth scopes are incorrect. Verify:
  • The Service Account Client ID is correctly entered in the Admin Console
  • All three required OAuth scopes are included
  • The delegated user is a super administrator

​
Permission Denied on Admin SDK calls

If Prowler connects but returns empty results or permission errors for specific API calls:
  • Confirm Domain-Wide Delegation is fully propagated (wait a few minutes after setup)
  • Verify all three scopes are authorized in the Admin Console
  • Ensure the delegated user is an active super administrator