DigiUsherDigiUsher Documentation
Go to Product
Data Connections

Connecting Google Workspace

Set up DigiUsher to track Google Workspace license costs, seat utilization, and Gemini AI adoption.

Overview

To onboard your Google Workspace environment to DigiUsher, a GCP service account with Domain-Wide Delegation is required. This provides read-only access to your Workspace user directory, license assignments, and usage reports — giving you:

  • Cost visibility: Google Workspace spend in FOCUS format alongside your cloud costs, with Organizational Unit (OU) breakdown for team-level chargeback/showback
  • License optimization: Identify suspended users still holding paid licenses and track seat count trends over time
  • Gemini AI adoption & ROI: Per-user Gemini usage tracking to evaluate whether AI Expanded/Ultra Access add-on licenses are justified
  • Utilization insights: Per-user last login tracking and org-level storage pool utilization

Summary of Access Required

ComponentDetails
IdentityGCP Service Account (digiusher-workspace) — API-only, no Console login
AuthenticationJSON key with Domain-Wide Delegation
Access levelRead-only — user directory, license assignments, usage reports
ScopeGoogle Workspace domain (all Organizational Units)
Data accessUser metadata, license SKUs, and usage reports only — no email, Drive, or Calendar content
CapabilityWhat It Provides
License cost trackingPer-SKU costs in FOCUS format alongside your cloud spend
Seat utilizationSeat counts per SKU per Organizational Unit
Suspended user detectionIdentify unused licenses from suspended accounts
Gemini AI trackingUsage events to evaluate add-on ROI

DigiUsher cannot read email, documents, or any user-generated content. DigiUsher cannot modify users, licenses, or organizational structure.

Use Terraform for the fastest setup

DigiUsher strongly recommends the Terraform configuration for the most efficient and reliable setup. It creates the service account and enables the required APIs automatically.

Terraform Repository: https://github.com/digiusher/digiusher-iac/

If your organization's policies require manual resource provisioning, follow the steps below.

Prerequisites

Information to Gather

ItemHow to Find
GCP Project IDgcloud projects list or Console: select a project from the project picker

Roles Required by the Person Performing Setup

RoleWhy
GCP Project Owner or EditorTo create the service account and enable APIs
Google Workspace Super AdminTo configure Domain-Wide Delegation and create custom admin roles

Network & Email Access (For Regulated Environments)

If your organization restricts outbound internet access or email domains, ensure the following are in place before starting:

  • Domain allowlist: Add *.digiusher.com to your network/firewall allowlist so that users in your organization can access the DigiUsher platform from their browsers.
  • Email allowlist: Add digiusher.com as an approved sender domain in your email security gateway. DigiUsher sends onboarding confirmations, alerts, and reports from @digiusher.com addresses.

The DigiUsher Terraform configuration creates the service account and enables the required APIs in ~2 minutes.

git clone https://github.com/digiusher/digiusher-iac.git
cd digiusher-iac/google-workspace

cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars — set your GCP project ID
# Find yours with: gcloud projects list

terraform init
terraform plan
terraform apply

After Terraform Apply

The remaining steps must be completed manually in the Google Admin Console — there are no APIs to automate Domain-Wide Delegation or custom admin role creation.

Extract the Service Account Key

terraform output -raw service_account_key | base64 -d > digiusher-workspace-key.json

Important

Store this key securely. Do not commit digiusher-workspace-key.json or terraform.tfstate to version control — both contain the private key.

Configure Domain-Wide Delegation

  1. Go to the Domain-Wide Delegation page in the Google Admin Console
    • Or navigate: Security > Access and data control > API controls > Manage Domain Wide Delegation

Google Admin Console Domain-Wide Delegation page

  1. Click Add new
  2. Client ID: copy from Terraform output: 
    terraform output -raw service_account_client_id
  3. OAuth scopes: copy the entire comma-separated line from Terraform output: 
    terraform output -raw dwd_scopes
  4. Click Authorize

Add new client ID dialog with Client ID and OAuth scopes

Propagation delay

Domain-Wide Delegation changes can take up to 24 hours to propagate. If DigiUsher's connection verification fails immediately after setup, wait and retry.

Create a Custom Admin Role

  1. Go to Admin roles in the Google Admin Console
  2. Click Create new role
  3. Name: DigiUsher Read-Only
  4. Scroll through the privilege categories and enable:
    • Users > Read
    • Reports
    • License Management
    • License Management > License Read
  5. Click Create

