PSA/ee/docs/plans/2026-01-04-tenant-owned-google-oauth/PRD.md

Tenant-Owned Google OAuth (Calendar + Inbound Gmail)

Summary

Switch Google integrations from Alga’s shared, multi-tenant Google OAuth app to tenant-owned Google Cloud OAuth credentials. Each tenant supplies their own OAuth Client ID/Secret (and required GCP configuration) to automate their own Google accounts. This removes Alga’s dependency on Google’s intensive verification/review for a single shared app.

Scope includes:

• Google Calendar integration
• Google inbound email (Gmail) integration

We will not migrate existing configurations. Tenants must reconfigure under the new model.

Problem Statement

Today Google integrations rely on Alga-managed OAuth credentials in some environments/flows (notably “hosted” logic), creating:

• Vendor compliance/review burden and delays for Alga.
• Higher operational and legal risk for a centralized multi-tenant app.
• Tenant friction when Alga’s app must be re-verified, rotated, or constrained.

Goals

• Tenants can configure Google integrations using their own Google Cloud OAuth app credentials.
• OAuth client credentials are stored using the Secrets Provider as tenant-level secrets (never stored in plain DB columns).
• Provide a dedicated Google setup area in UI with in-context guidance to complete required Google Cloud Console steps.
• Update Google Calendar and Gmail setup screens to use the tenant’s stored credentials and to select the appropriate tenant Google configuration.
• Use the same tenant-provided configuration model in both hosted and on-prem (CE vs EE): tenant secrets are the source of truth in all deployments.
• Remove/ignore existing Alga Google app infrastructure paths (fresh cutover).

Non-Goals

• Migrating existing Google provider configs, tokens, or Pub/Sub resources.
• Supporting Alga-owned Google OAuth credentials as a fallback for production/hosted environments.
• Redesigning OAuth scopes beyond what’s already required by current integrations.
• Consolidating the integrations into a single OAuth callback URL (we will keep existing callback routes unless decided otherwise).

Users / Personas

• Tenant Admin: configures integrations for their organization (OAuth app creation, secrets, service accounts).
• Technician / Scheduler: connects their Google Calendar (per-user calendar provider).
• Helpdesk Operator: relies on inbound email providers to create tickets from a mailbox.

Current-State Notes (as observed in repo)

Inbound Gmail

• UI: server/src/components/GmailProviderForm.tsx collects projectId, clientId, clientSecret, redirectUri and persists these via server/src/lib/actions/email-actions/emailProviderActions.ts.
• Tokens saved on callback: server/src/app/api/auth/google/callback/route.ts updates google_email_provider_config with access_token, refresh_token, token_expires_at.
• “Hosted” credential selection exists: server/src/lib/actions/email-actions/oauthActions.ts + callback route choose app-level secrets when NEXTAUTH_URL indicates hosted.
• Pub/Sub setup: server/src/lib/actions/email-actions/setupPubSub.ts currently reads service account JSON from an app secret (google_service_account_key), while docs suggest tenant-level (docs/inbound-email/setup/gmail.md).

Google Calendar

• UI: server/src/components/calendar/GoogleCalendarProviderForm.tsx creates a provider and runs OAuth via server/src/lib/actions/calendarActions.ts and callback server/src/app/api/auth/google/calendar/callback/route.ts.
• “Hosted” credential selection exists for calendar OAuth (similar detection via NEXTAUTH_URL).
• Calendar adapter token refresh can use tenant secrets (server/src/services/calendar/providers/GoogleCalendarAdapter.ts) if credentials not stored in provider config.
• Pub/Sub verification job exists (verify-google-calendar-pubsub) but Google calendar Pub/Sub setup appears incomplete/no-op in GoogleCalendarAdapter.registerWebhookSubscription().

Proposed Solution

1) Add a dedicated “Google” setup area

Add a new Settings area under Settings → Integrations → Communication:

• “Google” panel (or “Google Cloud”) that lets tenant admins:
  • Enter Google Cloud project ID (used for Gmail Pub/Sub; also used by calendar if/when calendar Pub/Sub is implemented).
  • Enter OAuth Client ID and OAuth Client Secret for:
    • Gmail inbound email (scopes include Gmail readonly + Pub/Sub) or
    • Calendar (scope includes Calendar)
  • Default to “Use the same OAuth app for Gmail + Calendar” and apply the same client credentials to both (while still allowing separate credentials if desired).
  • Upload/enter service account key JSON used for Pub/Sub provisioning (Gmail). Store via tenant secrets.
  • See the required redirect URIs and scopes directly in the UI:
    • Redirect URIs:
      • ${BASE_URL}/api/auth/google/callback
      • ${BASE_URL}/api/auth/google/calendar/callback
    • Scopes (current):
      • Gmail: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/pubsub
      • Calendar: https://www.googleapis.com/auth/calendar
  • Validate and show a status summary (configured / missing fields), and show masked client ID.

Redirect URIs:

• ${BASE_URL} is canonical across deployments; we do not need tenant-configurable redirect URI overrides.

2) Store configuration in tenant secrets (Secrets Provider)

Store all sensitive values as tenant secrets, not app secrets:

• google_client_id, google_client_secret (Gmail OAuth)
• google_calendar_client_id, google_calendar_client_secret (Calendar OAuth)
• google_project_id and/or google_calendar_project_id (if still needed by codepaths)
• google_service_account_key (JSON string for Pub/Sub provisioning)

Exact secret keys should align with existing code expectations where possible to minimize change surface.

3) Update integration setup screens

Gmail provider setup (Inbound Email)

Update GmailProviderForm to:

