Skip to main content
The Google Workspace connector enables Omni to index and search content from your organization’s Google Workspace environment, including Drive, Docs, Sheets, Slides, and optionally Gmail.

​
Overview

​
What Gets Indexed

SourceContent
Google DriveFiles, folders, and metadata
Google DocsFull document text and comments
Google SheetsSheet names, cell content, and formulas
Google SlidesSlide text and speaker notes
Gmail (optional)Email subjects, bodies, and attachments

​
How It Works

  1. A service account with domain-wide delegation accesses Google Workspace APIs
  2. The connector syncs content based on user permissions
  3. Permission inheritance ensures users only see content they have access to in Google Workspace
The connector uses read-only access. Omni cannot modify any content in your Google Workspace.

​
Prerequisites

Before setting up the Google Workspace connector, ensure you have:
  • Google Cloud Platform account with billing enabled
  • Google Workspace admin access (Super Admin or delegated admin)
  • Terraform (version >= 1.0) for automated setup, OR willingness to configure manually
  • Google Cloud CLI (gcloud) installed and authenticated

​
Setup Options

Automated Setup (Recommended)

Use Terraform to automate 80% of the setup process

Manual Setup

Step-by-step manual configuration

​
Automated Setup with Terraform

This Terraform configuration automates the Google Cloud setup, reducing setup time drastically.

​
Step 1: Authenticate with Google Cloud

gcloud auth login
gcloud auth application-default login

​
Step 2: Download the Terraform Configuration

Download the Google Workspace Terraform configuration from the Omni releases page: 
OMNI_VERSION="v0.5.0"
curl -fsSL "https://github.com/getomnico/omni/releases/download/${OMNI_VERSION}/omni-terraform-gcp.tar.gz" \
  | tar xz
cd terraform-google-workspace

​
Step 3: Configure Variables

Copy and edit the configuration file: 
cp terraform.tfvars.example terraform.tfvars
Edit terraform.tfvars with your organization’s details: 
workspace_domain = "your-company.com"
admin_email      = "admin@your-company.com"

​
Optional Configuration

# Custom project name
project_name = "omni-workspace-integration"

# Exclude Gmail access
include_gmail_scope = false

# Don't create local key file (use secret manager instead)
output_key_file = false

# Specify billing account
billing_account_name = "My Billing Account"

​
Step 4: Run Terraform

terraform init
terraform plan    # Review what will be created
terraform apply   # Create resources
Review the terraform plan output carefully before applying. This will create resources in your Google Cloud organization.

​
What Terraform Creates

ResourceDescription
Google Cloud ProjectNew project with billing enabled
Service AccountWith domain-wide delegation capability
APIsAdmin SDK, Drive, Gmail, Docs, Sheets, Slides enabled
Service Account KeySaved locally for Omni configuration
Organization TagsFor project identification
Organization PolicyRestricts key creation to tagged projects

​
Step 5: Complete Manual Steps

After Terraform completes, you’ll need to complete two manual steps that cannot be automated due to Google’s security model.

​
5a. Configure Domain-Wide Delegation

  1. Open the Google Workspace Admin Console
  2. Navigate to Security → Access and data control → API controls
  3. Click Manage Domain Wide Delegation
  4. Click Add new
  5. Enter the Client ID from Terraform output
  6. Add the OAuth scopes from Terraform output:
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/drive.readonly,
https://www.googleapis.com/auth/gmail.readonly,
https://www.googleapis.com/auth/documents.readonly,
https://www.googleapis.com/auth/spreadsheets.readonly,
https://www.googleapis.com/auth/presentations.readonly
  1. Click Authorize
If Gmail scope is not needed, exclude https://www.googleapis.com/auth/gmail.readonly from the scopes and set include_gmail_scope = false in your Terraform configuration.

​
5b. Configure Omni

  1. Navigate to Settings → Integrations in Omni
  2. Find Google Workspace and click Connect
  3. Paste the contents of the service account key file (omni-service-account-key.json)
  4. Enter your Google Workspace domain
  5. Enter the admin email address
  6. Click Connect, and click Configure against either the Drive or Gmail source
  7. Choose which sources you want enabled, select any specific users to include/exclude, and click Save Configuration
  8. Wait for the initial sync to complete
