Organizations (GCP)

Integrating a GCP Organization with InsightCloudSec

You can add multiple GCP projects within an organization structure seamlessly into InsightCloudSec using the Organizations feature. This allows automatic onboarding of all associated projects (including any new projects added after initial onboarding) into InsightCloudSec and badging of project level labels and organization/folder structure.

InsightCloudSec performs this onboarding and harvesting through the use of a GCP Service Account. This Service Account will be defined within a project with organization level permissions to allow for digesting the organization structure of projects and folders. After processing the organization structure and onboarding the desired projects, it will reach out to each project's API services for gathering resource information into InsightCloudSec.

Note: this page and the functionality detailed here refer to the cloud provider-specific organizational onboarding capability for GCP, which is managed under "Clouds --> Organizations". This functionality should not be confused with the InsightCloudSec-specific Organizations capability that allows for multi-tenant functionality available under "System Administration --> Organizations".


Before you get started you will want to make sure you have the following:

  • A functioning InsightCloudSec Installation
  • An InsightCloudSec Domain Admin within InsightCloudSec to work with GCP Organizations
  • Appropriate permissions in GCP to create service accounts, roles, and enable APIs. You must have the appropriate level of access in GCP to create Service Accounts within a project, and access to create and apply Roles at the organization level

You will need to be a Domain Admin within InsightCloudSec to work with Organizations.

If you have questions or concerns, reach out to us through the Customer Support Portal.


Important Note About APIs

For successful onboarding Cloud Resource Manager API, Cloud Asset API, and Service Usage API are required to be enabled in the project containing the Service Account that will be provisioned.

Due to the current GCP harvesting structure in InsightCloudSec, API services will need to be enabled in each project (including the project containing the Service Account) for proper harvesting. See our list of Recommended APIs.

Steps for Adding GCP Organizations (GCP Console)

The following sections involve resource creation/modification within the GCP console.

Service Account Creation

Service accounts can only be created within a project, so choose the project, or consider creating a new project for the service account for InsightCloudSec to reside in. The following steps will take place within that project.

1. Navigate into "IAM & Admin > Service Account".

2. Click "Create Service Account" and complete the service account details.

  • We recommend including ICS or InsightCloudSec here for tracking purposes.
GCP - Create Service AccountGCP - Create Service Account

GCP - Create Service Account

4. Click "Done" to create the Service Account.

Generating a Service Account Key

1. Navigate into the newly created Service Account.

  • Note the associated email; it will be used in a later step.

2. In the Keys section, select "ADD KEY".

3. Select "Create New Key".

Creating a new Service Account KeyCreating a new Service Account Key

Creating a new Service Account Key

4. With Key Type as JSON, click "Create" to download the key.


Store this JSON file in a secure place; it contains the only copy of the key.

Role Creation and Assignment

The following steps take place at the Organization level. Navigate into the Organization using the project selection dropdown and select the appropriate Domain in the listing.

GCP - Select DomainGCP - Select Domain

GCP - Select Domain

Custom Role Creation

1. Navigate into "IAM & Admin > Roles".

2. Click "Create Role".

3. Name your role and give it a description.

  • We recommend including InsightCloudSec or ICS in the name and description

4. Click add permissions, and using the filter field provided, select the following permissions:
- storage.buckets.get
- storage.buckets.getIAMPolicy
- bigquery.tables.get
- bigquery.tables.list
- cloudasset.assets.listResource


Required Permissions

The cloudasset.assets.listResource permission is required for proper resource harvesting as InsightCloudSec expands the use of Cloud Asset Inventory.

5. Click "Create" to save the new Role.

GCP - Add PermissionsGCP - Add Permissions

GCP - Add Permissions

Assigning Roles to Service Account

1. Navigate to "IAM & Admin--> IAM" and click "Add".

Add roles to Service AccountAdd roles to Service Account

Add roles to Service Account

2. Paste in the Service Account Email (taken from the Service Account details page) into the "New members" field.

