Google Cloud Platform (GCP)
Connector maturity: GA. See Connector maturity.
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:
- 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. - Navigate to IAM & Admin → Service Accounts
- Click Create Service Account — name it (e.g.,
orbisid-org-scanner) - At the Organization level in IAM (not the project level), grant this service account the
Security Reviewerrole - Under the service account, click Manage Keys → Add Key → Create new key → JSON
- Download the JSON key file — extract the
private_keyandprivate_key_idfields
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) |
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.
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 |
googleCloudCollectUsage | No | Read when each service account last authenticated (see When Service Accounts Were Last Used). Off by default |
googleCloudCollectCredentials | No | Read the user-managed keys of each service account (see Service Account Key Metadata). Off by default |
Service Account Key Metadata
With Read Service Account Key Metadata on, each scan lists the user-managed keys of every discovered service account (one IAM call per service account) and records each key's ID and its valid-from and valid-until dates. The key itself is never read. A key that never expires (Google reports the end of year 9999) is shown with no expiry, and a disabled key is shown as inactive. When Read When Service Accounts Last Authenticated is also on, each key's last use comes from the same Policy Intelligence data; otherwise it is shown as not reported. The scanning identity needs iam.serviceAccountKeys.list (in roles/iam.serviceAccountKeyAdmin or roles/iam.securityReviewer). Service accounts whose keys cannot be read are skipped with a warning, and credentials already recorded are kept.
When Service Accounts Were Last Used
With Read When Service Accounts Last Authenticated on, each scan also reads Google Policy Intelligence's Activity Analyzer and shows the result as the Last Used date on the service accounts it finds. The date is the later of the service account's own last sign-in and the last sign-in of any of its keys.
- Service accounts only. Policy Intelligence does not report when people (users or groups) last signed in, so those accounts keep no GCP-sourced date. It also reports sign-ins, not which individual permissions or roles were used, so roles show no usage date.
- 90 days. Google keeps this data for 90 days. A service account with no sign-in in that period has no date: that means no recent use, not that it was never used.
- Reading it needs the Policy Analyzer API enabled on the project, and the scanning service account needs
roles/policyanalyzer.activityAnalysisViewer(permissionpolicyanalyzer.serviceAccountLastAuthenticationActivities.queryand the key equivalent) on the organization. The scan then also requests thecloud-platformOAuth scope, which the Policy Analyzer API requires; the service account's roles still limit what it can read. A project whose data cannot be read is skipped with a warning in the scan log and the rest of the scan continues. - Outbound HTTPS to
policyanalyzer.googleapis.comon port 443.
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
- Create the GCP service account and grant Security Reviewer at the organization level
- Download the JSON key file and extract the
private_key(PEM) andprivate_key_id - 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'sprivate_keyvalue as-is — see the tip above) - Domain: Private key ID (optional)
- Leave Password blank
- Navigate to Systems → Add System
- 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 |
- Set the Google Cloud Organization ID attribute to the numeric organization ID
- Click Test Connection to verify the service account can obtain a token
- Click Save
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 |
Scan fails reading the organization, a folder, a project's IAM policy or its service accounts (403 PERMISSION_DENIED or another error) | Missing IAM permissions, or an API turned off for that project | Grant roles/iam.securityReviewer (or the individual permissions listed above) at the organization, not project, level, and make sure the IAM API is enabled on every project. The scan fails rather than skipping what it cannot read, because the accounts and roles only that part grants would otherwise be archived. A project deleted while the scan runs, or waiting for deletion, is skipped instead. A throttled scan is retried later |
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 |
Scan fails listing service accounts — 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 |
| Scan fails for a project | 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 |