Google Cloud Platform (GCP)

Description

The Google Cloud Platform connector recursively discovers and scans IAM policy bindings across an entire Google Cloud organization — the organization itself, every folder and sub-folder beneath it, and every project under any of those folders (or directly under the org) — plus the IAM service accounts within each discovered project. It authenticates using a service account with a private key via the OAuth 2.0 JWT bearer flow — no GCP SDK installation is required on the OrbisID server.

This connector replaces the earlier separate "GCP" (single-project) and "Google Cloud IAM" (org-level only, no project drill-down) connectors, which left a gap: neither one alone gave full visibility into an organization's access without manually adding a system per project.

System Type Classification

Field	Value
System Type	Infrastructure
Default Scan Priority	500

Version Support

OrbisID Edition	Supported
Community	No
Pro	Yes
Enterprise	Yes

Google Cloud Platform scanning requires a Pro or Enterprise licence.

Supported Protocol

Protocol	Port	Notes
Google Cloud REST API (HTTPS + OAuth 2.0 JWT)	443 TCP	Cloud Resource Manager and IAM endpoints

What OrbisID Discovers

Data	Source
Organization IAM policy bindings	POST /v3/organizations/{orgId}:getIamPolicy
Every folder and sub-folder under the organization	GET /v3/folders?parent=organizations/{orgId} (recursive)
Folder IAM policy bindings	POST /v3/folders/{folderId}:getIamPolicy (per folder)
Every project under the org or any folder	GET /v3/projects?parent=... (recursive)
Project IAM policy bindings	POST /v1/projects/{projectId}:getIamPolicy (per project)
Service accounts per project	GET /v1/projects/{projectId}/serviceAccounts
IAM members by type	user:, serviceAccount:, group:, domain: prefixes extracted from bindings at every level

Privileged Roles Detected

roles/owner, roles/editor, roles/iam.securityAdmin, roles/iam.roleAdmin, roles/resourcemanager.organizationAdmin, roles/resourcemanager.folderAdmin, roles/resourcemanager.projectIamAdmin, roles/iam.serviceAccountAdmin, roles/iam.serviceAccountTokenCreator, roles/iam.serviceAccountKeyAdmin, roles/billing.admin, roles/compute.admin, roles/storage.admin, roles/bigquery.admin, roles/cloudsql.admin, roles/container.admin, roles/orgpolicy.policyAdmin

Connection Requirements

GCP Service Account

Create a dedicated service account and grant it organization-level IAM read access — this single grant covers discovery at every level (org, folders, projects) since IAM read permissions granted at the organization are inherited down the resource hierarchy.

Required IAM permissions at the organization level:

Permission	Purpose
resourcemanager.organizations.getIamPolicy	Read the organization IAM policy
resourcemanager.folders.list	Enumerate folders and sub-folders
resourcemanager.folders.getIamPolicy	Read IAM policies on folders
resourcemanager.projects.list	Enumerate projects under the org and each folder
resourcemanager.projects.getIamPolicy	Read IAM policies on projects
iam.serviceAccounts.list	List service accounts within each project

Recommended role: roles/iam.securityReviewer at the organization level — it includes all of the permissions above.

Steps to create the service account:

1. In the GCP Console, navigate to APIs & Services → Library on the service account's own project, and Enable both the Cloud Resource Manager API and the IAM API. This is required independently of the organization-level role grant below — without it, every call (including folder/project discovery) fails with 403: ... API has not been used in project ... or it is disabled.
2. Navigate to IAM & Admin → Service Accounts
3. Click Create Service Account — name it (e.g., orbisid-org-scanner)
4. At the Organization level in IAM (not the project level), grant this service account the Security Reviewer role
5. Under the service account, click Manage Keys → Add Key → Create new key → JSON
6. Download the JSON key file — extract the private_key and private_key_id fields

Credential Mapping

OrbisID Field	GCP Value
credential.username	Service account email (e.g., orbisid-org-scanner@project-id.iam.gserviceaccount.com)
credential.privateKey	Service account private key (PEM format — the private_key field from the JSON key file)
credential.domain	Private key ID (the private_key_id field from the JSON key file, optional)

Use the Private Key field, not Password

The PEM key goes in the Credential form's Private Key field (a multi-line box — the same one used for Linux SSH keys), not Password. Password renders as a single-line masked input, which silently strips line breaks out of anything multi-line pasted into it; Private Key is a plain multi-line textarea, so the key's line structure survives.

Pasting the private_key value from the JSON file

Opened as plain text, the downloaded JSON key file's private_key value looks like this:

"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n"

