Current Doc

Gmail Org Integration

Use Browse Docs to switch sections and search the full docs list.

Documentation

Blue Lantern Security Docs

Learn how to use the marketplace, run security tools, and integrate via the API.

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.

Most organizations should use one-click setup. You need a Workspace super admin and an active seat plan; there is no Google Cloud project, service account, key or Pub/Sub topic to create.

  1. Open Integrations, click Add Integration, and choose Gmail (Google Workspace). Choose whether to onboard users and monitor mail or onboard users only, and optionally turn on moving detected phishing to Spam.
  2. Click Sign in with Google and sign in as a super admin. This tells us your Workspace domain; it asks only for your name, email and profile picture.
  3. Back in Blue Lantern, copy the client ID and scopes shown into your Google Admin console (Security → Access and data control → API controls → Manage domain-wide delegation → Add new) and click Authorize. If you turned on Spam moves, add the second client ID shown as well.
  4. The wizard checks each permission live and finishes on its own once Google applies the authorization, usually within minutes. You can close it and use Finish setup on the integration later.

Blue Lantern authenticates to Google with short-lived tokens, so no credential is stored. To revoke access, delete the Blue Lantern entries from domain-wide delegation. An integration connected with your own service account shows Switch to one-click; your current key keeps working until the new connection is verified.

Requirements

The rest of this page covers advanced setup, for organizations that want to use their own service account.

  • 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 whether Blue Lantern should onboard users and monitor mail or onboard users only. Onboarding only imports your users and assigns seats without reading any email, so it needs the directory scope alone; you can turn on mail monitoring later from the integration's Settings. If you choose to monitor mail, the same step offers 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 (only when monitoring mail)
    • https://www.googleapis.com/auth/admin.directory.user.readonly
    • https://www.googleapis.com/auth/gmail.modify (only if spam-move is enabled)

    If you plan to use the optional forwarding or inbox-rule checks, add these two as well. They read mail settings only (forwarding and filters, plus the labels filters refer to), never messages:

    • https://www.googleapis.com/auth/gmail.settings.basic
    • https://www.googleapis.com/auth/gmail.labels

    The wizard shows each set as one comma-separated line, ready to paste.

  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 before anything is stored: a directory list, plus one mailbox read when monitoring mail. 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, mail monitoring only). 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 (the optional gmail.settings.basic and gmail.labels scopes would let a holder edit filters and labels; we only read them), 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.

The forwarding and inbox-rule checks need the gmail.settings.basic and gmail.labels scopes on your delegation grant (step 3 above). If they are missing, the scan falls back to gmail.readonly when you granted it, and the integration's Settings prompt you to add them so these checks keep working if mail monitoring is turned off. Mail authentication needs no scopes.

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.

Need Help?

Can't find what you're looking for? Reach out and we'll get back to you.

Contact Support