DigiUsher Read-Only custom role with 4 privileges selected

Assign the Role to a Delegated Admin

The service account uses Domain-Wide Delegation to impersonate a Workspace user. That user's admin privileges determine what data can be accessed, so they must hold the custom role.

  1. Go to Admin roles in the Google Admin Console
  2. Click DigiUsher Read-Only > Admins > Assign members

DigiUsher Read-Only role with assigned admin member

  1. Enter a Workspace user's email (e.g., admin@yourdomain.com) — typically the Super Admin running this setup
  2. Click Add > Assign role

Assign role dialog showing member selection

Important

This must be a real user account, not the service account email. The service account impersonates this user via Domain-Wide Delegation.

Connect in DigiUsher

Enter the credentials into the DigiUsher platform (see Connect in DigiUsher below).

See the digiusher-iac README for full Terraform documentation including troubleshooting.

Option B: Manual Setup

Follow these steps if you prefer to set up via the GCP Console or gcloud CLI.

Enable APIs

Navigate to APIs & Services > Library in the GCP Console and enable each API, or run:

gcloud services enable \
  admin.googleapis.com \
  licensing.googleapis.com \
  iam.googleapis.com \
  --project=<PROJECT_ID>

Create Service Account and Key

2a. Create the Service Account

  1. Go to IAM & Admin > Service Accounts > Create Service Account
  2. Service account ID: digiusher-workspace
  3. Display name: DigiUsher Workspace Integration
  4. Description: Read-only service account for DigiUsher Google Workspace license tracking
  5. Click Create and Continue, then Done (no roles needed — access is granted via Domain-Wide Delegation)
gcloud iam service-accounts create digiusher-workspace \
  --display-name="DigiUsher Workspace Integration" \
  --description="Read-only service account for DigiUsher Google Workspace license tracking" \
  --project=<PROJECT_ID>

2b. Create and Download JSON Key

  1. Click on the service account > Keys > Add Key > Create new key > JSON > Create
  2. The key will be downloaded as a .json file
gcloud iam service-accounts keys create digiusher-workspace-key.json \
  --iam-account=digiusher-workspace@<PROJECT_ID>.iam.gserviceaccount.com

Important

Store this key securely. You will enter it into the DigiUsher platform in the final step.

2c. Note the Client ID

You will need the service account's numeric Client ID (also called Unique ID) for Domain-Wide Delegation.

  1. Go to IAM & Admin > Service Accounts
  2. Click on digiusher-workspace
  3. Copy the Unique ID (a numeric string like 115820021521931207848)
gcloud iam service-accounts describe \
  digiusher-workspace@<PROJECT_ID>.iam.gserviceaccount.com \
  --format="value(uniqueId)"

Configure Domain-Wide Delegation

  1. Go to the Domain-Wide Delegation page in the Google Admin Console
    • Or navigate: Security > Access and data control > API controls > Manage Domain Wide Delegation
  2. Click Add new
  3. Client ID: the numeric Client ID from Step 2c
  4. OAuth scopes: paste the following (all on one line, comma-separated):
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/apps.licensing
  1. Click Authorize

Propagation delay

Domain-Wide Delegation changes can take up to 24 hours to propagate. If DigiUsher's connection verification fails immediately after setup, wait and retry.

Create a Custom Admin Role

  1. Go to Admin roles in the Google Admin Console
  2. Click Create new role
  3. Name: DigiUsher Read-Only
  4. Scroll through the privilege categories and enable:
    • Users > Read
    • Reports
    • License Management
    • License Management > License Read
  5. Click Create

Assign the Role to a Delegated Admin

  1. Go to Admin roles in the Google Admin Console
  2. Click DigiUsher Read-Only > Admins > Assign members
  3. Enter a Workspace user's email (e.g., admin@yourdomain.com) — typically the Super Admin running this setup
  4. Click Add > Assign role

Important

This must be a real user account, not the service account email. The service account impersonates this user via Domain-Wide Delegation.

Connect in DigiUsher

After completing either the Terraform or Manual setup, add a new Google Workspace data source in the DigiUsher platform with the following:

FieldWhere to Find
NameA display name for this data source (e.g., Google Workspace)
Service Account Key (JSON)The digiusher-workspace-key.json file, or terraform output -raw service_account_key | base64 -d
Delegated Admin EmailThe Workspace user assigned the DigiUsher Read-Only role (e.g., admin@yourdomain.com)

SKU Pricing

