OpenCoreDocuments & KnowledgeGoogle Drive

Google Drive Service Account

View as Markdown

Use this method when your organization manages Google Workspace access through a service identity. A Workspace administrator approves the delegation and scope, and an OpenCore Admin uploads and maintains the credential and selects or associates it when configuring the connector.

Prerequisites

Use Standard mode, because connectors and document indexing require it. You need a Google Cloud Project controlled by the organization, a Google Workspace administrator who can configure Domain-Wide Delegation, and the Primary Admin Email for the Workspace organization that owns the Drive content.

Create the Service Account

In the Google Cloud Project, create a Service Account and create a JSON Key for it. Keep the key secret and upload it only through the protected OpenCore Admin screen.

1{
2  "type": "service_account",
3  "project_id": "<google-cloud-project-id>",
4  "client_email": "<service-account>@<project-id>.iam.gserviceaccount.com",
5  "private_key": "<keep-this-secret-and-upload-it-only-in-the-admin-panel>"
6}

Record the Service Account OAuth client ID from Google Cloud. Domain-Wide Delegation uses that OAuth client ID, not the service account email address.

Configure Domain-Wide Delegation

In the Google Workspace Admin console, add the Service Account OAuth client ID to Domain-Wide Delegation and authorize only the scopes currently required by the Google Drive connector:

Minimum scopeWhy OpenCore requests it
https://www.googleapis.com/auth/drive.readonlyRead approved Google Drive content.
https://www.googleapis.com/auth/drive.metadata.readonlyRead Google Drive metadata used to discover and identify content.
https://www.googleapis.com/auth/admin.directory.group.readonlyRead Workspace group membership for permission synchronization.
https://www.googleapis.com/auth/admin.directory.user.readonlyRead Workspace users for permission synchronization.

Do not add broader scopes unless the deployed connector changes its documented requirements. The Service Account impersonates the configured Primary Admin Email when it accesses Google Workspace.

Add the credential to OpenCore

  1. Sign in to OpenCore as an Admin and open Documents & Knowledge.
  2. Select Google Drive, choose Service account, and upload the JSON Key.
  3. Enter the Primary Admin Email for an administrator or owner of the Google Workspace organization that owns the Drive content.
  4. Create the credential, then keep the key out of source control, Agent instructions, and shared documents.

Only Admins can upload, replace, or otherwise maintain the Service Account credential. The Admin also selects or associates that Google credential when configuring the connector; do not assume it is shared with other roles.

Configure indexing scope

Choose the narrowest approved scope when the Admin configures the connector.

AreaAvailable options
GeneralInclude Everyone’s My Drive and Include shared drives.
SpecificComma-separated lists of Shared Drive URLs, Folder URLs, and My Drive Emails. Indexed folders include all subfolders.
AdvancedSpecific User Emails, which indexes only files accessible to those users, and optional Hide domain link-only files.

The selected scope and the impersonated account’s Google Drive permissions both limit what the connector can read. Domain-Wide Delegation does not replace content-owner approval for indexing.

Verify the connector

Create a connector with one small, representative approved scope and run an index attempt. Review the attempt result, indexed document set, and any reported skipped files or errors before attaching the document set to an Agent or broadening the scope.

Troubleshooting

SymptomCheck and correct
JSON type is rejectedUpload a valid JSON Key whose type is service_account, not an OAuth Client JSON.
Primary Admin Email failsEnter an existing administrator or owner email for the Google Workspace organization that owns the selected content.
Delegation or Scope errorConfirm Domain-Wide Delegation uses the Service Account OAuth client ID and authorizes all four required scopes.
403 from Google WorkspaceVerify that the Primary Admin Email has directory access and that Domain-Wide Delegation is active for the Service Account.