Google Workspace#

Connect your Google Workspace tenant so AgentSOAR can suspend compromised accounts and block malicious senders and sender domains. AgentSOAR authenticates with a Google Cloud service account that impersonates a Workspace admin via domain-wide delegation. This same credential also powers the Google Workspace email-logs data source.

What this enables#

This credential powers three AgentSOAR response capabilities against your Google Workspace tenant:

Capability	What it does	How
block_sender	Blocks mail from a specific malicious sender	Gmail filter
block_email_domain	Blocks mail from a malicious sender domain	Gmail filter
disable_user	Suspends a compromised user account	Admin SDK / Directory API

The same credential is also used by the Google Workspace email-logs data source to ingest mail activity.

Prerequisites#

• A Google Workspace tenant and a Google Cloud project to host the service account.
• A Workspace super-admin to authorize domain-wide delegation (Step 6).
• An active Workspace admin account for the integration to impersonate (Step 7).
• Access to AgentSOAR → Settings → Credentials (/agentsoar/settings/credentials).

How the connection works#

A Google Cloud service account by itself has zero access to Google Workspace data. Workspace data (the user directory, mailboxes) belongs to your tenant and its users, not to your Cloud project. Three pieces bridge that gap:

Value	What it is	Why it's needed
Service Account JSON	The machine identity calling Google	Who is making the request
Delegated Admin Email	A Workspace admin the service account impersonates	Whose authority the calls run under (domain-wide delegation)
Customer ID	The Workspace tenant identifier	Which tenant's directory to read/write

By the end of this guide you will have all three and a validated credential in AgentSOAR.

OAuth scopes the integration uses#

Scope	Used for
https://www.googleapis.com/auth/admin.directory.user.readonly	Validate the credential and sync the user inventory
https://www.googleapis.com/auth/admin.directory.user	Suspend a compromised user
https://www.googleapis.com/auth/admin.directory.domain.readonly	Discover the tenant's verified domains
https://www.googleapis.com/auth/gmail.settings.basic	Create the Gmail filter that blocks a sender domain

You authorize all four together in Step 6.

The read-write admin.directory.user scope already covers reads. The integration still requests the .readonly variant explicitly for read operations as a defense-in-depth boundary — read-only tokens can't accidentally mutate the directory. Authorize both.

Step 1 — Open or create a Google Cloud project#

The service account lives inside a Google Cloud project. Any project works — reuse an existing one or create a dedicated project for the AgentSOC integration.

1. Go to the Google Cloud Console.
2. Use the project picker in the top bar to select or create a project.

Step 2 — Enable the Admin SDK and Gmail APIs#

The integration calls two Google APIs. With your project selected, enable both:

• Admin SDK API — directory (user) operations.
• Gmail API — sender-blocking filters.

Click Enable on each page.

Step 3 — Create a service account#

1. Open IAM & Admin → Service Accounts.
2. Click Create service account.
3. Give it a recognizable name, e.g. agentsoc-workspace.
4. Skip the optional role/permission steps — Workspace access is granted later via domain-wide delegation, not via Cloud IAM. No project roles are required.

Step 4 — Create and download a JSON key#

1. Open the service account and go to the Keys tab.
2. Click Add key → Create new key → JSON.
3. A .json file downloads. This is the Service Account JSON you paste into AgentSOAR.

Treat this file like a password. The private key inside cannot be recovered after download — if you lose it, generate a new key from the Keys tab and delete the old one. Rotate keys periodically and remove unused entries.

If your organization enforces the iam.disableServiceAccountKeyCreation org policy, this step will fail with a permission error. Either request a scoped exception for this project, or have an admin create the key from an exempt project and share the JSON.

Step 5 — Copy the service account's Client ID#

On the service account's Details tab, copy the Unique ID — a ~21-digit number. This is the OAuth Client ID the next step needs.

Use the numeric Client ID — not the service account email. Pasting the email into the next step is the most common cause of an unauthorized_client error.

Step 6 — Authorize domain-wide delegation in the Admin Console#

This is the step that actually grants the service account access to Workspace data. It must be done by a Workspace super-admin.

1. Open Admin Console → Security → API controls → Domain-wide delegation.

2. Click Add new.

3. Client ID — paste the numeric Client ID from Step 5.

4. OAuth scopes — paste all four scopes, comma-separated:

   https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/gmail.settings.basic

5. Click Authorize.

Changes usually apply within minutes but can take up to 24 hours to propagate.

Step 7 — Pick the delegated admin email#

The service account cannot act as itself against Workspace — it impersonates a real admin user. The chosen email becomes the Delegated Admin Email in AgentSOAR, and every Directory and Gmail call will run with this person's authority.

Choose an active Workspace account that holds the admin privileges the four scopes require:

• User Management — read and suspend users
• Domain Management — read verified domains

For least-privilege, prefer a dedicated admin user with a custom admin role granting only those two privileges, rather than a super-admin. A super-admin works but grants far broader authority than the integration needs and widens the blast radius if the JSON key is ever compromised. Use super-admin only if your tenant can't assemble the privileges via a custom role.

Do not use the service account's own email (*.iam.gserviceaccount.com) here. It must be a real, active Workspace user with admin privileges. Using the service account's email is a frequent cause of invalid_grant at validation time.

Step 8 — Customer ID#

Use my_customer (the literal string) as the Customer ID. This alias automatically resolves to the delegated admin's own tenant — correct for virtually every organization. AgentSOAR also accepts the field being left blank, in which case the integration falls back to my_customer.

Set an explicit customer ID only for reseller / multi-tenant service accounts that manage more than one Workspace tenant. You can find it in Admin Console → Account → Account settings (a value like C03az79cb).

Step 9 — Add the credential in AgentSOAR and validate#

1. In AgentSOAR, open Settings → Credentials (/agentsoar/settings/credentials).
2. Add a Google Workspace credential and enter:
   • Service Account JSON — the file from Step 4.
   • Delegated Admin Email — the admin from Step 7.
   • Customer ID — my_customer (or leave blank).
3. Save. AgentSOAR validates the credential immediately.
4. Once it shows Healthy, open Inventory and sync to pull in your Workspace users.

Troubleshooting#

Error	Likely cause and fix
unauthorized_client	The Client ID isn't authorized for domain-wide delegation, or the authorized scopes don't match. Re-check Step 6 — verify the numeric Client ID (not the service account email) and that all four scopes are present, exactly.
invalid_grant / 400	The Delegated Admin Email is wrong, inactive, the service account's own email, or not a real user in this tenant. Confirm it in the Admin Console users list.
403 — notAuthorized / forbidden	The impersonated user lacks the required admin privileges. Grant User Management + Domain Management via a custom role, or use a super-admin (see Step 7).
403 — accessNotConfigured	The Admin SDK or Gmail API isn't enabled on the Cloud project that owns the service account. Re-check Step 2.
Worked only after a delay	Domain-wide delegation changes can take up to 24 hours to propagate. If everything looks correct, wait and re-validate.

Reference: Google — Control API access with domain-wide delegation

Related#

• AgentSOAR overview
• AgentSOAR capabilities
• Google Cloud Platform (GCP)
• Microsoft 365