OpenCoreDocuments & KnowledgeGmail

Gmail OAuth

View as Markdown

Use OAuth when an authorized person can complete Google browser consent for the Gmail account to be indexed. An OpenCore Admin uploads the OAuth app JSON and maintains the resulting credential.

Prerequisites

Use Standard mode. In a Google Cloud Project controlled by your organization, enable the Gmail API and Admin SDK API, configure the OAuth consent screen, and create a Web application OAuth client. The person authorizing OpenCore must be allowed to grant every requested scope.

Create the web OAuth client

Add this Authorized redirect URI exactly, replacing <WEB_DOMAIN> with the public base URL of the OpenCore deployment:

<WEB_DOMAIN>/admin/connectors/gmail/auth/callback

Download the OAuth client JSON. OpenCore expects the downloaded object to contain web.client_id and web.client_secret; the standard Google download also supplies the authorization and token endpoints.

1{
2  "web": {
3    "client_id": "<oauth-client-id>",
4    "project_id": "<google-cloud-project-id>",
5    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
6    "token_uri": "https://oauth2.googleapis.com/token",
7    "client_secret": "<oauth-client-secret>",
8    "redirect_uris": ["<WEB_DOMAIN>/admin/connectors/gmail/auth/callback"]
9  }
10}

Keep the file protected. Upload it only through the Gmail credential screen, and never place it in source control, Agent instructions, or a shared document.

Configure requested scopes

OpenCore currently requests these three read-only scopes for Gmail OAuth:

ScopeCurrent use
https://www.googleapis.com/auth/gmail.readonlyList threads and read messages from each mailbox account the connector processes.
https://www.googleapis.com/auth/admin.directory.user.readonlyAttempt to list user email addresses in the authorized Workspace domain.
https://www.googleapis.com/auth/admin.directory.group.readonlySupply read-only group-directory authorization required by the Google credential contract; Gmail thread access records remain mailbox-only.

The OAuth flow requests all three scopes. Directory user listing does not grant Gmail impersonation: the OAuth credential remains limited to the account that completed consent. Domain-wide mailbox coverage requires a Service Account with Domain-Wide Delegation.

Upload and authorize

  1. Sign in to OpenCore as an Admin and open Documents & Knowledge.
  2. Select Gmail, choose OAuth app, and upload or paste the OAuth client JSON.
  3. Select Authenticate with Gmail and complete Google’s consent flow with the account whose Gmail is approved for indexing.
  4. After the browser returns to OpenCore, confirm the credential appears in the credential list.

OpenCore reads the current Gmail profile after authorization and saves that email as the credential’s primary account. The OAuth credential can read only that account’s mailbox, even if the account is a Workspace administrator that can list Directory users. Domain-wide mailbox coverage requires a Service Account with Domain-Wide Delegation.

Verify the connector

Create a Gmail connector with an approved indexing start date. The default refresh frequency is 30 minutes and can be changed to another value of at least one minute. Run and review the first index attempt, confirm that only the expected mailbox threads are present, and inspect representative threads for usable plain-text content.

Troubleshooting

SymptomCheck and correct
OAuth JSON is rejectedUpload the Web application JSON with a web object containing string client_id and client_secret values.
Redirect URI mismatchConfigure <WEB_DOMAIN>/admin/connectors/gmail/auth/callback for the exact deployment that starts authorization.
Consent or missing-scope errorConfirm the consent screen requests all three documented scopes and that organization policy allows the OAuth client. Then authorize again.
Only one mailbox is indexedOAuth indexes one mailbox by design. To index the mailboxes of every Workspace user returned by the Admin SDK, use a Service Account with Domain-Wide Delegation.
Thread has headers but no bodyThe connector indexes text/plain MIME parts; an HTML-only message or an oversized plain-text part can contribute no body text.