Connecting Google Workspace

Overview

To connect your Google Workspace environment to DigiUsher, you need a GCP service account with Domain-Wide Delegation. Domain-Wide Delegation lets a service account act for a user of your domain. The account gets read-only access to your Workspace user directory, to the license assignments, and to the usage reports. You then get:

• Cost visibility. Your Google Workspace spend appears in FOCUS format beside your cloud costs. The breakdown by Organizational Unit (OU) gives you chargeback and showback for each team.
• License optimization. You see the suspended users that still hold a paid license, and the trend of the seat count over time.
• Gemini AI adoption. You see the Gemini usage of each user, and you can decide whether the AI Expanded or Ultra Access add-on licenses are worth their cost.
• Utilization data. You see the last login of each user, and the utilization of the storage pool of the organization.

Summary of Access Required

DigiUsher cannot read email, documents, or other content of your users. DigiUsher cannot change users, licenses, or the structure of your organization.

If the policies of your organization need a setup by hand, use the manual steps on this page.

Prerequisites

Information to Gather

Roles Required by the Person Performing Setup

Option A: Terraform (Recommended)

The DigiUsher Terraform configuration creates the service account and enables the necessary APIs in approximately 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

You must do the remaining steps by hand, in the Google Admin Console. There is no API for Domain-Wide Delegation, and no API to create a custom admin role.

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

The digiusher-iac README is the full Terraform documentation. It also gives the troubleshooting steps.

Option B: Manual Setup

Use these steps for a setup with the GCP Console or the gcloud CLI.

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

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

Connect in DigiUsher

After you complete the Terraform setup or the manual setup, go to Connectors > Add Source in DigiUsher and select Google Workspace. On the Configure step, enter these values:

Go to Connect and click Connect source to finish.

OAuth Scopes Reference

Setup Checklist

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

Security

What DigiUsher CAN Access (Read-Only)

• The user directory: email addresses, the time of the last login, the suspended state, and the Organizational Unit of each user
• The license assignments: the Workspace SKUs of each user, and the number of seats of each SKU
• The usage reports: the storage utilization of the organization, and the Gemini AI usage events
• DigiUsher reads no email content, no Drive files, no Calendar events, and no other content of your users

What DigiUsher CANNOT Do

• Read email, documents, or other content of your users
• Change users, groups, or the structure of your organization
• Add, remove, or change a license
• Read passwords, security keys, or the configuration of the two-factor authentication
• Buy a product, or change the billing configuration or the subscriptions

Scope Controls

• The Domain-Wide Delegation gives 4 OAuth scopes. Three of them are read-only. The fourth is apps.licensing, and the custom admin role limits it to read operations
• The scope apps.licensing has no read-only variant. The custom admin role gives only the privilege "License Read", so only read operations are permitted
• The service account has no GCP IAM role outside its own project. It therefore cannot read your cloud resources

Monitoring

To monitor the activity of the service account, open the Google Admin Console under Reports > Audit and investigation > Admin log events. Filter by the email address of the delegated admin user.

Credential Rotation

• With Terraform, run terraform apply -replace="google_service_account_key.digiusher_workspace".
• By hand, open the service account and click Keys > Add Key to create a new key. Then delete the old key, and enter the new key in the DigiUsher platform.

Revocation

• With Terraform, run terraform destroy. It removes the service account and invalidates the key.
• By hand, delete the service account digiusher-workspace in IAM & Admin > Service Accounts. GCP then immediately invalidates the key.
• In both cases, also remove the Domain-Wide Delegation entry in the Admin Console. You can also delete the custom admin role.

Troubleshooting

"Permission denied" when running Terraform

You need the access of a Project Owner or a Project Editor on the GCP project. This command gives your roles:

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. The Domain-Wide Delegation is not active yet. A change can take up to 24 hours. Wait and try again.
2. The scopes are wrong. Make sure that the scopes in the Admin Console are the 4 scopes of the OAuth Scopes Reference.
3. The admin role is not assigned. Make sure that the delegated admin user has the custom role "DigiUsher Read-Only".
4. The delegated admin email is wrong. The email address in DigiUsher must be the Workspace user with the role "DigiUsher Read-Only". It is not the service account email from the JSON key.

"API not enabled" errors

Terraform enables the APIs automatically, but an API needs a minute to become active. If you get this error, run terraform apply again.

Cannot find GCP Project ID

gcloud projects list

Need Help?

If this page does not answer your question, write to DigiUsher support at support@digiusher.com. The team will help you.