Your Google Workspace connector is now configured. Initial indexing may take a while, depending on the amount of content in your Google account.

​
Manual Setup

If you prefer not to use Terraform, follow these steps to configure the Google Workspace connector manually.

​
Step 1: Create a Google Cloud Project

  1. Go to the Google Cloud Console
  2. Click Select a project → New Project
  3. Enter project name: omni-workspace-integration
  4. Select your organization
  5. Click Create

​
Step 2: Enable Required APIs

In your new project, enable these APIs: 
gcloud services enable admin.googleapis.com
gcloud services enable drive.googleapis.com
gcloud services enable gmail.googleapis.com
gcloud services enable docs.googleapis.com
gcloud services enable sheets.googleapis.com
gcloud services enable slides.googleapis.com
Or enable via Console: APIs & Services → Library → Search and enable each API.

​
Step 3: Create Service Account

  1. Go to IAM & Admin → Service Accounts
  2. Click Create Service Account
  3. Name: omni-workspace-connector
  4. Description: Service account for Omni Google Workspace integration
  5. Click Create and Continue
  6. Skip the optional steps and click Done

​
Step 4: Enable Domain-Wide Delegation

  1. Click on the newly created service account
  2. Go to Details tab
  3. Under Advanced settings, click Domain-wide Delegation
  4. Check Enable G Suite Domain-wide Delegation
  5. Click Save
  6. Note the Client ID displayed

​
Step 5: Create Service Account Key

  1. Go to the Keys tab
  2. Click Add Key → Create new key
  3. Select JSON format
  4. Click Create
  5. Save the downloaded key file securely
This key file provides access to your entire Google Workspace domain. Store it securely and never commit it to version control.

​
Step 6: Configure Domain-Wide Delegation in Admin Console

Follow the same steps as 5a in the automated setup.

​
Step 7: Configure Omni

Follow the same steps as 5b in the automated setup.

​
Managing the Integration

​
Viewing Sync Status

Navigate to Settings → Integrations → Google Workspace to view:
  • Last sync time
  • Number of indexed documents
  • Any sync errors

​
Rotating Service Account Keys

It’s recommended to rotate service account keys every 90 days. Using Terraform: 
terraform taint google_service_account_key.omni_sa_key
terraform apply
Manually:
  1. Create a new key in Google Cloud Console
  2. Update the key in Omni settings
  3. Delete the old key

​
Removing the Integration

Using Terraform: 
terraform destroy
Manually:
  1. Remove the connector in Omni settings
  2. Delete the service account in Google Cloud
  3. Remove the domain-wide delegation entry in Admin Console

​
Troubleshooting

List available billing accounts and update your configuration:
gcloud billing accounts list
Ensure you have the Billing Account Administrator role on the billing account.
Verify your authentication:
gcloud auth list
gcloud organizations list
You need Organization Administrator role for Terraform setup.
The setup requires these roles:
  • Organization Administrator - for org policies and tags
  • Project Creator - to create the GCP project
  • Billing Account User - to link billing
  • Google Workspace Super Admin - for domain-wide delegation
Some permissions may take 10-15 minutes to propagate.
APIs are enabled automatically but may take a few minutes to propagate. Check status:
gcloud services list --enabled --project=YOUR_PROJECT_ID
Common causes:
  • Client ID mismatch - verify the ID in Admin Console matches the service account
  • Missing scopes - ensure all required scopes are added
  • Propagation delay - wait 5-10 minutes for changes to take effect
  • Wrong admin email - ensure the admin email has Google Workspace admin privileges
Initial sync duration depends on:
  • Number of users in your organization
  • Amount of content in Drive and Gmail
  • API quota limits
For large organizations (1000+ users), initial sync may take 24-48 hours. You can monitor progress in the Omni admin panel.

​
Security Considerations

  • Read-only access: The service account only has read permissions
  • Permission inheritance: Users only see content they can access in Google Workspace
  • Key security: Service account keys should be treated like passwords
  • Audit logging: Enable Cloud Audit Logs to monitor API access
  • Key rotation: Rotate service account keys every 90 days

​
What’s Next

Search Your Data

Learn how to search across Google Workspace content

AI Assistant

Ask questions about your documents and emails

Add More Connectors

Connect additional data sources