docs(googleworkspace): add Cloud/App documentation (#10421)

Co-authored-by: Andoni A. <14891798+andoniaf@users.noreply.github.com>
2026-07-04 19:21:51 +00:00 · 2026-03-24 09:48:01 +01:00
parent 844efbd046
commit 737d20d2c1
8 changed files with 122 additions and 84 deletions
@@ -2,9 +2,13 @@
 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. This allows Prowler to read directory data on behalf of a super administrator without requiring an interactive login.

-## Required OAuth Scopes
+## Required Open Authorization (OAuth) Scopes

 Prowler requests the following read-only OAuth 2.0 scopes from the Google Workspace Admin SDK:

@@ -20,16 +24,16 @@ The delegated user must be a **super administrator** in your Google Workspace or

 ## Setup Steps

-### Step 1: Create a GCP Project (if needed)
+### Step 1: Create a Google Cloud Platform (GCP) Project (if Needed)

-If you don't have a GCP project, create one at [https://console.cloud.google.com](https://console.cloud.google.com).
+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 the Admin SDK API

-1. Go to the [Google Cloud Console](https://console.cloud.google.com)
-2. Select your project
+1. Navigate to the [Google Cloud Console](https://console.cloud.google.com)
+2. Select the target project
 3. Navigate to **APIs & Services → Library**
 4. Search for **Admin SDK API**
 5. Click **Enable**
@@ -48,8 +52,8 @@ The Service Account does not need any GCP IAM roles. Its access to Google Worksp

 ### Step 4: Generate a JSON Key

-1. Click on the Service Account you just created
-2. Go to the **Keys** tab
+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
@@ -61,7 +65,7 @@ This JSON key grants access to your Google Workspace organization. Never commit

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

-1. Go to the [Google Workspace Admin Console](https://admin.google.com)
+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**
@@ -78,23 +82,26 @@ https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.google
 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: Store Credentials Securely
+### Step 6: Provide Credentials to Prowler

-Set your credentials as environment variables:
+- **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:

-```bash
+```console
 export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/googleworkspace-sa.json"
 export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
+prowler googleworkspace
 ```

-Alternatively, if you need to pass credentials as a string (e.g., in CI/CD pipelines):
+Alternatively, to pass credentials as a string (e.g., in CI/CD pipelines):

-```bash
+```console
 export GOOGLEWORKSPACE_CREDENTIALS_CONTENT=$(cat /path/to/googleworkspace-sa.json)
 export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
+prowler googleworkspace
 ```

-## Credential Lookup Order
+## How Prowler Resolves Credentials

 Prowler resolves credentials in the following order:

@@ -147,7 +154,7 @@ The Service Account cannot impersonate the delegated user. This usually means Do
 - All three required OAuth scopes are included
 - The delegated user is a super administrator

-### Permission Denied on Admin SDK calls
+### Permission Denied on Admin SDK Calls

 If Prowler connects but returns empty results or permission errors for specific API calls:

@@ -1,100 +1,131 @@
 ---
-title: 'Getting Started with Google Workspace'
+title: 'Getting Started With Google Workspace on Prowler'
 ---

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

-<VersionBadge version="5.19.0" />
-
-Prowler for Google Workspace allows you to audit your organization's Google Workspace environment for security misconfigurations, including super administrator account hygiene, domain settings, and more.
+Prowler for Google Workspace audits the organization's Google Workspace environment for security misconfigurations, including super administrator account hygiene, domain settings, and more.

 ## Prerequisites

-Before running Prowler with the Google Workspace provider, ensure you have:
+Set up authentication for Google Workspace with the [Google Workspace Authentication](/user-guide/providers/googleworkspace/authentication) guide before starting either path:

-1. A Google Workspace account with super administrator privileges
-2. A Google Cloud Platform (GCP) project to host the Service Account
-3. Authentication configured (see [Authentication](/user-guide/providers/googleworkspace/authentication)):
-   - A **Service Account JSON key** from a GCP project with Domain-Wide Delegation enabled
+- **Service Account:** Create a Service Account in a GCP project with Domain-Wide Delegation enabled.
+- **OAuth Scopes:** Authorize the required read-only OAuth scopes in the Google Workspace Admin Console.
+- **Customer ID:** Identify the Google Workspace Customer ID to use as the provider identifier.
+- **Delegated User:** Have the email of a super administrator to use as the delegated user.

-## Quick Start
+<CardGroup cols={2}>
+  <Card title="Prowler Cloud" icon="cloud" href="#prowler-cloud">
+    Onboard Google Workspace using Prowler Cloud
+  </Card>
+  <Card title="Prowler CLI" icon="terminal" href="#prowler-cli">
+    Onboard Google Workspace using Prowler CLI
+  </Card>
+</CardGroup>
+
+## Prowler Cloud
+
+<VersionBadge version="5.21.0" />
+
+### Step 1: Locate the Customer ID
+
+1. Log into the [Google Workspace Admin Console](https://admin.google.com).
+2. Navigate to "Account" > "Account Settings".
+3. Find the **Customer ID** on the Account Settings page.
+
+    ![Google Workspace Customer ID](/images/providers/googleworkspace-customer-id.png)
+
+<Note>
+The Customer ID starts with the letter "C" followed by alphanumeric characters (e.g., `C0xxxxxxx`). This value acts as the unique identifier for the Google Workspace account in Prowler Cloud.
+</Note>
+
+### Step 2: Open Prowler Cloud
+
+1. Go to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](/user-guide/tutorials/prowler-app).
+2. Navigate to "Configuration" > "Cloud Providers".
+
+    ![Cloud Providers Page](/images/prowler-app/cloud-providers-page.png)
+
+3. Click "Add Cloud Provider".
+
+    ![Add a Cloud Provider](/images/prowler-app/add-cloud-provider.png)
+
+4. Select "Google Workspace".
+
+    ![Select Google Workspace](/images/providers/select-googleworkspace-prowler-cloud.png)
+
+### Step 3: Provide Credentials
+
+1. Enter the **Customer ID** and an optional alias, then click "Next".
+
+    ![Google Workspace Customer ID Form](/images/providers/googleworkspace-customer-id-form.png)
+
+2. Paste the **Service Account JSON** credentials content.
+3. Enter the "Delegated User Email" (a super administrator in the Google Workspace organization).
+
+    ![Google Workspace Credentials Form](/images/providers/googleworkspace-credentials-form.png)
+
+<Note>
+The Service Account JSON is the full content of the key file downloaded when creating the Service Account. Paste the entire JSON object, not just the file path. For setup instructions, see the [Authentication guide](/user-guide/providers/googleworkspace/authentication).
+</Note>
+
+### Step 4: Check Connection
+
+1. Click "Check Connection" to verify that the credentials and Domain-Wide Delegation are configured correctly.
+2. Prowler will test the Service Account impersonation and Admin SDK access.
+
+    ![Check Connection](/images/providers/googleworkspace-check-connection.png)
+
+<Note>
+If the connection test fails, verify that Domain-Wide Delegation is properly configured and that all three OAuth scopes are authorized. It may take a few minutes for delegation changes to propagate. See the [Troubleshooting](/user-guide/providers/googleworkspace/authentication#troubleshooting) section for common errors.
+</Note>
+
+### Step 5: Launch the Scan
+
+1. Review the summary.
+2. Click "Launch Scan" to start auditing Google Workspace.
+
+    ![Launch Scan](/images/providers/googleworkspace-launch-scan.png)
+
+---
+
+## Prowler CLI
+
+<VersionBadge version="5.19.0" />

 ### Step 1: Set Up Authentication

-Set your Service Account credentials file path and delegated user email as environment variables:
+Set your Service Account credentials and delegated user email following the [Google Workspace Authentication](/user-guide/providers/googleworkspace/authentication) guide:

-```bash
+```console
 export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/service-account-key.json"
 export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
 ```

-### Step 2: Run Prowler
-
-```bash
-prowler googleworkspace
-```
-
-Prowler will authenticate as the delegated user and run all available security checks against your Google Workspace organization.
-
-## Authentication
-
-Prowler uses a **Service Account with Domain-Wide Delegation** to authenticate to Google Workspace. This requires:
-
- A Service Account created in a GCP project
- The Admin SDK API enabled in that project
- Domain-Wide Delegation configured in the Google Workspace Admin Console
- A super admin user email to impersonate
-
-### Using Environment Variables (Recommended)
-
-```bash
-export GOOGLEWORKSPACE_CREDENTIALS_FILE="/path/to/service-account-key.json"
-export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
-prowler googleworkspace
-```
-
 Alternatively, pass the credentials content directly as a JSON string:

-```bash
+```console
 export GOOGLEWORKSPACE_CREDENTIALS_CONTENT='{"type": "service_account", ...}'
 export GOOGLEWORKSPACE_DELEGATED_USER="admin@yourdomain.com"
+```
+
+### Step 2: Run the First Scan
+
+Run a baseline scan after credentials are configured:
+
+```console
 prowler googleworkspace
 ```

-<Note>
-The delegated user must be a super admin email in your Google Workspace organization. The service account credentials must be provided via environment variables (`GOOGLEWORKSPACE_CREDENTIALS_FILE` or `GOOGLEWORKSPACE_CREDENTIALS_CONTENT`).
-</Note>
+Prowler authenticates as the delegated user and runs all available security checks against the Google Workspace organization.

-## Understanding the Output
-
-When Prowler runs successfully, it will display the credentials being used:
-
-```
-Using the Google Workspace credentials below:
-┌─────────────────────────────────────────────────────────┐
-│ Google Workspace Domain: yourdomain.com                 │
-│ Customer ID: C0xxxxxxx                                  │
-│ Delegated User: admin@yourdomain.com                    │
-│ Authentication Method: Service Account with Domain-Wide  │
-│ Delegation                                              │
-└─────────────────────────────────────────────────────────┘
-```
-
-Findings are reported per check. For example, the `directory_super_admin_count` check verifies the number of super administrators is within a recommended range (2–4):
-
- **PASS** — 2 to 4 super administrators found
- **FAIL** — 0 or 1 (single point of failure) or 5+ (excessive privilege exposure)
-
-Output files are saved in the configured output directory (default: `output/`) in CSV, JSON-OCSF, and HTML formats.
-
-## Configuration
+### Step 3: Use a Custom Configuration (Optional)

 Prowler uses a configuration file to customize provider behavior. To use a custom configuration:

-```bash
+```console
 prowler googleworkspace --config-file /path/to/config.yaml
 ```

-## Next Steps
-
- [Authentication](/user-guide/providers/googleworkspace/authentication) — Detailed guide on setting up a Service Account and Domain-Wide Delegation
+---