Google Workspace: Sensitive Data Scanning Guide

What it scans

Connection type	Scanned scope
`gmail`	Headers, bounded body text and attachment contents for the explicit Workspace users you list, optionally limited by label and received-after time
`google_drive`	One shared drive, or one explicitly impersonated user's My Drive root; Docs/Slides export as text and Sheets as CSV

These connections use a service account with domain-wide delegation and are marked Pilot. For personal accounts use Personal drives or Gmail app-password header and attachment scanning.

What you need

A Google Workspace super admin, a Google Cloud project operator and a customer-run agent that can reach Google's OAuth, Gmail and Drive API endpoints over HTTPS. The service-account key stays on your agent.

Warning: Domain-wide delegation can impersonate any user in the domain for the authorized scopes. Myrikeep's explicit user list narrows scanning but is not a Google-enforced boundary on a stolen key.

Step 1: Create a project and service account

In Google Cloud console, choose Select a project → New project or an existing project you control.
APIs & Services → Library: enable Gmail API and/or Google Drive API, according to the sources you will scan.
IAM & Admin → Service Accounts → Create service account: name it myrikeep-scan. Skip project roles and optional user access grants.
Open the new account's Details → Advanced settings → Domain-wide delegation and record its numeric OAuth Client ID.
Keys → Add key → Create new key → JSON downloads the private key file. Protect it like a password. Do not upload it to Myrikeep.

See Google's service-account delegation instructions.

Step 2: Authorize read-only delegation

As Workspace super admin, open Admin console → Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new. Enter the service account's numeric Client ID and only the scopes your connections need:

text

https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly

Authorize just one scope if using just one source. Do not add Gmail modify/send, Drive write or Admin SDK directory scopes. These are broad read permissions; the key can read mail/Drive as users across your domain. Keep it on the host, rotate it routinely and review provider audit logs. See Gmail scopes and Drive scopes.

Step 3: Choose scope and connect

For Gmail, list the actual Workspace user email addresses. For a shared drive, choose an impersonated user with access and copy the shared drive ID from its Drive URL, such as the ID after /drive/folders/. Do not paste the full URL. Leave Drive ID empty for that user's My Drive root. The connector never searches the user directory or lists every drive in the domain.

Open Connections → Add connection, select Workspace Gmail (Pilot) or Google Drive (Pilot), enter the scope, assign your agent and use Local credential catalog. Save the JSON below on the agent. Wait for present, then queue a small scan in Scans and check Coverage.

Connection settings table

Console field	Example	Required or optional
Connection name	`Workspace finance`	Required; unique in workspace
Type	`gmail` or `google_drive`	Required
Impersonated users (Gmail)	`[email protected]`	Required; one per line or comma-separated, at most 1,000
Gmail label ID (Gmail)	`INBOX` or `Label_7`	Optional; blank scans mailbox scope
Received after (Gmail)	`2026-01-01T00:00:00Z`	Optional; UTC
Impersonated user (Drive)	`[email protected]`	Required; user with drive access
Drive / document library ID (Drive)	`0AExampleDriveId`	Optional; shared drive ID, blank for My Drive
Agent	`Google agent`	Required; same workspace
Credential mode	Local credential catalog	Required
Credential name	`GOOGLE_MAIN`	Required; uppercase alias
Exclude patterns (View/edit)	`*.tmp`	Optional; one glob per line
Enabled (connection row)	Enabled	Disable to stop new scans

Workspace Drive has no folder-ID/root-path field. For a smaller scan choose a separate shared drive or use exclusions, while remembering the key's broad authority.

Secret file

Save the downloaded Google service-account JSON verbatim as /srv/myrikeep/secrets/GOOGLE_MAIN. Its shape is below. The key is an explicit placeholder, not a usable private key; do not manufacture a key from this example.

json

{
  "type": "service_account",
  "project_id": "example-scan-project",
  "private_key_id": "<GOOGLE_KEY_ID>",
  "private_key": "<GOOGLE_GENERATED_PEM_PRIVATE_KEY>",
  "client_email": "[email protected]",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/myrikeep-scan%40example-scan-project.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

Required fields are type, client_email, private_key, token_uri. The other shown fields are accepted optional fields, not permission settings. All values must be nonempty strings; unknown fields are rejected by the catalog validator. The token URI must be exactly the one shown. Merge this catalog entry:

json

{"version": 1, "credentials": {"GOOGLE_MAIN": {"types": ["gmail", "google_drive"], "source": {"kind": "file_json", "path": "/run/secrets/GOOGLE_MAIN"}}}}

Include only the types used. Follow Agent credentials for file modes and mounts. To rotate, create a new Google key, replace the local file, verify a scan and remove the old key in Google Cloud.

Scope, exclusions and schedules

Gmail scans only the named users and optional label/time filter. Drive walks only the selected drive's descendants. Drive globs such as *.tmp or ~$* match item names, not full folder paths. Gmail globs match slash-joined user, message, part and filename fields: *.pdf skips PDF attachments, not message bodies. Enumeration fetches bounded full message payloads to discover parts, even if a part is later excluded. Configure exclusions in Connections → View/edit. See Getting started for schedule cadence.

"Who can see it" support

Drive checks anyone links, internal domain sharing and external grants. Complete owner-visible narrow permissions may be restricted; incomplete/non-owner views, unresolved groups and shared-drive limits remain unknown or partial. It does not enumerate directory/group membership. Gmail sharing checks are not available for this source yet. Drive uses modified time for age; Gmail uses internal receipt time. A Drive viewed-by-me date describes only the caller, not all users. See Who can see it.

Troubleshooting

State or error	What to do
`unknown`	Check heartbeat, assignment and current connection revision.
`missing` / `credential_missing`	Check alias/type and read-only secret mount.
Invalid / `credential_config_invalid`	Use the downloaded service-account object, with valid PEM key, permitted fields, token URI and file modes.
`present`	The key is structurally valid; delegation and user/resource access still need a scan.
`source_error` / unauthorized_client	Inspect local diagnostics. Check numeric client ID and the exact delegated scopes in Admin console.
invalid_grant / invalid credentials	Check key revocation, private-key format, agent clock and impersonated user.
403 / access denied	Enable the API, check delegated scope and impersonated user's access to this shared drive.
404 / item gone	Verify plain provider ID and the selected user's visibility; do not paste a browser URL.
`access_denied` sharing / unknown	Review read-only metadata access; do not infer restricted from missing permission evidence.
429 / rate_limited	The agent retries within bounds; narrow scope and spread schedules if quota failures persist.
Paused / Migration paused / Disabled	Resume agent, assign and save a valid migrated connection, or enable it.
`signin_required`	Workspace types use service accounts. Interactive sign-in belongs to personal drives.

Limits

No send/write, directory discovery or domain-wide file search. Gmail caps at 100,000 messages, 100 attachments per message, 20,000 body characters and 10 MiB per attachment by default. Inline-only attachment parts without attachmentId are skipped. Drive caps at one million items, 100,000 folders and depth 64. Cross-drive/chained shortcuts and unsupported Google-native types are skipped. Docs/Slides export text and Sheets CSV, without full original formatting. All reads/exports and sampling are bounded. Common text, PDF text and modern Office have parsers; other file formats use strings-only checks. Text in images and scanned PDFs needs OCR, an optional premium feature a workspace owner enables; it runs inside your agent with the OCR agent image. Check Coverage for skipped or sampled content.