Connecting Google Workspace

Flarehawk connects to your Google Workspace customer through a managed, read-only administrator OAuth flow. One connection covers Login, Admin, Drive, and Gmail activity. You do not create an OAuth app, service account, key, or webhook.

​

How log delivery works

Flarehawk polls every five minutes and uses a seven-day initial backfill. Login, Admin, and Drive also use payload-bearing Reports API watches for faster delivery. Google describes watch delivery as best-effort and unordered, and channels expire within hours, so polling remains the completeness path. Gmail is polling-only because Google does not support Gmail in the Reports API push application list. See Google’s Reports Activities API and push notification guide.

​

Prerequisites

• An active Flarehawk organization.
• A licensed Google Workspace customer. Consumer Google accounts cannot connect.
• A Google Workspace administrator who can authorize read-only Reports audit access and customer-directory lookup.
• Audit sources available for your Workspace edition and administrator privileges. Flarehawk reports unsupported sources individually while keeping available sources connected.

​

Create the connection

​

Analytics and detections

Google Workspace provides four provider-isolated analytics pages:

• Sign-ins — login outcomes, failure bursts, actors, and source addresses.
• Admin Activity — privilege, policy, and configuration changes.
• Drive Activity — external sharing, downloads, deletes, and resources.
• Gmail Activity — forwarding, delegation, mailbox access, deletes, and attachments.

Each Google Activity can contain multiple child events. Flarehawk expands each child into its own canonical, billable event and deduplicates overlap between watches, polls, and retries before storage, usage metering, and analysis.

​

Security and tenancy

• Flarehawk stores the OAuth refresh grant, exact scopes, customer ID, primary domain, and authorizing administrator identity in its encrypted connection-credential bundle.
• One Google customer can belong to only one Flarehawk organization. Reauthorizing from the same organization updates the grant in place and retains the asset, ingest token, and poll cursors.
• OAuth state is signed, expires after ten minutes, uses PKCE, and is bound to the initiating Flarehawk user and organization.
• The public Reports callback has an exact Envoy route with a local 500-request-per-second ceiling per proxy. Malformed headers are rejected before database access. Google treats the limiter’s 429 as a failed notification, so the overlapping completeness poll recovers any activity that reaches this deliberately high ceiling.
• Deleting the connection makes a best-effort attempt to stop active Reports watches and revoke the Google grant before removing local configuration.

​

Operator configuration

Use a separate Google Cloud project and connector OAuth client in staging and production. The dashboard Worker reads the Infisical-backed VB_GOOGLE_WORKSPACE_CONNECT_CLIENT_ID, VB_GOOGLE_WORKSPACE_CONNECT_CLIENT_SECRET, and VB_GOOGLE_WORKSPACE_CONNECT_REDIRECT_URI bindings. VB_GOOGLE_WORKSPACE_CONNECT_STATE_SECRET is optional and lets operators use an independent high-entropy state-signing key. These are connector credentials; do not reuse the VB_BETTER_AUTH_GOOGLE_* social-login client, and do not commit them as Wrangler vars. Kubernetes uses the same environment-specific OAuth client through the unprefixed GOOGLE_WORKSPACE_CONNECT_CLIENT_ID and GOOGLE_WORKSPACE_CONNECT_CLIENT_SECRET keys. The redirect URI is a dashboard-only binding. The public webhook URL is selected by the environment’s Helm values. Keep the connector key names present in both staging and production Infisical environments even though their values may differ. The Google Workspace poller heartbeat is production-only. Provision these values before enabling the functional release: The callback URI must end in /api/providers/google_workspace/oauth/callback. Helm sets the public watch address to https://ingest-staging.flarehawk.com/webhooks/google-workspace/reports/v1 in staging and https://ingest.flarehawk.com/webhooks/google-workspace/reports/v1 in production. Before promoting the integration, complete Google’s production-readiness checklist for each environment:

• Create separate staging and production Google Cloud projects and web-application OAuth clients.
• Enable the Admin SDK API in both projects.
• Configure the OAuth consent screen, authorized domains, support contacts, and privacy-policy/application links; publish the production app and complete Google verification for the requested sensitive scopes.
• Register the exact dashboard callback URI for each environment. Configure the matching public HTTPS ingest endpoint ending in /webhooks/google-workspace/reports/v1 as the Reports watch address; do not share either endpoint across environments.
• Provision the dashboard VB_GOOGLE_WORKSPACE_CONNECT_* bindings and the matching unprefixed K8s connector values in the appropriate Infisical environment.
• Bootstrap the production incident.io source from scripts/incident-io/heartbeats.config.ts (flarehawk-google-workspace-poller), then store HEARTBEAT_GOOGLE_WORKSPACE_POLLER_URL under prod /flarehawk-k8s/incident-io-heartbeats only. Supply the same existing 32-byte credential-encryption key as VB_CREDENTIALS_ENCRYPTION_KEY to the dashboard and CREDENTIALS_ENCRYPTION_KEY to the K8s poller. Never copy the staging encryption key into production, and never copy the production heartbeat URL into staging.
• Confirm the environment’s google-workspace-webhook-*-policy is accepted by Envoy Gateway and that excess callback traffic receives 429 without changing the general ingest route. The policy follows Envoy Gateway’s route-scoped local rate-limit contract.
• Exercise OAuth consent, a bounded poll, watch creation/renewal, webhook authentication, heartbeat delivery, and deletion/revocation against staging before promotion.