As part of the connection wizard (step 3 of 4), DigiUsher detects your installed Workspace SKUs and seat counts automatically and prompts you to enter per-SKU pricing (monthly cost per seat). This is required because Google does not provide a pricing API for Workspace licenses.

You can leave pricing at zero to complete setup — license counts and utilization data will appear immediately, and cost data fills in once you update pricing via the data source settings.

Important

The Delegated Admin Email is the Workspace user from the admin role assignment step — it is NOT the service account email from the JSON key. These are different.

OAuth Scopes Reference

ScopePurpose
admin.directory.user.readonlyRead user list: email, last login, suspended status, Organizational Unit
admin.reports.usage.readonlyRead org-level usage reports: storage utilization
admin.reports.audit.readonlyRead activity audit logs: Gemini AI usage events
apps.licensingRead license assignments: which users hold which SKUs, seat counts

Note on apps.licensing

Although no read-only variant of this scope exists, the custom admin role only grants "License Read", ensuring that only read operations are permitted.

Verification Checklist

  • GCP APIs enabled — Admin SDK, Enterprise License Manager, IAM
  • Service account digiusher-workspace created with JSON key
  • Domain-Wide Delegation configured with correct Client ID and all 4 OAuth scopes
  • Custom admin role DigiUsher Read-Only created with correct privileges
  • Admin role assigned to a real Workspace user (not the service account email)
  • Credentials entered into DigiUsher — service account key + delegated admin email
  • SKU pricing configured during the connection wizard
  • *.digiusher.com allowlisted in network/firewall (if applicable)
  • digiusher.com allowlisted for incoming email (if applicable)

Security

What DigiUsher CAN Access (Read-Only)

  • User directory: email addresses, last login timestamps, suspended status, Organizational Unit membership
  • License assignments: which users hold which Workspace SKUs, seat counts per SKU
  • Usage reports: org-level storage utilization, Gemini AI usage events
  • No access to email content, Drive files, Calendar events, or any user-generated data

What DigiUsher CANNOT Do

  • Read email, documents, or any user content
  • Modify users, groups, or organizational structure
  • Assign, remove, or change licenses
  • Access passwords, security keys, or 2FA settings
  • Make purchases or modify billing/subscriptions

Scope Controls

  • Domain-Wide Delegation authorizes 4 OAuth scopes (3 read-only, plus apps.licensing which is restricted to read-only via the custom admin role)
  • Although no read-only variant of the apps.licensing scope exists, the custom admin role only grants "License Read", ensuring that only read operations are permitted.
  • The service account has no GCP IAM roles beyond its own project — it cannot access any cloud resources

Monitoring

Monitor service account activity in the Google Admin Console under Reports > Audit and investigation > Admin log events, filtering by the delegated admin user's email.

Credential Rotation

  • Terraform: terraform apply -replace="google_service_account_key.digiusher_workspace"
  • Manual: Service account > Keys > Add Key (create new), then delete the old key. Enter the new key into the DigiUsher platform.

Revocation

  • Terraform: terraform destroy — removes the service account and invalidates the key.
  • Manual: Delete the digiusher-workspace service account in IAM & Admin > Service Accounts. This instantly invalidates the key.
  • In both cases, also remove the Domain-Wide Delegation entry in the Admin Console and optionally delete the custom admin role.

Troubleshooting

"Permission denied" when running Terraform

You need Project Owner or Editor access on the target GCP project:

gcloud projects get-iam-policy <PROJECT_ID> \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:<YOUR_EMAIL>" \
  --format="table(bindings.role)"

DigiUsher connection verification fails

  1. DWD not propagated yet — changes can take up to 24 hours. Wait and retry.
  2. Wrong scopes — verify the scopes in the Admin Console match all 4 listed in the OAuth Scopes Reference.
  3. Admin role not assigned — ensure the "DigiUsher Read-Only" custom role is assigned to the delegated admin user.
  4. Wrong delegated admin email — the email provided to DigiUsher must be the Workspace user who holds the "DigiUsher Read-Only" role, not the service account email from the JSON key.

"API not enabled" errors

Terraform enables APIs automatically, but propagation can take a minute. Re-run terraform apply if this occurs.

Cannot find GCP Project ID

gcloud projects list

Need Help?

If you encounter any issues not covered above, contact DigiUsher support at support@digiusher.com and the team will help you get set up.

Connecting a GCP account

Previous Page

Connecting an Oracle Cloud Infrastructure (OCI) account

Next Page