Google Workspace

​

Overview

​

What Gets Indexed

​

How It Works

1. Organization-wide sources use a service account with domain-wide delegation; a plain service account can sync selected shared drives directly (see Service Account Direct (Shared Drives)). Personal connections use the user’s Google OAuth authorization.
2. The connector syncs content within the configured Drive scope and source permissions
3. Permission inheritance ensures users only see content they have access to in Google Workspace

​

Prerequisites

• Google Cloud Platform account with billing enabled
• Google Workspace admin access (Super Admin or delegated admin)
• Google Cloud CLI (gcloud) installed and authenticated (optional, for enabling APIs via CLI)

​

Setup

​

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

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
gcloud services enable chat.googleapis.com

​

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: Get the Client ID

1. Click on the newly created service account
2. Go to the Details tab
3. Under Advanced settings, copy the Client ID (also shown as the service account’s Unique ID) — you’ll need this in Step 6 to authorize domain-wide delegation

​

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

​

Step 6: Configure Domain-Wide Delegation in Admin Console

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 Step 4
6. Add the following OAuth scopes:

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,
https://www.googleapis.com/auth/chat.spaces.readonly,
https://www.googleapis.com/auth/chat.memberships.readonly,
https://www.googleapis.com/auth/chat.admin.memberships.readonly,
https://www.googleapis.com/auth/chat.messages.readonly

7. Click Authorize

​

Step 7: Configure Omni

1. Navigate to Settings → Integrations in Omni
2. Find Google Workspace and click Connect
3. Choose whether to create Google Drive, Gmail, Google Chat, or any combination of those sources
4. Paste the contents of the service account key file from Step 5
5. Enter your Google Workspace domain
6. Enter the admin email address
7. Click Connect
8. Use Settings on each created source to adjust source settings, then click Sync to start the initial sync

​

Personal Google OAuth

​

Service Account Direct (Shared Drives, no Domain-Wide Delegation)

​

Google-Side Setup

1. Create a service account key (IAM & Admin → Service Accounts → Keys)
2. Ensure the service account itself can list Workspace groups and group members through the Admin SDK without impersonation, for example through an appropriate customer-level admin role. Omni validates this access before creating the source
3. In each shared drive → Manage members, add the service account email (<name>@<project>.iam.gserviceaccount.com) as Content manager (fileOrganizer) or Manager (organizer). Without one of these roles the service account cannot read the drive’s ACLs, and the connector will not sync the drive
4. Verify your Workspace external-sharing policy permits adding *.iam.gserviceaccount.com to shared drives. The service account is an external principal, so a scoped OU / trust-rule exception may be needed. If the policy cannot allow the service account at all, use OAuth or domain-wide delegation instead

​

Behavior

• drive.readonly and admin.directory.group.readonly are required; the source config selects this mode with auth_mode: "service_account_direct", a Workspace domain, and one or more folder_path_filters entries of kind shared_drive_root
• The drive member list supplies each document’s baseline public/users/groups permissions; the service account’s own email is excluded
• Effective permissions mirror Google’s shared-drive model: direct grants on ancestor folders and files are added, and a limited-access folder boundary replaces inherited access with drive organizers plus direct grants at that boundary
• Drive and relevant folder ACLs are fingerprinted; a change triggers a full drive re-traversal so existing documents get the new permissions
• Polling only; no webhook registration. Google Groups on the drive map to groups. Setup verifies that the service account can list Workspace groups and members, and the connector emits group-membership events during sync. If group sync later fails, group-granted documents are visible only to users whose memberships are supplied by another source
• Switching an existing domain-wide-delegation source to service-account-direct is not supported; create a new source instead

​

Managing the Integration

​

Gmail Attachments

​

Google Chat

​

Drive Folder Filtering

• Domain-wide delegation: Admins can select shared drives or folders within them. If no folders are selected, all content available through the source is indexed. Personal My Drive folder scopes are not supported for service-account sources; use personal OAuth instead.
• Personal Google OAuth: The account owner can choose Entire Drive or selected folders from My Drive and accessible shared drives. The owner manages this scope from My Integrations.
• Service-account direct: The source must select at least one whole shared drive. Folder-level restrictions are not supported in this mode.

​

User OAuth for Tools

​

AI Tools and Skills

• google_workspace_schema — fetches API method schemas so the assistant can discover available operations and their parameters
• google_workspace_call — executes API calls against Drive, Docs, Sheets, Slides, and Gmail

• Google Drive skill — search and read files, manage permissions, create and update Docs/Sheets/Slides via the API
• Gmail skill — search, read, and manage messages and threads with Gmail query syntax

​

Viewing Sync Status

​

Rotating Service Account Keys

1. Create a new key in Google Cloud Console
2. Update the key in Omni settings
3. Delete the old key

​

Removing the Integration

1. Navigate to Settings → Integrations
2. Click Settings against the Google Workspace source
3. Click Delete Permanently
4. Optionally, delete the service account in Google Cloud and remove the domain-wide delegation entry in Admin Console

​

Troubleshooting

gcloud services list --enabled --project=YOUR_PROJECT_ID

​

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