fix(search): surface Google service account authorization errors (#7893)

* fix(search): surface Google service account authorization errors

* fix(search): preserve unrecognized Google token failures

* fix(search): handle delegated token errors during setup

* fix(search): clarify service account delegation guidance

Author: waleedlatif1

apps/docs/content/docs/search/gmail.mdx

@@ -84,6 +84,8 @@ Enter the Client ID and these exact scopes, separated by a comma:
 https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly
 ```
 
+For a key shared with Drive and Calendar, use the [combined six-scope list](/search/google-drive#one-service-account-for-drive-gmail-and-calendar).
+
 Select **Authorize**, then **View details** to confirm both scopes were saved. If the same client also indexes Drive or Calendar, retain those services' required scopes. These Gmail crawl scopes do not allow sending or modifying mail.
 
 If your organization requires multi-party approval, another super administrator must approve the request. Delegation can take up to 24 hours to propagate. See Google's [delegation guide](https://knowledge.workspace.google.com/admin/apps/control-api-access-with-domain-wide-delegation).

apps/docs/content/docs/search/google-calendar.mdx

@@ -86,6 +86,8 @@ Enter the Client ID and these exact comma-separated **OAuth scopes**:
 https://www.googleapis.com/auth/calendar.events.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly
 ```
 
+For a key shared with Drive and Gmail, use the [combined six-scope list](/search/google-drive#one-service-account-for-drive-gmail-and-calendar).
+
 Select **Authorize** and verify both scopes under **View details**. If you reuse a Drive or Gmail service account, retain its existing delegated scopes and add any missing Calendar scopes. An existing Drive authorization alone does not grant Calendar access. Delegation can take up to 24 hours to propagate; organizations requiring multi-party approval need another super administrator to approve the change. See [Google's delegation guide](https://knowledge.workspace.google.com/admin/apps/control-api-access-with-domain-wide-delegation).
 
 The **Directory administrator email** must be an active Workspace administrator with permission to read users. A super administrator has this permission; a custom administrator role can supply it. This identity lists the directory. Sim obtains a separate read-only Calendar token for each selected user; it does not read everyone's events as the administrator.

apps/docs/content/docs/search/google-drive.mdx

@@ -121,6 +121,16 @@ Invite teammates through **Settings → Members → Invite**, using their Google
 </Step>
 </Steps>
 
+## One service account for Drive, Gmail, and Calendar
+
+You can reuse one JSON key for all three central connectors. Authorize this combined list on the same numeric **Client ID**, and enable **Google Drive API**, **Gmail API**, **Google Calendar API**, and **Admin SDK API** in its Cloud project:
+
+```text
+https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/calendar.events.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly
+```
+
+Under **View details**, verify all six scopes are saved. Gmail and Calendar succeeding does not verify Drive's group and domain permissions. Each connector still needs its own source configuration in Sim.
+
 ## Source options
 
 An admin opens **Settings → Sources → Google Drive** to open its configuration list. Each row shows **Member accounts** or **Service account** beside its sync status. Open a connection's **Settings** tab to edit its filters, then select **Save**. **Documents** shows indexed files and **Sync history** shows recent runs.
@@ -147,6 +157,7 @@ Search schedules syncs hourly. Central crawls revisit the selected users' files
 
 | Problem | Next step |
 | --- | --- |
+| Google rejects authorization (`unauthorized_client`) | In **Manage Domain Wide Delegation**, verify the numeric **Client ID** matches `client_id` in the JSON key uploaded to Sim and all required scopes appear under **View details**. Check pending approval and allow time for recent changes to propagate. Changing the OAuth consent screen alone does not authorize delegation. |
 | Directory access failed | Check all four delegated scopes and the **Directory administrator email** user's administrator privileges. A normal Google OAuth credential cannot supply this central Search path. |
 | Missing files in a central crawl | Check **Users**, folder and file-type filters, and whether selected active Workspace users can download the file and read its permissions. Opening a file alone does not prove either. Check Sync history for errors. Files reachable only by excluded or inactive accounts are not crawled; files with unverified permissions stay hidden. |
 | User not found or inactive | Use a primary email in the same Google Workspace customer. Aliases, external or guest accounts, suspended users, and archived users cannot be selected for crawling. |

apps/sim/lib/knowledge/application/connectors.test.ts

@@ -107,6 +107,15 @@ vi.mock('@/lib/credentials/application/organization-credentials', () => ({
 }))
 
 vi.mock('@/lib/oauth/credential-service', () => ({
+  ServiceAccountTokenError: class extends Error {
+    constructor(
+      readonly statusCode: number,
+      readonly errorDescription: string,
+      readonly errorCode?: string
+    ) {
+      super(errorDescription)
+    }
+  },
   resolveCredentialTokenBundle: mocks.resolveTokenBundle,
   resolveOAuthAccountId: vi.fn(async () => null),
   getServiceAccountToken: vi.fn(),
@@ -145,6 +154,7 @@ vi.mock('@/connectors/registry.server', () => ({
           'https://www.googleapis.com/auth/admin.directory.group.readonly',
           'https://www.googleapis.com/auth/admin.directory.domain.readonly',
         ],
+        serviceAccountDelegationScopes: ['https://www.googleapis.com/auth/drive.readonly'],
         serviceAccountSubjectFieldId: 'adminEmail',
       },
       validateConfig: mocks.validateConnectorConfig,
@@ -167,11 +177,20 @@ import {
   updateKnowledgeConnectorDocuments,
   validateConnectorSourceConfig,
 } from '@/lib/knowledge/application/connectors'
+import type { ConnectorAccessToken } from '@/lib/knowledge/connectors/access-token'
 import { MAX_KNOWLEDGE_CONNECTOR_DOCUMENT_SEARCH_LENGTH } from '@/lib/knowledge/constants'
+import { classifyKnowledgeFailure } from '@/lib/knowledge/orchestration/shared'
+import {
+  getServiceAccountToken,
+  resolveOAuthAccountId,
+  ServiceAccountTokenError,
+} from '@/lib/oauth/credential-service'
 import * as githubInstallation from '@/lib/oauth/github-installation'
 import { capabilityRefusal } from '@/lib/permission-groups/capability-assertions'
 import { DEFAULT_PERMISSION_GROUP_CONFIG } from '@/lib/permission-groups/fields'
 import { confluenceConnectorMeta } from '@/connectors/confluence/meta'
+import { gmailConnectorMeta } from '@/connectors/gmail/meta'
+import { googleCalendarConnectorMeta } from '@/connectors/google-calendar/meta'
 import { googleDriveConnectorMeta } from '@/connectors/google-drive/meta'
 
 const crossWorkspaceContext = {
@@ -1624,6 +1643,240 @@ describe('organization connector credential authorization', () => {
     expect(mocks.resolveTokenBundle).not.toHaveBeenCalled()
   })
 
+  it.each([googleDriveConnectorMeta, gmailConnectorMeta, googleCalendarConnectorMeta])(
+    'projects $name token rejections as safe setup errors',
+    async ({ auth }) => {
+      mocks.resolveTokenBundle.mockRejectedValueOnce(
+        new ServiceAccountTokenError(401, 'private provider payload', 'unauthorized_client')
+      )
+      const error = await resolveConnectorCredentialAccessToken({ ...input, auth }).catch(
+        (error: unknown) => error
+      )
+      expect(error).toBeInstanceOf(OrchestrationError)
+      expect(internalOrchestrationErrorPolicy.project(error)).toMatchObject({
+        status: 400,
+        body: { error: expect.stringContaining('(unauthorized_client)') },
+      })
+      expect((error as Error).message).toContain('numeric client ID')
+      expect((error as Error).message).toContain(
+        "exact domain-wide delegation scopes in this connector's service-account setup section"
+      )
+      expect((error as Error).message).not.toContain('private provider payload')
+      expect(mocks.authorizeOrganizationCredentialUse).toHaveBeenCalledOnce()
+    }
+  )
+
+  it.each([
+    [400, 'invalid_grant', 'JSON key'],
+    [
+      400,
+      'invalid_scope',
+      "exact domain-wide delegation scopes in this connector's service-account setup section",
+    ],
+    [403, 'access_denied', 'API access policies'],
+  ])('classifies Google %s %s without exposing provider text', async (status, code, guidance) => {
+    mocks.resolveTokenBundle.mockRejectedValueOnce(
+      new ServiceAccountTokenError(status, 'private provider payload', code)
+    )
+    const error = await resolveConnectorCredentialAccessToken(input).catch(
+      (error: unknown) => error
+    )
+    expect(error).toMatchObject({ code: 'validation', message: expect.stringContaining(guidance) })
+    expect((error as Error).message).not.toContain('private provider payload')
+  })
+
+  it.each([googleDriveConnectorMeta, gmailConnectorMeta, googleCalendarConnectorMeta])(
+    'maps $name delegated token failures after directory authorization succeeds',
+    async ({ auth }) => {
+      vi.mocked(resolveOAuthAccountId).mockResolvedValueOnce({
+        accountId: '',
+        usedCredentialTable: true,
+        credentialId: credential.id,
+        credentialType: 'service_account',
+        providerId: credential.providerId,
+      })
+      vi.mocked(getServiceAccountToken).mockRejectedValueOnce(
+        new ServiceAccountTokenError(401, 'private delegated response', 'unauthorized_client')
+      )
+      const resolved = await resolveConnectorCredentialAccessToken({ ...input, auth })
+      expect(resolved?.accessToken).toBe('organization-token')
+      expect(getServiceAccountToken).not.toHaveBeenCalled()
+      if (!resolved?.getDelegatedAccessToken) throw new Error('Expected delegated token resolver')
+      await expect(resolved.getDelegatedAccessToken('member@example.com')).rejects.toMatchObject({
+        code: 'validation',
+        message: expect.stringContaining('(unauthorized_client)'),
+      })
+      expect(getServiceAccountToken).toHaveBeenCalledWith(
+        credential.id,
+        auth.mode === 'oauth' ? auth.serviceAccountDelegationScopes : undefined,
+        'member@example.com'
+      )
+    }
+  )
+
+  it('preserves successful delegated token reads and unexpected failures', async () => {
+    vi.mocked(resolveOAuthAccountId).mockResolvedValueOnce({
+      accountId: '',
+      usedCredentialTable: true,
+      credentialId: credential.id,
+      credentialType: 'service_account',
+      providerId: credential.providerId,
+    })
+    const resolved = await resolveConnectorCredentialAccessToken(input)
+    if (!resolved?.getDelegatedAccessToken) throw new Error('Expected delegated token resolver')
+    vi.mocked(getServiceAccountToken).mockResolvedValueOnce('delegated-token')
+    await expect(resolved.getDelegatedAccessToken('member@example.com')).resolves.toBe(
+      'delegated-token'
+    )
+    for (const error of [
+      new ServiceAccountTokenError(401, 'private delegated response', 'unknown-code'),
+      new ServiceAccountTokenError(503, 'private delegated response', 'unauthorized_client'),
+      new TypeError('Network request failed'),
+    ]) {
+      vi.mocked(getServiceAccountToken).mockRejectedValueOnce(error)
+      await expect(resolved.getDelegatedAccessToken('member@example.com')).rejects.toBe(error)
+    }
+  })
+
+  it('passes safe delegated errors to configuration validation', async () => {
+    vi.mocked(resolveOAuthAccountId).mockResolvedValueOnce({
+      accountId: '',
+      usedCredentialTable: true,
+      credentialId: credential.id,
+      credentialType: 'service_account',
+      providerId: credential.providerId,
+    })
+    vi.mocked(getServiceAccountToken).mockRejectedValueOnce(
+      new ServiceAccountTokenError(401, 'private delegated response', 'unauthorized_client')
+    )
+    mocks.validateConnectorConfig.mockImplementationOnce(
+      async (_token: string, _config: unknown, context: ConnectorAccessToken) => {
+        if (!context.getDelegatedAccessToken) throw new Error('Expected delegated token resolver')
+        try {
+          await context.getDelegatedAccessToken('member@example.com')
+          return { valid: true }
+        } catch (error) {
+          if (!(error instanceof Error)) throw error
+          return { valid: false, error: error.message }
+        }
+      }
+    )
+    const rejection = await validateConnectorSourceConfig({
+      principal,
+      organizationId: 'org',
+      actingUserId: principal.userId,
+      requestId: 'request',
+      sourceConfig: input.sourceConfig,
+      connector: {
+        connectorType: 'google_drive',
+        credentialId: credential.id,
+        encryptedApiKey: null,
+        accessMode: 'admin',
+      } as Parameters<typeof validateConnectorSourceConfig>[0]['connector'],
+    })
+    expect(rejection).toMatchObject({
+      errorCode: 'validation',
+      message: expect.stringContaining('(unauthorized_client)'),
+    })
+    expect(rejection?.message).not.toContain('private delegated response')
+  })
+
+  it.each([400, 401, 403])(
+    'preserves unrecognized Google %s responses instead of assuming a configuration error',
+    async (status) => {
+      for (const code of [undefined, 'unknown-private-code', 'server_error']) {
+        const error = new ServiceAccountTokenError(status, 'private provider payload', code)
+        mocks.resolveTokenBundle.mockRejectedValueOnce(error)
+        await expect(resolveConnectorCredentialAccessToken(input)).rejects.toBe(error)
+        expect(internalOrchestrationErrorPolicy.project(error)).toBeNull()
+      }
+    }
+  )
+
+  it.each([429, 500, 503])(
+    'preserves Google %s failures instead of blaming configuration',
+    async (status) => {
+      const error = new ServiceAccountTokenError(status, 'private provider payload', 'server_error')
+      mocks.resolveTokenBundle.mockRejectedValueOnce(error)
+      await expect(resolveConnectorCredentialAccessToken(input)).rejects.toBe(error)
+      expect(internalOrchestrationErrorPolicy.project(error)).toBeNull()
+    }
+  )
+
+  it('preserves unexpected token failures as internal errors', async () => {
+    const error = new TypeError('private network failure')
+    mocks.resolveTokenBundle.mockRejectedValueOnce(error)
+    await expect(resolveConnectorCredentialAccessToken(input)).rejects.toBe(error)
+    expect(internalOrchestrationErrorPolicy.project(error)).toBeNull()
+  })
+
+  it('keeps authorization errors actionable through connector creation orchestration', async () => {
+    queueTableRows(member, [{ role: 'admin' }])
+    queueTableRows(member, [{ role: 'admin' }])
+    mocks.resolveKnowledgeBase.mockResolvedValue({
+      organizationId: 'org',
+      knowledgeBaseId: 'org-index',
+      knowledgeBase: { id: 'org-index', name: 'Search', isSearchIndex: true },
+    })
+    mocks.resolveTokenBundle.mockRejectedValueOnce(
+      new ServiceAccountTokenError(401, 'private provider payload', 'unauthorized_client')
+    )
+    mocks.createConnector.mockImplementationOnce(
+      async (createInput: { resolveAccessToken(id: string): Promise<unknown> }) => {
+        try {
+          await createInput.resolveAccessToken(credential.id)
+          throw new Error('Unexpected successful token exchange')
+        } catch (error) {
+          return classifyKnowledgeFailure(error, 'request', 'Create connector')
+        }
+      }
+    )
+    const error = await createKnowledgeConnector
+      .execute({
+        principal,
+        input: {
+          knowledgeBaseId: 'org-index',
+          assertedOrganizationId: 'org',
+          connectorType: 'google_drive',
+          credentialId: credential.id,
+          accessMode: 'admin',
+          sourceConfig: input.sourceConfig,
+          syncIntervalMinutes: 60,
+        },
+      })
+      .catch((error: unknown) => error)
+    expect(internalOrchestrationErrorPolicy.project(error)).toMatchObject({
+      status: 400,
+      body: { error: expect.stringContaining('(unauthorized_client)') },
+    })
+    expect(mocks.recordAudit).not.toHaveBeenCalled()
+  })
+
+  it('returns an actionable error before saving a configuration edit', async () => {
+    mocks.resolveTokenBundle.mockRejectedValueOnce(
+      new ServiceAccountTokenError(401, 'private provider payload', 'unauthorized_client')
+    )
+    await expect(
+      validateConnectorSourceConfig({
+        principal,
+        organizationId: 'org',
+        actingUserId: principal.userId,
+        requestId: 'request',
+        sourceConfig: input.sourceConfig,
+        connector: {
+          connectorType: 'google_drive',
+          credentialId: credential.id,
+          encryptedApiKey: null,
+          accessMode: 'admin',
+        } as Parameters<typeof validateConnectorSourceConfig>[0]['connector'],
+      })
+    ).rejects.toMatchObject({
+      code: 'validation',
+      message: expect.stringContaining('(unauthorized_client)'),
+    })
+    expect(mocks.validateConnectorConfig).not.toHaveBeenCalled()
+  })
+
   it('does not mint a token after the credential creator leaves the organization', async () => {
     mocks.resolveTokenIdentity.mockResolvedValueOnce(null)
     await expect(resolveConnectorCredentialAccessToken(input)).resolves.toBeNull()