prowler/docs/user-guide/providers/googleworkspace/authentication.mdx

---
title: 'Google Workspace Authentication in Prowler'
---

import { VersionBadge } from "/snippets/version-badge.mdx"

<VersionBadge version="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 |

<Warning>
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.
</Warning>

## 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](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](https://console.cloud.google.com), select the target project and enable each of the following APIs:

| API | Service Name | Required For |
|-----|--------------|--------------|
| **[Admin SDK API](https://console.cloud.google.com/apis/library/admin.googleapis.com)** | `admin.googleapis.com` | Directory service checks (users, roles, domains) |
| **[Cloud Identity API](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com)** | `cloudidentity.googleapis.com` | All service checks except Directory (domain-level application policies) |

For each API:

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

<Note>
Both APIs 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.
</Note>

### 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**

<Note>
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.
</Note>

### 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`)

<Warning>
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.
</Warning>

#### Service Account Key Creation Is Disabled

Organizations created on or after May 3, 2024 enforce the [Secure by Default](https://docs.cloud.google.com/resource-manager/docs/secure-by-default-organizations) 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:

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

Alternatively, override the policy with the Google Cloud CLI:

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

```console
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

1. Navigate to the [Google Workspace Admin Console](https://admin.google.com)
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
```

7. Click **Authorize**

<Note>
Domain-Wide Delegation must be configured by a Google Workspace **super administrator**. It may take a few minutes to propagate after saving.
</Note>

### 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:

```console
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):

```console
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

```bash
# 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:

```bash
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:

```bash
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)