Connecting a Google Workspace Mailbox

Connecting a Google Workspace Mailbox

From v0.3.0, an organization's report mailbox can be a Google Workspace mailbox, read through one service account for the whole server. The server's hosted mailbox can be read the same way.

Server setup (once, by the platform admin)

1. In the Google Cloud console, create a project (or use one), enable the Gmail API, and create a service account. Create a JSON key for it.
2. Give the key to YetAnotherDmarcTool, in the api and the worker:
   • GOOGLE_MAIL_SERVICE_ACCOUNT_FILE: the path of the key file, mounted read-only (Docker Compose); or
   • GOOGLE_MAIL_SERVICE_ACCOUNT_JSON: the key's contents on one line (Portainer stack variable, or the Azure template's Google Workspace mailboxes step, which stores it in Key Vault). jq -c . key.json prints it on one line.
3. The admin console's setup checks say if the key can't be read.

The service account's client ID (in the key, and shown in Settings → Mailbox) is what customers' Workspace admins grant access to.

Connecting an organization's mailbox

1. The organization's Google Workspace admin grants the service account access once: admin.google.com → Security → Access and data control → API controls → Manage domain-wide delegation → Add new:
   • Client ID: the one shown in Settings → Mailbox
   • OAuth scope: https://www.googleapis.com/auth/gmail.modify
2. In YetAnotherDmarcTool, an org admin: Settings → Mailbox → Google Workspace mailbox, enter the mailbox, Test connection, Save & start syncing.

The mailbox must be on one of the organization's verified domains. Domain-wide delegation lets the service account act as anyone in a Workspace that granted it, so this is what keeps one organization from reading another's mailbox.

Reports are marked read, removed from the inbox and labelled DMARC processed (created if missing). A message that isn't a readable report is only marked read. The report sender check uses Gmail's own Authentication-Results (mx.google.com); nothing to confirm.

The hosted mailbox from Google

Set HOSTED_REPORTS_SOURCE=google and HOSTED_REPORTS_MAILBOX_ADDRESS to the mailbox, with the service account above (your own Workspace grants it access). The mailbox must deliver name+anything@domain to name@domain; Gmail does. Reports are routed to the right organization by the address they were sent to.

Troubleshooting

Message	Meaning
"hasn't granted domain-wide delegation to client ID ... with scope ..."	Step 1 above isn't done, or the scope differs. Changes can take a few minutes.
"check that the mailbox exists in a Workspace that granted access"	Wrong address, or the mailbox is in another Workspace.
"the mailbox must be on one of your verified domains"	Verify the domain first (Settings → Domains).