OpenCoreDocuments & KnowledgeGmail

Gmail Service Account

View as Markdown

Use a Service Account when a Google Workspace organization centrally approves mailbox indexing. A Workspace administrator configures Domain-Wide Delegation, and an OpenCore Admin uploads the key and provides the Primary Admin Email.

Prerequisites

Use Standard mode. You need a Google Cloud Project controlled by the organization, the Gmail API and Admin SDK API enabled in that project, a Google Workspace administrator who can configure Domain-Wide Delegation, and an approved administrator or owner account in the Workspace organization.

Create the Service Account

Create a Service Account in Google Cloud, enable Domain-Wide Delegation for it, and create a JSON key. OpenCore requires a JSON object whose type is service_account.

1{
2  "type": "service_account",
3  "project_id": "<google-cloud-project-id>",
4  "private_key_id": "<service-account-key-id>",
5  "private_key": "<service-account-private-key>",
6  "client_email": "<service-account-email>",
7  "client_id": "<service-account-oauth-client-id>",
8  "token_uri": "https://oauth2.googleapis.com/token"
9}

Keep the key secret. Record the Service Account OAuth client ID separately; the Workspace delegation entry uses this numeric client ID, not the Service Account email.

Configure Domain-Wide Delegation

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

ScopeCurrent use
https://www.googleapis.com/auth/gmail.readonlyImpersonate every Workspace user returned by the Admin SDK to list threads and read messages.
https://www.googleapis.com/auth/admin.directory.user.readonlyImpersonate the Primary Admin Email to list user email addresses in the 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 do not receive group IDs.

Do not copy Google Drive scopes into this delegation. The Gmail connector does not request Drive content or metadata access.

Add the credential to OpenCore

  1. Sign in to OpenCore as an Admin and open Documents & Knowledge.
  2. Select Gmail, choose Service account, and upload or paste the Service Account JSON key.
  3. Enter the Primary Admin Email for an administrator or owner in the Google organization that owns the Gmail accounts approved for indexing.
  4. Create the credential, confirm it appears in the credential list, and select it when creating the Gmail connector.

The Primary Admin Email is used for Admin SDK directory access. After the connector lists Workspace users, the Service Account impersonates each returned user when it reads that user’s Gmail threads.

Account coverage and permission sync

With working Domain-Wide Delegation and directory permissions, the connector processes the user addresses returned for the Primary Admin Email’s Workspace domain. A 403 or 404 from the directory list causes the implementation to fall back to the configured Primary Admin Email, so confirm account coverage from the actual index result.

Every indexed thread is non-public and carries the mailbox used to fetch it as its only external user access. Message recipients and Workspace groups are not added to that access entry. When Gmail permission synchronization runs, it refreshes this same mailbox-only record for threads returned in its time window.

Verify updates

Create a Gmail connector with an approved indexing start date and a representative mailbox boundary. The default refresh frequency is 30 minutes and can be changed to another value of at least one minute. Run the first index attempt and verify the expected accounts, threads, and plain-text content before attaching the document set to an Agent.

Creating another Service Account or OAuth credential preserves the existing Gmail credentials. Keep separate credentials for separate Workspace organizations or approval boundaries, and check the selected credential before running an index attempt.

Troubleshooting

SymptomCheck and correct
JSON type is rejectedUpload a valid key whose type is service_account, not a Web OAuth client JSON.
Cannot impersonate a userConfirm Domain-Wide Delegation is enabled for the Service Account and uses its OAuth client ID. Verify that the user still exists and has Gmail enabled.
Directory or missing-scope errorAuthorize all three Gmail connector scopes in the Workspace delegation entry and verify that the Primary Admin Email can list users.
Only the Primary Admin Email is indexedThe directory user list returned 403 or 404. Correct Admin SDK access and delegation, then run a new index attempt.
A user’s mailbox is skippedThe connector skips a mailbox when Gmail reports that mail service is not enabled for that user. Confirm the account has a provisioned Gmail mailbox.
  • Gmail Overview explains indexed content, account coverage, updates, and permission boundaries.
  • Gmail OAuth covers browser-based authorization with an uploaded OAuth app JSON.
  • Connectors & Indexing explains document sets and index attempts.