Docs / Obsidian Suite / Connect your mail
Google Workspace
How to put Obsidian Suite in front of Gmail in Google Workspace, and how to connect it with a service account. Your domain page in the portal (Manage > Organizations > your organization > the domain) shows the same steps, filled in with your domain and Obsidian Suite's addresses.
Before you start
- Your organization's Platform is Google Workspace (organization page, Settings).
- Your domain is added. Its Deliver clean mail to is
aspmx.l.google.com, filled in for you when the domain is added. - Note the Obsidian Suite IP addresses listed in step 1 of the domain page's Set up mail flow card.
Mail flow
- Inbound gateway. Google Admin console > Apps > Google Workspace > Gmail > Spam, phishing and malware > Inbound gateway:
- add the Obsidian Suite IP addresses from your domain page;
- tick Message is spam if the following header regexp matches with
X-Obsidian-Spam: Yes, so tagged mail goes to Spam; - after the MX switch, also tick Reject all mail not from gateway IPs.
- MX record. Change your domain's MX to
10 mx1.obsidiansuite.net. Obsidian Suite delivers clean mail on to Google. See Getting started. - Outbound (optional). See Sending outbound mail.
API connector
The connector adds user sync, sign-in with Google accounts, clawback of delivered threats and, if you want it, API-mode scanning. On your organization page choose API connectors > Add connector > Google Workspace.
Create the service account
- Google Cloud console: create a project and enable the Gmail API and the Admin SDK API.
- IAM > Service accounts: create one, then Keys > Add key > JSON. You paste the downloaded file's contents into the connector.
- Google Admin console > Security > Access and data control > API controls > Domain-wide delegation > Add new: the service account's client ID with these scopes:
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/gmail.modify - For sign-in with Google accounts: APIs & Services > Credentials > Create OAuth client ID (Web application) with the redirect URI
https://portal.obsidiansuite.net/auth/oidc/google/callback. You paste its ID and secret into the connector.
Connector fields
| Field | What to enter |
|---|---|
| Workspace admin to impersonate | A Google Workspace super admin the service account acts as for directory reads. |
| Customer ID | my_customer (the default) means the admin's own account. |
| Mailboxes to scan (API mode) | Comma separated. Empty means every active synced user. |
| Service account json | The whole JSON key file (paste its contents). Stored encrypted. |
| OAuth client ID (SSO) | Client ID of the OAuth web client, used only for Continue with Google sign-in. |
| Oauth client secret | Secret of that OAuth client. Stored encrypted. |
Secret fields show stored once a value is saved. Leave them blank to keep the stored value.
Then choose the capabilities, described in API connectors, and use Test connection.
Clawback in Google moves the message to Trash. Releasing it again takes it out of Trash and puts it back in the inbox.
Troubleshooting
- unauthorized_client: the domain-wide delegation scopes are missing or mistyped. Copy them exactly as above, as one comma-separated line.