Google Workspace service account setup#

A complete, step-by-step walkthrough for producing the credentials AgentSOC needs to manage your Google Workspace tenant — listing users, suspending compromised accounts, and blocking malicious sender domains.

Screenshots: image placeholders below point at docs/images/gws-*.png. Capture each screenshot and drop it in at that path — the captions describe exactly what to show.

---

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 AgentSOC.

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 AgentSOC.

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 AgentSOC, 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. AgentSOC 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 AgentSOC and validate#

1. In AgentSOC, open AgentSOAR → 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. AgentSOC 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