Google Workspace Authentication in Prowler

Added in: 5.19.0 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:

Scope	Description
`https://www.googleapis.com/auth/admin.directory.user.readonly`	Read access to user accounts and their admin status
`https://www.googleapis.com/auth/admin.directory.domain.readonly`	Read access to domain information
`https://www.googleapis.com/auth/admin.directory.customer.readonly`	Read access to customer information (Customer ID)
`https://www.googleapis.com/auth/admin.directory.orgunit.readonly`	Read access to organizational unit hierarchy (identifies the root OU for policy filtering)
`https://www.googleapis.com/auth/cloud-identity.policies.readonly`	Read access to domain-level application policies (required for Calendar, Chat, Drive, Gmail, Groups, Marketplace, Security, and Sites service checks)
`https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly`	Read 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.

Optional Scope for Edition Context

Prowler can read which Google Workspace editions the tenant holds, Cloud Identity Premium included, and state in a finding when the audited feature is not sold on them (for example, Data Loss Prevention (DLP) for Drive or Google session control). This needs the Enterprise License Manager API enabled in the GCP project (Step 2) and the scope https://www.googleapis.com/auth/apps.licensing added to the Domain-Wide Delegation list (Step 5). Without the scope, every check runs the same and findings carry no edition context.

The apps.licensing scope is Google’s “view and manage licenses” scope and has no read-only variant. Prowler only lists license assignments, but anyone holding the Service Account key could assign or revoke licenses with it on behalf of the super administrator. Grant it only if you want the edition context, and protect the key accordingly.

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 enable each of the following APIs:

API	Service Name	Required For
Admin SDK API	`admin.googleapis.com`	Directory service checks (users, roles, domains)
Cloud Identity API	`cloudidentity.googleapis.com`	All service checks except Directory (domain-level application policies)
Enterprise License Manager API	`licensing.googleapis.com`	Optional: edition context in findings (see Optional Scope for Edition Context)

For each API:

Open the link above, or navigate to APIs & Services → Library and search for the API name
Confirm the target project is selected in the project picker
Click Enable

The Admin SDK API and the Cloud Identity API must be enabled in the same GCP project that hosts the Service Account. All service checks except Directory will return no findings if the Cloud Identity API is not enabled. The Identity and Access Management (IAM) API (iam.googleapis.com) is a different API: enabling it does not replace the Cloud Identity API.

Step 3: Create a Service Account

In the Google Cloud Console, navigate to IAM & Admin → Service Accounts
Click Create Service Account
Give it a descriptive name (e.g., prowler-googleworkspace-reader)
Click Create and Continue
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

Click the newly created Service Account
Navigate to the Keys tab
Click Add Key → Create new key
Select JSON format
Click Create — the key file will download automatically
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.

Service Account Key Creation Is Disabled

Organizations created on or after May 3, 2024 enforce the Secure by Default organization policy iam.managed.disableServiceAccountKeyCreation, and the Add key dialog shows “Service account key creation is disabled”. To create the key, a user with the Organization Policy Administrator role (roles/orgpolicy.policyAdmin) on the organization must turn off enforcement for the project that hosts the Service Account:

In the Google Cloud Console, select the project and navigate to IAM & Admin → Organization Policies
Open Disable service account key creation (iam.managed.disableServiceAccountKeyCreation) and click Manage policy
Select Override parent’s policy, click Add a rule, set Enforcement to Off, and click Set policy
Return to the Service Account Keys tab and create the key

Alternatively, override the policy with the Google Cloud CLI:

policy.yaml

name: projects/PROJECT_ID/policies/iam.managed.disableServiceAccountKeyCreation
spec:
  rules:
    - enforce: false

gcloud org-policies set-policy policy.yaml

The constraint only blocks new key creation. Keys that already exist keep working, so enforcement can be restored once the key has been downloaded.

Step 5: Configure Domain-Wide Delegation in Google Workspace

Navigate to the Google Workspace Admin Console
Navigate to Security → Access and data control → API controls
Click Manage Domain Wide Delegation
Click Add new
Enter the Client ID of the Service Account (found in the JSON key as client_id, or on the Service Account details page)
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

To enable the optional edition context, append ,https://www.googleapis.com/auth/apps.licensing to the list.

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:

GOOGLEWORKSPACE_CREDENTIALS_FILE environment variable
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

Policy API Checks Return No Findings

If the Directory checks run successfully but other service checks (Calendar, Chat, Drive, Gmail, Groups, Marketplace, Security, Sites) 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)

Prowler Cloud

Prowler for MSPs and MSSPs

Prowler Lighthouse AI

Prowler for AI Agents

CI/CD

CLI

Providers

Cookbooks

Google Workspace Authentication in Prowler

Required Open Authorization (OAuth) Scopes

Optional Scope for Edition Context

Setup Steps

Step 1: Create a Google Cloud Platform (GCP) Project (if Needed)

Step 2: Enable Required APIs

Step 3: Create a Service Account

Step 4: Generate a JSON Key

Service Account Key Creation Is Disabled

Step 5: Configure Domain-Wide Delegation in Google Workspace

Step 6: Provide Credentials to Prowler

How Prowler Resolves Credentials

Best Practices

Troubleshooting

`GoogleWorkspaceMissingDelegatedUserError`

`GoogleWorkspaceNoCredentialsError`

`GoogleWorkspaceInvalidCredentialsError`

`GoogleWorkspaceImpersonationError`

Permission Denied on Admin SDK Calls

Policy API Checks Return No Findings

​Required Open Authorization (OAuth) Scopes

​Optional Scope for Edition Context

​Setup Steps

​Step 1: Create a Google Cloud Platform (GCP) Project (if Needed)

​Step 2: Enable Required APIs

​Step 3: Create a Service Account

​Step 4: Generate a JSON Key

​Service Account Key Creation Is Disabled

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

​Step 6: Provide Credentials to Prowler

​How Prowler Resolves Credentials

​Best Practices

​Troubleshooting

​GoogleWorkspaceMissingDelegatedUserError

​GoogleWorkspaceNoCredentialsError

​GoogleWorkspaceInvalidCredentialsError

​GoogleWorkspaceImpersonationError

​Permission Denied on Admin SDK Calls

​Policy API Checks Return No Findings

Required Open Authorization (OAuth) Scopes

Optional Scope for Edition Context

Setup Steps

Step 1: Create a Google Cloud Platform (GCP) Project (if Needed)

Step 2: Enable Required APIs

Step 3: Create a Service Account

Step 4: Generate a JSON Key

Service Account Key Creation Is Disabled

Step 5: Configure Domain-Wide Delegation in Google Workspace

Step 6: Provide Credentials to Prowler

How Prowler Resolves Credentials

Best Practices

Troubleshooting

`GoogleWorkspaceMissingDelegatedUserError`

`GoogleWorkspaceNoCredentialsError`

`GoogleWorkspaceInvalidCredentialsError`

`GoogleWorkspaceImpersonationError`

Permission Denied on Admin SDK Calls

Policy API Checks Return No Findings