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

# Google Workspace setup

## Part 1: Google Workspace Data Ingestion

Set up a Google Cloud service account with **domain-wide delegation** so ConfigView can pull your Google Workspace data into the dashboard.

ConfigView reads Workspace through the **Admin SDK** and a few related Admin APIs. A single service account, authorized once in your Workspace Admin Console, impersonates an admin and reads users, groups, org units, roles, devices, audit logs, and mailbox settings — all read-only.

You'll end up with two things in ConfigView: a secret `GOOGLE_ADMIN_EMAIL` (the admin to impersonate) and the service-account key file, uploaded as `google_admin.json`. The key is **not** a Secret Manager secret — like Google Cloud, it's uploaded as a JSON file and referenced directly by the scripts.

> **Running more than one Google Workspace?** Each instance gets its own JSON file and admin-email secret, suffixed by number: the first instance uses `google_admin.json` + `GOOGLE_ADMIN_EMAIL`, the second uses `google_admin_2.json` + `GOOGLE_ADMIN_EMAIL_2`, and so on. The steps below cover the first instance; for a second instance, just append `_2` to the filename and the secret name.

***

### Step 1: Create a Google Cloud project

The service account lives in a Google Cloud project. Any project works; API calls are quoted against it.

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Click the **project dropdown** (top-left) → **New Project**.
3. Name it `configview-integration`, choose your Organization, and click **Create**.
4. Make sure the new project is selected in the dropdown before continuing.

***

### Step 2: Enable the required APIs

On that project, enable the APIs ConfigView calls. On a fresh project these are **off by default**. Click each link (with your project selected) and press **Enable**, or run the one-liner below.

