Skip to main content

Connect a GCP project

Connecting a Google Cloud project lets Retrievy's CSPM scanner audit your GCP resources. Findings flow into the Command Center and feed your Retrievy Index the moment the first scan lands.

GCP uses a service account with a downloaded JSON key. There's no OAuth Quick Connect for GCP today; service-account JSON is the only supported path.

Before you start​

You need:

  • A GCP project where you (or a project owner) can create service accounts and grant IAM roles.
  • A Retrievy workspace with CSPM enabled (every plan).
  • The manage-cloud-accounts permission in Retrievy.
  • One free data-source slot on your plan. See plan feature matrix.

Step 1. Enable the APIs Retrievy needs​

In the GCP console, open the project you want to connect, then enable these three APIs from APIs & Services → Library:

  • Cloud Asset API (cloudasset.googleapis.com)
  • Cloud Resource Manager API (cloudresourcemanager.googleapis.com)
  • Security Command Center API (securitycenter.googleapis.com)

Each API takes a moment to activate. If you skip this step, the first Retrievy scan returns Cloud Asset API has not been used in project and stops.

If you're connecting an entire organisation or folder later, enable the same APIs at the organisation level so child projects inherit them automatically.

Step 2. Create a read-only service account​

In the GCP console, open IAM & Admin → Service Accounts → Create service account.

  1. Name: retrievy-cspm-reader. The Service account ID auto-fills.
  2. Description: Read-only service account for Retrievy CSPM scans. Click Create and continue.
  3. Grant access step: add these three IAM roles, one at a time:
RoleWhy Retrievy needs it
Viewer (roles/viewer)Reads every GCP resource Retrievy audits (compute, storage, networking, etc.).
Security Reviewer (roles/iam.securityReviewer)Reads IAM policies, role bindings, and audit configs.
Cloud Asset Viewer (roles/cloudasset.viewer)Enumerates resources via the Cloud Asset API in one call instead of per-service.
  1. Click Continue, then Done (skip the optional user-access step).

These three roles together give Retrievy the read access it needs and no write permissions anywhere. The Viewer role specifically is read-only across the project.

Step 3. Generate a JSON key​

Still on the service account you just created:

  1. Click the service account name to open its detail page.
  2. Open the Keys tab → Add key → Create new key.
  3. Pick JSON as the key type. Click Create.

A .json file downloads to your machine. Open it in any text editor; you'll paste the entire contents into Retrievy in the next step.

caution

The JSON key is a long-lived credential with read access to your entire project. Treat the file like a password. Delete the downloaded copy from your machine once you've pasted it into Retrievy, and rotate it from the Keys tab regularly.

Step 4. Add the project in Retrievy​

In Retrievy:

  1. Open Settings → Cloud Integrations → Add Cloud Account.
  2. On the IDENTIFY TARGET step, pick GCP from the provider tiles. Click Next.
  3. The INGEST CREDENTIALS step shows two fields:
FieldWhat to paste
Project IDYour GCP project ID (not the project number, not the project name). Visible at the top of the GCP console.
Service Account Key JSONThe full JSON file contents. Paste the entire object, including the curly braces.

  1. Click Next. Retrievy validates the JSON shape (it must include type: "service_account", project_id, private_key, and client_email), then signs a JWT with the private key and exchanges it for an access token at Google's OAuth endpoint. If the token comes back, the credentials are good and the wizard advances.

  2. On the final step, click Finish. The first scan queues automatically.

Step 5. Watch the first scan​

The new account card appears in Settings → Cloud Integrations with a Scanning... state. Findings start arriving in the Command Center within minutes for small projects, longer for large ones.

You can also watch progress in the Recent Scans list at the bottom of the Command Center.

What Retrievy scans​

The GCP CSPM module covers the standard service-by-service audit set: IAM (members, roles, custom roles, primitive role usage), Cloud Storage (bucket policies, uniform access, public exposure), Compute Engine (firewall rules, OS Login, shielded VMs), Cloud SQL (auth, encryption, public IP), Cloud KMS (key rotation, IAM), VPC (firewall logging, default networks), Cloud Logging and Monitoring (sinks, alerting), and more.

Every finding lands with its compliance mappings so it shows up in both the Kanban and the Compliance Hub without extra configuration.

Connecting an entire organisation​

To audit every project in your GCP organisation with one credential set:

  1. Create the service account in a dedicated host project (typically a security or shared-services project).
  2. Grant the three roles above at the organisation scope instead of the project scope (IAM & Admin → IAM at the org level).
  3. Enable the three APIs at the organisation level.
  4. Add the credential to Retrievy with the host project's project ID. Retrievy enumerates every project the service account can see and includes them in scans.

Each project still counts as one data-source slot in your plan. If you have more projects than your plan covers, contact support about the Build Your Own tier.

Rotating the JSON key​

  1. In GCP, open the service account → Keys → Add key → create a new JSON key. Download it.
  2. In Retrievy, open the GCP account detail → Update credentials → paste the new JSON. Save.
  3. Once Retrievy confirms the new key works (a fresh Test Connection passes), delete the old key from GCP.

Revoking access​

  1. In Retrievy, Deactivate the account (pauses scans) or remove it entirely (releases the slot).
  2. In GCP, either disable the service account or delete it. Disabling is reversible; deleting is not.

Troubleshooting​

Symptom: Wizard rejects the JSON with Invalid service account key. → Fix: You probably pasted only the private_key value instead of the full JSON object. Open the downloaded file in a text editor and copy everything from the opening { to the closing }, including all surrounding fields.

Symptom: First scan fails with Cloud Asset API has not been used in project X before or it is disabled. → Fix: Skipped step 1. Enable the Cloud Asset API on the project (you may also need to wait a minute for GCP to propagate the change). Re-trigger the scan.

Symptom: Scan succeeds but every IAM-related finding is missing. → Fix: The service account doesn't have Security Reviewer. Open IAM for the project, add roles/iam.securityReviewer to the service account, and re-scan.

Symptom: I get 403 PERMISSION_DENIED on Compute Engine resources. → Fix: The Compute Engine API needs to be enabled on the project too. Enable Compute Engine API in APIs & Services → Library, then re-scan.

Symptom: I want to scan a specific subset of projects in my organisation, not all of them. → Fix: Grant the service account roles at the folder scope rather than the organisation scope; Retrievy will only see projects inside folders where it has access.

Symptom: Scan completes but the project shows No findings for everything. → Fix: Either the project genuinely has no misconfigurations (rare but possible on brand-new empty projects), or the service account's roles aren't applied yet. In GCP IAM, double-check the three roles are listed against the service account email. Wait 2 minutes for IAM propagation, then re-scan.