> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prowler.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Authentication in Prowler

export const VersionBadge = ({version}) => {
  return <a href={`https://github.com/prowler-cloud/prowler/releases/tag/${version}`} target="_blank" rel="noopener noreferrer" className="version-badge-link">
            <span className="version-badge-container">
                <span className="version-badge">
                    <span className="version-badge-label">Added in:</span> 
                    <span className="version-badge-version">{version}</span>
                </span>
            </span>
        </a>;
};

<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 navigate to **APIs & Services → Library**. Search for and enable each of the following APIs:

| API                    | Required For                                                            |
| ---------------------- | ----------------------------------------------------------------------- |
| **Admin SDK API**      | Directory service checks (users, roles, domains)                        |
| **Cloud Identity API** | All service checks except Directory (domain-level application policies) |

For each API:

1. Search for the API name in the library
2. Click the API result
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.
</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>

### 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 theme={null}
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 theme={null}
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 theme={null}
# 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 theme={null}
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 theme={null}
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)