Google Drive OAuth | Alephant Documentation

Use this method when an authorized person can complete browser-based consent for the Google Drive content being indexed. Only an OpenCore Admin can upload or maintain the saved OAuth credential; it does not give Agents direct access to Google Drive.

Prerequisites

Use Standard mode, because connectors and document indexing require it. An Admin needs access to the OpenCore Google Drive credential screen, and the Google account owner must approve the intended content and indexing scope. Curators cannot access the credential controls.

In Google Cloud, use a project your organization controls. Enable the Google Drive API and prepare a web OAuth client for that project.

Create the OAuth app

Configure the OAuth consent screen in the Google Cloud Project, then create a web OAuth client. Add this Authorized redirect URI exactly, replacing <WEB_DOMAIN> with the public base URL of your OpenCore deployment:

<WEB_DOMAIN>/admin/connectors/google-drive/auth/callback

Download the OAuth Client JSON for that web client. Keep the downloaded file protected; it contains the client configuration OpenCore uses only while completing the authorization flow.

OAuth scopes and data access

In the Google Cloud OAuth consent screen configuration, add these four read-only scopes under Data Access. The consent shown to the authorizing person is based on this configuration; the selected connector scope and the account’s existing permissions still determine which Drive content is indexed.

OAuth scope	Purpose
`https://www.googleapis.com/auth/drive.readonly`	Read approved Drive file content that the authorizing account can access.
`https://www.googleapis.com/auth/drive.metadata.readonly`	Read Drive file and folder metadata used to discover, filter, and index the selected scope.
`https://www.googleapis.com/auth/admin.directory.group.readonly`	Read Google Workspace group metadata needed to resolve group-based access.
`https://www.googleapis.com/auth/admin.directory.user.readonly`	Read Google Workspace user metadata needed to resolve user-based access.

All four scopes are read-only. Consent grants data access to the connector; it does not let OpenCore modify Drive content or expand the Google account’s underlying permissions. A Google Workspace organization’s app access policy may separately need to allow this OAuth client before its users can complete consent.

Upload and authorize

Sign in to OpenCore as an Admin and open Documents & Knowledge.
Select Google Drive, choose OAuth app, and upload the OAuth Client JSON from the Google Cloud Project.
Select Authenticate with Google Drive. The browser opens Google’s authorization flow.
Sign in with the Google account whose approved Drive content will be indexed, review the requested access, and complete consent.

After the browser returns to OpenCore, confirm as an Admin that the credential appears as authenticated. If the account, consent screen, redirect URI, or uploaded client does not match, start a new authorization flow after correcting the configuration.

Only Admins can upload, replace, re-authorize, or otherwise maintain the 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 you create the connector.

Area	Available options
General	Include My Drive, Include shared drives, and Include All Files Shared With You.
Specific	Comma-separated lists of Shared Drive URLs and Folder URLs. Indexed folders include all subfolders.
Advanced	Optional Hide domain link-only files, which skips files shared broadly to a domain or publicly but requiring the link for access.

The selected scope and the Google account’s permissions both limit what the connector can read. Expanding a connector scope does not grant the account new Google Drive access.

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

Symptom	Check and correct
Redirect URI mismatch	Confirm that the Google Cloud web client has exactly `<WEB_DOMAIN>/admin/connectors/google-drive/auth/callback` for the deployment that started the flow.
Scope is missing from consent	In the Google Cloud OAuth consent screen, confirm that Data Access contains `drive.readonly`, `drive.metadata.readonly`, `admin.directory.group.readonly`, and `admin.directory.user.readonly`; save the consent configuration, then re-authorize.
App is blocked by Workspace policy	Ask a Google Workspace administrator to check the organization’s app access policy and allow the OAuth client when required, then re-authorize.
Account cannot access content	Sign in with an account that has Google Drive permission for the selected My Drive, Shared Drive, file, or folder.
Authorization was revoked	Re-run browser authorization with the approved account, then run a new index attempt.

Google Drive Overview compares authentication methods and indexing scopes.
Google Drive Service Account covers organization-managed access through Domain-Wide Delegation.
Connectors & Indexing explains document sets and index attempts.