| API                                | Console link                                                                          | Used for                                                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin SDK API**                  | [enable](https://console.cloud.google.com/apis/library/admin.googleapis.com)          | Users, groups, org units, roles, ChromeOS devices, schemas, domains, and the Admin **audit log** (Reports) — the bulk of the integration |
| **Cloud Identity API**             | [enable](https://console.cloud.google.com/apis/library/cloudidentity.googleapis.com)  | Mobile devices                                                                                                                           |
| **Groups Settings API**            | [enable](https://console.cloud.google.com/apis/library/groupssettings.googleapis.com) | Per-group sharing / posting settings                                                                                                     |
| **Enterprise License Manager API** | [enable](https://console.cloud.google.com/apis/library/licensing.googleapis.com)      | Gemini / Workspace license assignments                                                                                                   |
| **Gmail API**                      | [enable](https://console.cloud.google.com/apis/library/gmail.googleapis.com)          | Mailbox forwarding rules and delegates                                                                                                   |

```bash theme={null}
gcloud services enable admin.googleapis.com cloudidentity.googleapis.com \
  groupssettings.googleapis.com licensing.googleapis.com gmail.googleapis.com \
  --project=configview-integration
```

> **Note.** The Admin SDK exposes both the Directory (`directory_v1`) and Reports (`reports_v1`) APIs under the single `admin.googleapis.com` service — enabling Admin SDK API covers both. You only need the others for the specific endpoints listed above; skip an API and just leave its scripts disabled.

> **Propagation.** Right after enabling, you may see intermittent `SERVICE_DISABLED` 403s for \~10–15 minutes while the change rolls out. Wait it out before assuming a misconfiguration.

***

### Step 3: Create the service account

1. Open [IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) with your `configview-integration` project selected.
2. Click **Create Service Account**.
3. **Name:** `configview` (the email auto-fills, e.g. `configview@configview-integration.iam.gserviceaccount.com`).
4. Click **Create and Continue**.
5. **Skip** the optional "Grant this service account access to project" and "Grant users access" steps — this integration needs **no project IAM roles**; all access comes from domain-wide delegation in Step 5.
6. Click **Done**.

***

### Step 4: Create and download the JSON key

1. From the service account list, click your `configview` service account.
2. Open the **Keys** tab → **Add Key** → **Create new key** → **JSON** → **Create**.
3. The JSON key file downloads automatically. Keep it handy — you'll upload it to ConfigView in Step 6.
4. While you're here, open the **Details** tab and copy the **Unique ID** (the numeric **Client ID**) — you'll need it for delegation in Step 5.

***

### Step 5: Authorize domain-wide delegation

This is what lets the service account read your Workspace data. You authorize its Client ID against a fixed list of read-only scopes in the Admin Console.

1. Sign in to the [Google Workspace Admin Console](https://admin.google.com) as a **super admin**.
2. Go to **Security** → **Access and data control** → **API controls** → **Manage Domain Wide Delegation**.
3. Click **Add new** and paste:
   * **Client ID:** the numeric Unique ID from Step 4.4
   * **OAuth scopes:** the comma-separated list below
4. Click **Authorize**.

Paste this full scope list (read-only — they grant visibility, never write access):

```
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.user.security,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.group.member.readonly,
https://www.googleapis.com/auth/admin.directory.orgunit.readonly,
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,
https://www.googleapis.com/auth/admin.directory.domain.readonly,
https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly,
https://www.googleapis.com/auth/admin.directory.userschema.readonly,
https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/apps.groups.settings,
https://www.googleapis.com/auth/apps.licensing,
https://www.googleapis.com/auth/cloud-identity.devices.readonly,
https://www.googleapis.com/auth/gmail.readonly,
https://www.googleapis.com/auth/gmail.settings.basic
```

Each scope maps to a slice of the integration:

| Scope                                      | Unlocks                                           |
| ------------------------------------------ | ------------------------------------------------- |
| `admin.directory.user.readonly`            | Users                                             |
| `admin.directory.user.security`            | Tokens (OAuth grants), 2-step verification status |
| `admin.directory.group.readonly`           | Groups                                            |
| `admin.directory.group.member.readonly`    | Group members                                     |
| `admin.directory.orgunit.readonly`         | Org units                                         |
| `admin.directory.rolemanagement.readonly`  | Roles, privileges, role assignments               |
| `admin.directory.domain.readonly`          | Domains, domain aliases                           |
| `admin.directory.device.chromeos.readonly` | ChromeOS devices                                  |
| `admin.directory.userschema.readonly`      | Custom user schemas                               |
| `admin.reports.audit.readonly`             | Admin audit log (Reports API)                     |
| `apps.groups.settings`                     | Per-group settings                                |
| `apps.licensing`                           | Gemini / Workspace license assignments            |
| `cloud-identity.devices.readonly`          | Mobile devices                                    |
| `gmail.readonly`, `gmail.settings.basic`   | Mailbox forwarding rules and delegates            |

> **Adding scopes later.** If you enable a new script that needs a scope you didn't authorize, re-open **Manage Domain Wide Delegation**, click your client row, and add the missing scope. Delegation changes take a minute or two to propagate.

> **Trim if you like.** You only need the scopes for the scripts you'll actually run. The list above is the full set; dropping a scope just disables its endpoints (and its health check).

***

### Step 6: Add the secret and upload the JSON key

**6a. Add the admin-email secret.**

1. Go to your ConfigView dashboard: `https://{companyname}.configview.com/admin/secret/`
2. Click **Add Secret** and create:
   * `GOOGLE_ADMIN_EMAIL`: a super-admin email address for the service account to impersonate (e.g. `admin@yourdomain.com`)
3. Click **Save**.

**6b. Upload the service-account JSON key.**

1. Go to the JSON upload board: `https://{companyname}.configview.com/admin/external/`
2. **Rename the key file you downloaded in Step 4 to `google_admin.json`** before uploading — the scripts resolve it by that exact name.
3. Upload it. It's saved to `<project_root>/json/google_admin.json` on the satellite (the same directory that already holds `secret-manager.json`). It is **not** a Secret Manager secret — the key is referenced directly by all Google Workspace scripts.

> **Second instance.** For a second Google Workspace, name the secret `GOOGLE_ADMIN_EMAIL_2` and upload the key as `google_admin_2.json` (instance 3 → `_3`, and so on).

***

### Step 7: Enable the Google Workspace app in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/cron/`
2. You should see **Google Workspace** in the list of available apps.
3. Select the scripts you want to run.
4. Click **Save**.

***

### Step 8: Verify

1. Go to: `https://{companyname}.configview.com/admin/status/`
2. Run the **Google Workspace** health check.
3. All checks should pass.

If a check fails:

* **`unauthorized_client` / `Client is unauthorized to retrieve access tokens`** — the Client ID isn't authorized, or a required scope is missing. Re-do Step 5 and confirm the Unique ID matches.
* **`access_denied` / `403`** on a specific endpoint — the matching scope wasn't authorized, or `GOOGLE_ADMIN_EMAIL` isn't a super admin.
* **`SERVICE_DISABLED`** — the API for that endpoint isn't enabled on the project. Re-check Step 2.
* **`FileNotFoundError` / `google_admin.json`** — the key file wasn't uploaded, or was uploaded under the wrong name. Re-do Step 6b and confirm it's named exactly `google_admin.json` (or `google_admin_2.json` for a second instance).
* Otherwise verify your `GOOGLE_ADMIN_EMAIL` secret and the uploaded JSON key are both in place.

***

### Data Tables

Once the scripts run, the corresponding Google Workspace tables will be created in your database. All tables include a `run_at` column for historical tracking.

The **Admin Audit Log** script (`google_admin_audit`) pulls the Google Admin Console activity feed from the Reports API — user, group, role, and security-setting changes over a rolling 180-day window. Curated queries built on it (recent admin actions, role & privilege changes, security-setting changes, and per-user investigation lookups) ship in the saved-query catalog under the **Audit** category.