Google Workspace setup

​

Part 1: Google Workspace Data Ingestion

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

1. Go to the Google Cloud Console.
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

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

1. Sign in to the Google Workspace Admin Console 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.

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/admin.reports.usage.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

Seat utilization uses apps.licensing + admin.reports.usage.readonly. apps.licensing answers “how many seats are assigned” (one row per user per SKU). The purchased count comes from the Reports API customer usage report under admin.reports.usage.readonly, which exposes accounts:<edition>_total_licenses alongside _used_licenses. apps.order does not work for this and you can skip it. The Reseller API has the same numbers, but it authenticates the reseller — a customer super admin gets a flat 403 Forbidden on every method even with the scope granted, and buying through a reseller does not change that. It is listed above only because the scope name suggests otherwise. Note admin.reports.usage.readonly is a separate scope from admin.reports.audit.readonly — granting the audit one does not grant this one, and vice versa.

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

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.

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.

• 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. Note this failure happens when the token is issued, before any API call, so a script hitting it produces no 403 and no error rows — its table simply stays empty. Scopes are authorized individually: the rest of the integration can be working perfectly while one un-granted scope leaves its own endpoints silently at zero. If one table is empty and the others are fine, suspect its scope first.
• 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