Google Cloud service account setup

A step-by-step walkthrough for producing the credentials AgentSOC needs to act on your Google Cloud project — blocking attacker IPs with project firewall rules, isolating Compute Engine instances with a quarantine tag, and powering instances on and off.

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

How the connection works

AgentSOC authenticates to Google Cloud with a service account key — a JSON file that identifies a service account granted Compute Engine permissions on your project. Two values (plus an optional one) go into the credential form:

ValueWhat it is
Project IDThe GCP project where your Compute Engine resources live
Service account JSONThe downloaded key file that authenticates AgentSOC
Region (optional)A default region/zone — leave blank to rely on per-resource locations

By the end of this guide you will have a validated credential in AgentSOC.

Step 1 — Open or select a Google Cloud project

Go to the Google Cloud Console and select (or create) the project that contains the Compute Engine instances you want AgentSOC to manage. Note its Project ID (not the display name).

Step 1 — Google Cloud Console project picker

Step 2 — Enable the Compute Engine API

Open the Compute Engine API page with your project selected and click Enable.

Step 2 — Enable Compute Engine API

Step 3 — Create a service account

  1. Open IAM & Admin → Service Accounts.
  2. Click Create service account and name it e.g. agentsoc-soar.

Step 3 — Create service account

Step 4 — Grant Compute roles

On the Grant this service account access to project step, add the roles the integration's actions need:

  • Compute Instance Admin (v1) — roles/compute.instanceAdmin.v1 — read, start, stop, and tag instances.
  • Compute Security Admin — roles/compute.securityAdmin — create and delete the firewall rules used to block attacker IPs.

For least-privilege, replace these with a custom role limited to the compute.instances.*, compute.firewalls.*, and compute.networks.get permissions.

Step 4 — Grant Compute roles

Step 5 — 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 cannot be recovered after download — if you lose it, generate a new key and delete the old one.

If your organization enforces the iam.disableServiceAccountKeyCreation org policy, this step fails with a permission error. Request a scoped exception, or have an admin create the key from an exempt project.

Step 5 — Create JSON key

Step 6 — Add the credential in AgentSOC and validate

  1. In AgentSOC, open AgentSOAR → Settings → Credentials (/agentsoar/settings/credentials).
  2. Add a Google Cloud credential and enter:
    • Project ID — from Step 1.
    • Service Account JSON — the file from Step 5.
    • Region — optional; leave blank unless you want a default.
  3. Save. AgentSOC validates the key with a Compute Engine API probe.
  4. Once it shows Healthy, the Google Cloud action capabilities are ready to use.

Step 6 — AgentSOC Add Google Cloud credential form

Troubleshooting

ErrorLikely cause and fix
credentials_json must be a valid GCP service account JSONThe pasted text isn't a complete service account key. Paste the full contents of the downloaded .json file, including the private_key.
Compute Engine API has not been used in project … or it is disabledThe Compute Engine API isn't enabled on this project. Re-do Step 2.
403 — Permission deniedThe service account is missing roles. Re-check Step 4 — it needs Compute Instance Admin and Compute Security Admin.
The project … was not foundThe Project ID is wrong (you may have used the display name). Copy the exact Project ID from the console.

Reference: Google Cloud — Create and manage service account keys