Gmail Org Integration

Monitor every Gmail mailbox in your Google Workspace org through the direct API, with no per-user extension installs. One setup pulls your user directory, assigns seats, and analyzes incoming mail for phishing within seconds of arrival. Results land in the Monitoring Hub, and malicious mail can optionally be moved to Spam automatically.

Setup is driven end to end by the guided wizard at Account → Integrations. The in-app Gmail Org Integration page has the same steps with copy-ready gcloud commands; this page is the reference version.

Requirements

• An active seat plan. Accounts without a seat plan cannot connect org integrations. Users are seated up to your purchased count and unseated mailboxes are not ingested; see Seat Licenses & Pricing.
• A Google Workspace domain. Domain-wide delegation does not exist for consumer @gmail.com accounts.
• A Workspace super admin to grant domain-wide delegation, and (if your org enforces the service-account key restriction) an Organization Policy Administrator in Google Cloud. A Blue Lantern account admin can start the wizard and hand these steps to the right people; every value they need is shown copy-ready.

How setup works

1. Start the wizard. Open Integrations, click Add Integration, and choose Gmail (Google Workspace). The first step asks one decision up front: whether to allow the optional spam-move action (write access). Leave it off for strictly read-only monitoring.
2. Google Cloud: service account and JSON key. In any Google Cloud project you own, enable the Admin SDK API and Gmail API, create a service account (no IAM roles needed), and create a JSON key for it. The wizard collects the key file and checks its shape immediately. If Keys → Add key is greyed out, your org enforces iam.disableServiceAccountKeyCreation; an Organization Policy Administrator must add a project-level exception, create the key, and re-enable the restriction.
3. Workspace: grant domain-wide delegation (super admin). In the Admin console under Security → Access and data control → API controls → Domain-wide delegation, add the service account's client ID (shown copy-ready in the wizard) with these scopes:

   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/admin.directory.user.readonly
   • https://www.googleapis.com/auth/gmail.modify (only if spam-move is enabled)
4. Connect and pull the directory. Enter your Workspace primary domain and an admin email to impersonate for directory reads, then connect. The delegation is validated live (a directory list and one mailbox read) before anything is stored; failures name the exact missing scope. On success your users are pulled and seated automatically and appear on the Organization page.
5. Enable real-time delivery (Pub/Sub). The final screen walks through creating a Pub/Sub topic in your project, granting Gmail's push service account the Publisher role on it, and creating an authenticated push subscription to our endpoint, with every value copy-ready. Save the topic name and mailbox watches arm automatically on the next daily sweep. This step can also be completed later from the integration's Settings.

Sensitive actions

This integration reads mailboxes across your org, so be deliberate about each grant:

• Service-account key creation. If you lift iam.disableServiceAccountKeyCreation, scope the exception to the single project and re-enable it after creating the key. On our side the key is sent once over TLS, stored in AWS Secrets Manager (never our database), and never returned by any API. Deleting the key in Google Cloud immediately invalidates our access.
• Domain-wide delegation. The grant is the minimum needed for org-wide monitoring: scopes are read-only unless you explicitly enable spam-move, directory access is list-only, and the connection fails closed at setup if a scope is missing. A super admin can revoke the grant in the Admin console at any time, which severs access instantly.
• What we retain. Raw message payloads auto-delete within 24 hours and analysis reports within 90 days. The dedup cache stores only a content hash and run reference, never message content. Pub/Sub push notifications carry no mail content (only a mailbox address and history cursor), and the push endpoint verifies Google-signed authentication on every request.

Optional: daily identity posture scan

From the integration's Settings you can enable a once-daily scan of who can get into your org, reported in the Monitoring Hub under the Identity type:

• MFA registration. Every directory user is checked for 2-Step Verification; admins without it are critical findings.
• Dormant accounts. Enabled accounts with no sign-in for 90 days (30 days for admins) are flagged; dormant admins are critical.

No new permissions are needed for either check; the directory scope in your existing delegation grant already covers both. The scan reads the whole directory, including users whose mailboxes are not monitored.

Optional: daily mail posture scan

Settings also offer a once-daily scan of the ways mail can leak from your org, reported under the Mail Posture type with an exportable report per scan:

• Auto-forwarding. Account-level auto-forward, parked forwarding addresses, and filter forwards to external destinations, the classic BEC persistence move. Admin forwards are critical findings.
• (Enabling either of the two checks above requires a one-time acknowledgement in Settings: they read and store mailbox forwarding and inbox-rule contents for every directory user, beyond the monitored-group scope. The acknowledgement is recorded with who accepted and when.)
• Suspicious inbox rules. Filters that delete, hide, or divert mail in patterns associated with account compromise.
• Mail authentication. DMARC, SPF, and the google._domainkey DKIM selector posture of your sending domains. Public DNS lookups only.

No new scopes are needed for any of these; the gmail.readonly delegation scope already covers the settings reads.

Optional: daily AI exposure scan

Settings also offer a once-daily inventory of the third-party OAuth apps your users have granted access to their Workspace data, reported under the AI Exposure type. It flags AI tools that can reach mail, files, or calendars, and after the first baseline scan it highlights newly appearing risky apps — which can trigger alert rules on the AI Exposure run type.

The scan reads grant metadata only — app identities and scope strings, never message or file content. It requires the admin.directory.user.security scope added to your existing domain-wide delegation grant (Security → API controls → Domain-wide delegation — same client ID, add the scope). The next daily scan picks it up; mail monitoring continues unaffected either way.

Managing the integration

The Integrations page shows connection status, granted scope, and sync results. Settings let you change the monitored domain, spam rules, and Pub/Sub topic; changes are merged, so you only submit what changed. Disconnecting removes the stored credential; revoking the delegation or deleting the key on the Google side has the same effect immediately.