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

​
Required Open Authorization (OAuth) Scopes

Prowler requests the following read-only OAuth 2.0 scopes:
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)
https://www.googleapis.com/auth/admin.directory.orgunit.readonlyRead access to organizational unit hierarchy (identifies the root OU for policy filtering)
https://www.googleapis.com/auth/cloud-identity.policies.readonlyRead access to domain-level application policies (required for Calendar service checks)
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonlyRead access to admin roles and role assignments
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 Google Cloud Platform (GCP) Project (if Needed)

If no GCP project exists, 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 Required APIs

In the Google Cloud Console, select the target project and navigate to APIs & Services → Library. Search for and enable each of the following APIs:
APIRequired For
Admin SDK APIDirectory service checks (users, roles, domains)
Cloud Identity APICalendar service checks (domain-level sharing and invitation policies)
For each API:
  1. Search for the API name in the library
  2. Click the API result
  3. Click Enable
Both APIs must be enabled in the same GCP project that hosts the Service Account. Calendar checks will return no findings if the Cloud Identity API is not enabled.

​
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 the newly created Service Account
  2. Navigate 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. Navigate 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,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/cloud-identity.policies.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.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: Provide Credentials to Prowler

  • Prowler Cloud: Paste the Service Account JSON content and enter the delegated user email in the credentials form when configuring the Google Workspace provider.
  • Prowler CLI: Export the credentials as environment variables:
export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/googleworkspace-sa.json"
export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
prowler googleworkspace
Alternatively, 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"
prowler googleworkspace

​
How Prowler Resolves Credentials

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 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 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 scopes are authorized in the Admin Console
  • Ensure the delegated user is an active super administrator

​
Calendar Checks Return No Findings

If the Directory checks run successfully but the Calendar checks (e.g., calendar_external_sharing_primary_calendar) return no findings, the Cloud Identity Policy API is not reachable for this Service Account. Verify:
  • The Cloud Identity API is enabled in the GCP project hosting the Service Account (Step 2)
  • The scope https://www.googleapis.com/auth/cloud-identity.policies.readonly is included in the Domain-Wide Delegation OAuth scopes list in the Admin Console (Step 5)
  • The delegated user is a super administrator (the Policy API only returns data to super admins)
  • Domain-Wide Delegation has had time to propagate after adding the new scope (a few minutes)