​

Operator release runbook

Release this integration in two standard promotion batches. Do not combine the schema and functional changes, and do not use a feature flag as a substitute for the split.

​

Batch 1: expand schema

1. Promote only the PlanetScale watch-channel migrations, the shared and production ClickHouse view/counter migrations, their atlas.sum files, and the ClickHouse parity manifest. Keep the provider unavailable and keep googleWorkspacePoller.enabled out of this batch.
2. Let the staging migration workflow apply the PlanetScale and shared ClickHouse histories. Verify atlas migrate status is clean, google_workspace_watch_channels exists, all four filtered views resolve, and the family counters compile against staging data.
3. Promote the schema batch from staging to main with a merge commit.
4. Dispatch the production database workflow with env=prod and dry_run=false, obtain the production-database approval, and verify both the shared and production-only ClickHouse histories plus PlanetScale are clean. Do not begin the functional promotion until live production schema parity passes.

​

Batch 2: enable the integration

1. Provision the Infisical connector keys and webhook URL before enabling the staging poller. Do not provision a staging Google Workspace incident.io heartbeat.
2. Include OAuth, connection lifecycle, poller, webhook, claim layer, analysis, UI, documentation, monitors, Helm enablement, and the atomic unflagged status: "available" catalog change in the functional batch.
3. Complete the staging acceptance checks below. Resolve source errors and monitor-routing failures before opening the promotion PR.
4. Confirm production Google Cloud verification, callback/webhook registration, Infisical key parity, incident.io heartbeat provisioning, and Datadog monitor validation before promoting staging to main.
5. After promotion, watch the poller CronJob, ingest and analysis rollouts, source cursors, channels, and all Google Workspace monitors. If the functional release regresses, disable the poller and revert the functional batch while leaving the backward-compatible expanded schema in place.

The functional batch intentionally enables googleWorkspacePoller in both environment values. A schema-only promotion must therefore exclude those values files and the available catalog entry.

​

Staging acceptance

• Connect a dedicated licensed Workspace with all four sources. Verify encrypted credentials, the immutable customer asset, a seven-day backfill, source health, and completed cursors.
• Generate known Login, Admin, Drive, and Gmail activity. Confirm payload-bearing push for Login, Admin, and Drive, bounded polling for all four, and polling-only delivery for Gmail.
• Force a watch renewal and a temporary webhook outage. Verify replacement-before-retirement, poll recovery, and exact deduplication across watch, poll, retry, and stale-claim recovery.
• Confirm the exact webhook route and BackendTrafficPolicy are accepted in staging. Exercise a controlled over-limit burst, verify 429 at the edge, and then verify the overlapping poll recovers the activity.
• Confirm one Google child event produces one canonical row, one family-counter contribution, one metered event, and one analysis task. Verify all four filtered ClickHouse views, analytics pages, Google rules, incident evidence, and sandbox notification delivery.
• Exercise revoked consent, insufficient privileges, unsupported source licensing, quota throttling, transient ingest failure, reconnect, and deletion. Unsupported sources must remain source-local and must not suppress the successful poller heartbeat.

​

Monitoring contract

• The production incident.io source expects a successful five-minute poll sweep and has a ten-minute grace period, so it alerts after 15 minutes without a successful run. Staging does not ping this heartbeat.
• Structured google_workspace_source_freshness logs drive cursor warnings above one hour and P1 alerts above three hours. A healthy steady-state cursor is normally about 15 minutes behind because the poll horizon is deliberate.
• Repeated google_workspace_channel_maintenance_failed events inside the 90-minute renewal window page before an active channel expires without a replacement. Polling remains the completeness path while push is degraded.
• Datadog also tracks bounded Reports API retries, final source errors, webhook authentication rejections, and any source-claim admission or finalization failure. Monitor definitions live under k8s/monitoring/datadog/monitors/google-workspace-*.json and must pass the repository monitor sync validation before promotion.
• Use flarehawk.ingest_source_claims.count outcomes to compare accepted, committed/request duplicate, reclaimed, and recovery events. Break freshness and error logs down by connection_id and application; never place channel tokens or OAuth credentials in logs or monitor messages.

​

Troubleshooting

For Google’s OAuth requirements, see the web-server OAuth guide and production readiness checklist.