Those \n are literal backslash-n characters — how JSON encodes a line break in a string — not actual line breaks. Pasting that text as-is into the Private Key field used to fail with an opaque Illegal base64 character 5c error; OrbisID now automatically converts those literal \n sequences into real line breaks when the credential is saved, so pasting the JSON value verbatim works either way. If you're instead typing the key out from a JSON-aware viewer/editor (which usually renders \n as real line breaks already), that also works unchanged.

System Attributes

Attribute	Required	Description
googleCloudOrgId	Yes	The numeric Google Cloud organization ID to scan (e.g., 123456789012), found in IAM & Admin → Settings or via gcloud organizations list

Network Requirements

Requirement	Detail
Outbound HTTPS	OrbisID server (or On-Premise Agent) must reach oauth2.googleapis.com, cloudresourcemanager.googleapis.com, and iam.googleapis.com on port 443

Configuration Steps

1. Create the GCP service account and grant Security Reviewer at the organization level
2. Download the JSON key file and extract the private_key (PEM) and private_key_id
3. Create a Credential in OrbisID:
   • Username: Service account email
   • Private Key: Private key PEM, including the full -----BEGIN PRIVATE KEY----- block (paste the JSON file's private_key value as-is — see the tip above)
   • Domain: Private key ID (optional)
   • Leave Password blank
4. Navigate to Systems → Add System
5. Fill in the fields:

Field	Value
Name	Descriptive name (e.g., GCP – my-org)
Hostname	cloudresourcemanager.googleapis.com (used for reference)
OS Type	Google Cloud Platform (GCP)
System Type	Infrastructure
Credential	The GCP service account credential

6. Set the Google Cloud Organization ID attribute to the numeric organization ID
7. Click Test Connection to verify the service account can obtain a token
8. Click Save

Recursive by design

One system covers the whole organization — there is no need to add a separate system per project. The scanner walks every folder and project under the org automatically on each scan.

Real-Time Account & Entitlement Events

Beyond periodic full scans, OrbisID can pull a Pub/Sub subscription (fed by a Cloud Logging sink on Admin Activity audit logs you configure) to detect service account create/delete/enable/disable events near-real-time. See Real-Time Events — Pro/Enterprise only. IAM policy binding (role grant/revoke) changes are not detected this way.

Troubleshooting

Symptom	Likely Cause	Resolution
Scan fails: "Google Cloud organization ID is required"	googleCloudOrgId attribute not set	Set the Google Cloud Organization ID attribute on the system
401 Unauthorized / token error	Invalid private key PEM or service account email	Verify the PEM includes the full key block; ensure the service account email is correct
Scan fails: "private key PEM (credential's Private Key field) is required"	The key was pasted into Password instead of Private Key, or left empty	Move the PEM into the credential's Private Key field
Illegal base64 character 5c / "Private key contains literal '\n' characters instead of real line breaks"	A credential saved before this connector auto-normalized the key still has the literal \n escapes baked into its stored value	Open the credential and click Save again (no changes needed) — this re-applies the fix. New credentials are normalized automatically on first save
"Private key is not valid Base64..." / "Private key data does not decode as a valid PKCS#8 RSA key"	The pasted key was truncated, re-wrapped, or edited	Re-download the JSON key file and paste the private_key value again, unmodified, including the full -----BEGIN/-----END block, into the Private Key field
403 PERMISSION_DENIED on org/folder/project policy	Missing IAM permissions at the organization level	Grant roles/iam.securityReviewer (or the individual permissions listed above) at the organization, not project, level
403 — "Cloud Resource Manager API has not been used in project ... or it is disabled"	Cloud Resource Manager API not enabled on the service account's own GCP project	Visit the URL in the error message (or APIs & Services → Library in the GCP Console) and click Enable; wait a minute or two, then retest
403 — "IAM API has not been used in project ... or it is disabled"	IAM API not enabled on the service account's own GCP project (blocks service account enumeration)	Enable the IAM API on the same project via APIs & Services → Library
"Service account enumeration skipped" — 403 Request had insufficient authentication scopes / ACCESS_TOKEN_SCOPE_INSUFFICIENT	Fixed in this connector — earlier versions requested only the cloud-platform.read-only OAuth scope, which the IAM API does not accept for serviceAccounts.list (unlike the Cloud Resource Manager API)	Upgrade to the current connector version, which also requests the iam scope; no GCP-side configuration change needed
invalid_grant error	Private key ID mismatch or key revoked	Re-download the JSON key file; verify the key is active in the GCP Console
Some projects missing from results	Service account lacks org-level inheritance, or a project denies inherited IAM policies	Confirm the role was granted at the organization level; check for IAM deny policies on the affected project
Connection timeout	GCP API endpoints blocked	Ensure outbound HTTPS access to *.googleapis.com on port 443
System was migrated from an old "GCP" connector and now fails immediately	The old project-only connector never stored an organization ID	Set the Google Cloud Organization ID attribute — this is a one-time manual step after upgrading