3. To promote the Service Account inside the domain and grant members permissions for your GCP organization, go to the IAM sub-menu under "IAM & Admin" on the navigation bar.

  • Select the Members tab.
  • Select the Add tab.
  • Paste the service account email address in the New member field.
  • Select the following roles necessary for complete organization visibility/harvesting:
    • Resource Manager -> Organization Viewer (Organization Administrator if you're setting up write permissions)
    • Resource Manager -> Folder Viewer
    • IAM -> Security Reviewer
    • Project -> Viewer (Editor to allow InsightCloudSec to have write permissions into GCP)
    • Custom -> Custom InsightCloudSec Role created in previous steps

4. Click "Save".

GCP - Service AccountGCP - Service Account

GCP - Service Account

Setup in InsightCloudSec

Follow the steps below to onboard the GCP organization into InsightCloudSec. These take place within the InsightCloudSec UI.

1. Navigate to the "Cloud --> Clouds" page.

2. Click the "Organizations" tab, then click "Add Organizations".

Adding an OrganizationAdding an Organization

Adding an Organization

3. Select "GCP" from the "Cloud Type" drop-down menu.

4. Provide a nickname for the Organization. This creates a system Badge containing the nickname that can be searched or referenced throughout InsightCloudSec.

5. Paste in the JSON credentials from the Service Account Key you created on the GCP console above.

6. Select your desired Organization options as follows:

  • Select the "Limit import scope" checkbox and provide Parent Folder ID(s) to only include the given folder(s) and anything underneath it.
  • The "Auto-Sync Projects" checkbox is enabled by default and allows InsightCloudSec to auto-sync with Projects in your Organization. Note: if you deselect this option you will have to manually add your accounts.
  • The "Auto-Remove Deleted Accounts" checkbox is enabled by default. If you want to prevent InsightCloudSec from removing accounts that are deleted from GCP you will need to uncheck this box.
  • The "Auto Badge Projects" is enabled by default and allows InsightCloudSec to auto-badge your projects.

7. Optional - Limit Import scope: When checked this option allows you to specify Folder IDs limiting the projects onboarded to only projects contained in those folders.


Import Scope Changes

To change the import scope to a different folder, or to remove the scope entirely navigate to "Clouds --> Organizations". Select the pencil next to the name of the Organization you want to modify. You will need to input the JSON credentials again in order to make this change.

8. Click "Add" to start the onboarding process

Your Organization will now be listed within the Organizations section. Initially, the listing will show '0' accounts. Projects, resource data, and compliance data will be processed and begin to show up and reflect within the tool after the initial harvesters and processors complete.**

Auto Badging

InsightCloudSec includes auto-badging capabilities to create a 1:1 map of GCP project-level labels to Badges in InsightCloudSec. This allows Clouds to be scoped to a badge that maps to the account tag.

For GCP Organizations that have auto badging of projects enabled, all clouds corresponding with a project that do not have a parent folder will have a cloud_org_path badge with a value of '/' to signify they are at the root.

Selecting the "Auto Badge Projects" option will also provide automatic badging for Organizations that utilize folders through the new gcp_folder badge.

This badge can be extremely helpful for managing scope around Insights, Bots, and the Compliance Scorecard views for organizational units and lines of business within your cloud footprint.

Auto badging takes place in two stages.

  • Periodically a process retrieves tags/labels from each account/project and compares them with ResourceTags associated with the corresponding cloud in the InsightCloudSec database.

    • If there are any changes detected, the ResourceTags in the database are overwritten with the values from the account/project. This means that Cloud Account tags should not be locally modified since any local changes will be overwritten the next time the process runs. Additionally any local changes that are made to Cloud Account tags are not pushed back up to the cloud provider.
  • Periodically a process retrieves all ResourceTags from the local database that are associated with the accounts managed by an organization. For each cloud the list of tags for that cloud is compared with the current list list of Badges and for each Key/Value pair of tags:

    • Existing Badges with a Key prefix of system. are skipped.
    • If the corresponding Badge with the Key/Value pair for that cloud does not already exist, it is created.
    • If a tag Value changes the Badge with the corresponding Key will be updated to that value.
    • If a Badge no longer has a tag with a corresponding Key, it will be deleted.
    • All Badges that have a corresponding tag will have their autogenerated column set to ‘true’ even if they were previously set to ‘false’.

Did this page help you?