• Stop asking for OAuth Client ID/Secret in the provider form (those come from tenant Google setup).
• Stop persisting OAuth Client ID/Secret into google_email_provider_config DB columns (keep schema, but do not rely on it).
• Continue to ask for mailbox, provider name, label filters, defaults, etc.
• Surface a “Google not configured” state with a CTA link to the Google setup panel if required secrets are missing.
• OAuth initiation must use tenant secrets (even in hosted environments).

Google Calendar provider setup

Update GoogleCalendarProviderForm to:

• Surface which tenant Google configuration it will use (and show missing-config CTA if not configured).
• Ensure OAuth initiation + callback use tenant secrets consistently.
• If the tenant chooses separate credentials for Calendar vs Gmail, the form should use the calendar ones.
• Ensure Google Calendar update callbacks are configured so Alga receives calendar change notifications.

4) Remove/disable hosted-app credential paths for Google

For Google (only), eliminate “hosted uses app secrets” branching so hosted environments do not depend on Alga-owned Google OAuth credentials.

5) Fresh cutover, no migration

Existing Google provider records may remain in DB, but:

• Existing provider records should be reset back to an initial/disconnected state to avoid confusing “connected” UI on legacy credentials/tokens.
• We won’t attempt to migrate tokens/config; tenants re-authorize after configuring tenant secrets.

Google Calendar callbacks

We should configure Google Calendar change notifications so Alga receives callbacks and triggers a delta sync.

Current implementation expectation in code:

• Google Calendar notifications arrive as Pub/Sub push to POST /api/calendar/webhooks/google (server/src/app/api/calendar/webhooks/google/route.ts).
• CalendarWebhookProcessor.processGoogleWebhook() locates the provider using the Pub/Sub subscription name and then performs a delta sync using the provider’s sync token.

Required work:

• Provision the Google-side notification pipeline end-to-end so calendar updates publish into the tenant’s Pub/Sub topic/subscription (or, if Pub/Sub is not feasible for Calendar notifications, pivot to native Calendar push channels and refactor the webhook processor accordingly).

Background maintenance (Google)

Microsoft mail/calendar already have scheduled renewal via the job runner abstraction (PG Boss in CE, Temporal in EE). We should add similar maintenance for Google:

• Gmail: refresh/renew Gmail watch subscriptions before watch_expiration and surface failures as provider errors.
• Calendar: verify/repair the calendar notification pipeline so callbacks continue to arrive; surface failures as provider errors.
• Tokens: proactively refresh access tokens nearing expiry (best-effort) to detect broken refresh tokens early and reduce webhook processing failures.

UX / UI Notes

• The Google setup panel must include concise, step-by-step instructions:
  • Create/choose a Google Cloud project.
  • Enable required APIs (Gmail API, Google Calendar API, Pub/Sub API).
  • Configure OAuth consent screen (Internal/External depending on tenant).
  • Create OAuth Client ID (Web application) and add redirect URIs.
  • Create a service account and grant Pub/Sub admin (or specific permissions) for provisioning.
  • Provide the Gmail push service account publisher role guidance (as done in setup code) and/or link to docs.
• Show “copy” buttons for redirect URIs and scopes.
• Show validation errors inline (invalid client ID format, malformed JSON service account key, missing project ID).

Technical Design Notes

Configuration read-path

Create a small server action/service:

• getGoogleIntegrationConfigStatus(tenant) returns which secrets are present and any derived base URLs / redirect URIs.
• Ensure values are masked (never return raw secret).

OAuth flows

Email OAuth:

• Initiation: server/src/lib/actions/email-actions/oauthActions.ts
• Callback: server/src/app/api/auth/google/callback/route.ts

Calendar OAuth:

• Initiation: server/src/lib/actions/calendarActions.ts
• Callback: server/src/app/api/auth/google/calendar/callback/route.ts

Both should:

• Use tenant secrets for client ID/secret.
• Avoid app-secret fallback for Google.

Pub/Sub provisioning

Update Gmail Pub/Sub provisioning (server/src/lib/actions/email-actions/setupPubSub.ts) to read google_service_account_key from tenant secrets. (This aligns with docs/inbound-email/setup/gmail.md.)

Calendar Pub/Sub:

• Current implementation appears incomplete/no-op; not required to satisfy the tenant-owned OAuth change, but should be assessed as a risk.

Security / Permissions

• Only users with appropriate RBAC (currently system_settings create/update) can view the Google setup panel and write secrets.
• Never return secrets to the client; only return masked/boolean status.
• Ensure secrets provider write path uses tenant scoping.

Risks / Open Questions

1. Google Calendar notifications: confirm the chosen mechanism (Pub/Sub vs native Calendar push channels) based on feasibility and the existing webhook processor expectations.
2. Provider reset: implement as explicit admin action vs automatic reset-on-first-load; decide which is safer operationally.

Rollout / Migration

• Breaking change for Google integrations.
• No migration of existing providers/tokens.
• Update documentation and in-app guidance to clearly explain reconfiguration steps.

Acceptance Criteria

• Tenant admin can configure Google OAuth credentials via a dedicated settings area and secrets are stored as tenant secrets.
• Gmail and Google Calendar integrations successfully initiate OAuth using tenant credentials (including in hosted environments) with the same tenant-secret configuration model for CE and EE.
• Provider setup UIs no longer require manual entry of client id/secret per-provider and guide users to the Google setup area if missing.
• No Google integration codepath depends on app-level Google OAuth credentials.
• Google Calendar notifications are configured so Alga receives callbacks and can trigger delta sync.
• Google integrations have scheduled maintenance (PG Boss / Temporal) to keep callbacks and tokens healthy, analogous to Microsoft.
• Secrets are never returned unmasked to the browser.