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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.prowler.com/feedback

```json
{
  "path": "/user-guide/providers/googleworkspace/authentication",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

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

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

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