Gmail Org Integration
Monitor every Gmail mailbox in your Google Workspace org through the direct API — no per-user extension installs. One setup pulls your user directory, assigns seats, and analyzes incoming mail for phishing automatically, within seconds of arrival.
A Google Workspace administrator is required
The setup involves privileged actions in your Google Cloud and Workspace admin consoles: granting domain-wide delegation requires a Workspace super admin, and if your organization enforces the service-account key restriction, lifting it requires an Organization Policy Administrator in Google Cloud. A Blue Lantern account admin can start the wizard and hand those specific steps to the right people — every value they need is shown copy-ready.
Whole-org coverage
A service account you own, with domain-wide delegation you grant, reads mailboxes directly — every user is covered with nothing to install on their machines.
Real-time analysis
Gmail pushes new-mail notifications through your own Pub/Sub topic; suspicious mail is analyzed within seconds and lands in the Monitoring Hub with a verdict. Duplicates (an inbox copy and a user-forwarded copy) dedupe to one report.
Seats assigned automatically
Pulled users are seated up to your purchased seat count; the rest join unmonitored until you add seats. Ingestion is seat-only.
How setup works
Everything is driven from our guided wizard — it presents each Google-side step with copy-ready values, then validates the connection live before anything is stored.
- 1
Start the wizard in our UI
Open Account → Integrations (or the button above), 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 + 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.
Many organizations enforce the org policy iam.disableServiceAccountKeyCreation, which blocks creating the JSON key. If Keys → Add key is greyed out, an Organization Policy Administrator must temporarily lift that restriction for the project (Organization Policies → "Disable service account key creation" → add a project-level exception), create the key, and re-enable the restriction afterwards. This is a sensitive change — scope it to one project and put it back when done.
- 3
Workspace: grant domain-wide delegation (super admin)
In the Workspace Admin console: Security → Access and data control → API controls → Domain-wide delegation → Add new, using the service account's client ID (the wizard shows it copy-ready from your key) and 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)
- https://www.googleapis.com/auth/admin.directory.user.security (only for the optional AI exposure scan — can be added later)
This grant is what authorizes org-wide mailbox reads — it is the most sensitive step, and only a super admin can perform it. It is revocable there at any time.
- 4
Connect and pull the directory
Back in the wizard: enter your Workspace primary domain and an admin email to impersonate for directory reads, then connect. We validate the delegation live (a directory list and one mailbox read) before storing anything; failures come back with the exact missing scope or misconfiguration named. 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 — every URL, service account, and audience value is shown 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.
Helpful gcloud commands
Everything above can be done in the console UI, but these commands speed up the common snags. The org-policy commands remove org-wide guardrails — run them with care and restore the policies once setup is done.
Find your organization ID
Needed for the org-policy commands below.
gcloud organizations list
Lift the service-account key-creation restriction
Unblocks Keys → Add key when your org enforces it (step 2). Requires an Organization Policy Administrator, and you may need to enable the Org Policy API first (gcloud services enable orgpolicy.googleapis.com). This removes the policy org-wide — restore it after creating the key.
gcloud org-policies delete constraints/iam.disableServiceAccountKeyCreation --organization=<ORG_ID>
Lift the domain-restricted-sharing policy
Needed if granting the Pub/Sub Publisher role to Gmail's push service account fails — that account ([email protected]) is outside your domain, which this policy blocks. Same caution: org-wide removal, restore it after the grant.
gcloud org-policies delete constraints/iam.allowedPolicyMemberDomains --organization=<ORG_ID>
Grant Gmail publish rights on your topic
The step-5 Publisher grant, as a one-liner.
gcloud pubsub topics add-iam-policy-binding <TOPIC_ID> \ --project=<PROJECT_ID> \ --member=serviceAccount:[email protected] \ --role=roles/pubsub.publisher
Optional: daily AI exposure scan
Which AI tools can touch your org's data — the inventory insurers and customers have started asking for. Enable it with one checkbox in the integration's Settings.
How it works
Once a day we list each directory user's granted third-party OAuth apps through the Admin SDK token audit and classify every grant: whether the app is a known AI tool (a curated catalog plus name heuristics) and how far its scopes reach — Gmail, Drive, and Calendar access versus sign-in only. Flagged apps become per-app check rows; per-user grants are rolled up into counts, so no user addresses leave the report.
Where results land
Each scan is an AI Exposure run in the Monitoring Hub with per-app check rows and an exportable report. The first scan records a baseline; after that, newly appearing risky apps lead the report and can trigger alert rules on the AI Exposure run type. An AI exposure section also appears in the attestation report.
Requires the https://www.googleapis.com/auth/admin.directory.user.security scope added to your existing domain-wide delegation entry (step 3 above — same client ID, add the scope). No reconnect is needed; the next daily scan picks it up. The scan reads grant metadata only — app identities and scope strings, never message or file content — and mail monitoring continues unaffected either way.
Sensitive actions, and how exposure is limited
This integration reads mailboxes across your org — be deliberate about each grant. What you are granting, and the corresponding controls:
Service-account key creation
If your org enforces iam.disableServiceAccountKeyCreation, lifting it (even briefly) weakens a guardrail — scope the exception to the single project, re-enable it after creating the key, and treat the downloaded JSON as a credential. 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 (org-wide mailbox read)
The delegation lets the service account read every mailbox and list users — the minimum needed for org-wide monitoring, and nothing more: scopes are read-only unless you explicitly enable spam-move (gmail.modify), 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 Workspace 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. All data is strictly scoped to your account.