Onboard a GCP Organization

After InsightCloudSec is successfully installed, you're ready to start harvesting data from your Accounts, which requires configuring Google Cloud Platform (GCP) to "talk" with InsightCloudSec securely. As your inventory grows and your cloud accounts are fully visible, you can then begin to leverage the rest of InsightCloudSec, including Insights, Bots, Layered Context, and more.

This page and the functionality detailed here refer to the provider-specific Accounts and Organizations capability available under Cloud > Cloud Accounts (individual accounts are listed on the Listing page; Organizations are listed on the Organizations page). This functionality should not be confused with the InsightCloudSec-specific Organizations capability that allows for multi-tenant functionality available under System Administration > Organizations. If you are looking to onboard a single GCP Account instead, see Onboard an GCP Account.

Opening the Cloud Account Onboarding Interface

Before you can begin the onboarding process, you'll need to navigate to the Cloud Account Onboarding interface, which provides a different experience depending on the type of user you are:

UserDescriptionExperience
First-time UserInsightCloudSec is freshly deployed and this will be the first time a Cloud Service Provider (CSP) has been onboarded.Platform Users:
Onboarding wizard launched from Platform Home by clicking the InsightCloudSec tile.

InsightCloudSec Only Users:
The onboarding wizard appears automatically after logging in using your unique InsightCloudSec URL.
Returning UserInsightCloudSec has one or more CSPs already onboarded and you would like to add a new account.Launched from within InsightCloudSec. Not a wizard.
Admin UserYou can login to the cloud provider and have the appropriate access to grant InsightCloudSec access to your account(s).As an admin, you will need to complete some specific tasks within your Cloud Service Provider's (CSP) console to generate details needed for onboarding that either you or a non-admin user can input to InsightCloudSec.
Non-Admin UserYou can interact with InsightCloudSec and would like to onboard an account(s) but do not have the appropriate CSP access to grant InsightCloudSec access to your account(s).You will need to copy and send a message to the admin asking them to complete specific tasks and provide you with the information you need to complete onboarding.

Onboarding a GCP Organization

A couple methods for onboarding your GCP Organization are available depending on whether you're a non-admin or admin user.

Resuming cloud onboarding to InsightCloudSec

If you close the interface before completing Account onboarding, you can resume onboarding from the page you were on last.

Non-Admin User Instructions

Ask an admin for required information

As a non-admin user, you need to copy and send a message to the admin asking them to complete specific tasks and provide you with the information needed to complete onboarding.

First-time Users
  1. Login to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click InsightCloudSec to launch the onboarding wizard.
    • Open a browser window to your unique InsightCloudSec URL and login. The onboarding wizard will appear automatically.
  2. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
  3. On the Cloud Service Providers screen, select Google Cloud Platform.
  4. Select No - Help me identify the details needed, then click Next.
  5. Click the Copy button in the Google Cloud Platform Admin Instructions text box and share them with the admin.
Returning Users
  1. Login to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click the InsightCloudSec tile.
    • Open a browser window to your unique InsightCloudSec URL and login.
  2. Navigate to Cloud > Cloud Accounts in the left-hand navigation menu.
  3. Click the + Add Cloud button in the top right-hand corner.
  4. Click the Google Cloud Platform button.
  5. Click Don't have admin access? in the bottom right-hand corner of the window.
  6. Click the Copy button in the Google Cloud Platform Admin Instructions text box and share them with the admin.

Connect the Account

When your admin has completed their steps and provided the information to you, you can now connect the Account.

First-time Users
  1. Return to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click InsightCloudSec to launch the onboarding wizard.
    • Open a browser window to your unique InsightCloudSec URL and login. The onboarding wizard will appear automatically.
  2. The wizard should automatically return you to the Google Cloud Platform Admin Instructions page.
  3. Enter the following information (provided by your admin):
    1. Copy/paste the Nickname for the Account. This is a unique value that will be used to search Accounts across the system based on an identifiable label.
    2. Copy/paste the API Credentials and Project ID.
    3. Optionally, provide the Email Delegation.
  4. Click Connect Account.
Returning Users
  1. Login to InsightCloudSec using one of the methods below:
    • In the Insight Platform, click the InsightCloudSec tile.
    • Open a browser window to your unique InsightCloudSec URL and login.
  2. Navigate to Cloud > Cloud Accounts in the left-hand navigation menu.
  3. Click the + Add Cloud button in the top right-hand corner.
  4. Click the Google Cloud Platform button.
  5. Click Don't have admin access? in the bottom right-hand corner of the window.
  6. Enter the following information (provided by your admin):
    1. Copy/paste the Nickname for the Account. This is a unique value that will be used to search Accounts across the system based on an identifiable label.
    2. Copy/paste the API Credentials and Project ID.
    3. Optionally, provide the Email Delegation.
  7. Click Connect Account.
Admin User Instructions

As an admin, you must prepare your Organization for the connection with InsightCloudSec by creating a new service account & creating and assigning a custom role within GCP.

Providing details to a non-admin user?

If you are providing details to a non-admin user to onboard the Account, ensure that the credentials you share with the non-admin user will include the appropriate access and enable them to connect your GCP project with InsightCloudSec successfully. We recommend using a secure file sharing system to provide credentials to your non-admin user.

GCP Admin Onboarding Prerequisites

  • Domain Admin permissions within InsightCloudSec
  • Appropriate permissions in GCP to create service accounts, roles, and enable APIs within the desired project
    • If enabling Email Delegation/Directory Support, you'll need GCP Super Admin privileges

InsightCloudSec offers some features that require additional permissions/roles within GCP. It is easiest to perform this configuration while onboarding an account/organization. Review the links below to determine which features you'd like to use and we'll provide a reminder to select the relevant options later.

Prepare GCP for Onboarding

To onboard an organization for GCP you need to complete one of the following set of instructions:

Recommended APIs

For successful onboarding, the Cloud Resource Manager API, Cloud Asset API, Policy Analyzer 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.

Manual Onboarding using the GCP console

Multiple Browser Tabs/Windows Recommended

InsightCloudSec onboarding can proceed much more quickly and easily if you have both your InsightCloudSec instance and the GCP console open side-by-side in your preferred browser's windows/tabs.

Step 1: Create a Service Account
  1. Login to your InsightCloudSec instance and open the Cloud Onboarding interface.
    • First-time Users:
      1. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
      2. On the Cloud Service Providers screen, select Google Cloud Platform.
      3. Select Yes - I have permissions to create service accounts, roles and enable APIs, then click Next.
      4. For your connection journey, click Manual Steps, then click Next.
    • Returning Users:
      1. Navigate to Cloud > Cloud Accounts in the left navigation menu.
      2. Click the + Add Cloud button in the top right corner.
      3. Click the Google Cloud Platform button.
      4. For your connection journey, click Manual Steps.
  2. In a separate browser tab or window, login as an Admin to the GCP Console for the project you want to harvest.

In the GCP Console:

  1. Log in to your GCP account and select the project you want to onboard.
  2. On the project's dashboard, copy and save the Project ID.
  3. Go to IAM & Admin > Service Account, and click Create Service Account.
  4. Complete the service account details. We recommend including ICS or InsightCloudSec in the details for tracking purposes.
  5. Click Done.
  6. Copy and save the Service Account ID for generating a key and for onboarding the account in InsightCloudSec.
Step 2: Generate a Service Account Key

In the GCP Console:

  1. In the newly created Service Account, paste the Service Account ID into the filter input.
  2. Click the email address link to view the details.
  3. In the KEYS section, click ADD KEY.
  4. Select Create New Key.
  5. For the Key Type, select JSON, and then click Create to download the key.
  6. Copy and save this JSON file in a secure place; it contains the only copy of the key, which is required for onboarding the account in InsightCloudSec.

In the InsightCloudSec Cloud Onboarding interface:

  1. For 1. Authentication:
    1. Copy/paste the entire JSON key file into the API Credentials field.
    2. Copy/paste the project_id value from the JSON key file into the Project ID field.
    3. Click Next.
Step 3: Create a custom role (Organization-level Change)

Organization-level Change

This change must be performed at the organization level!

In the GCP Console:

  1. Go to IAM & Admin > Roles and click Create Role.
  2. Enter a name and description for the role. We recommend including InsightCloudSec here for tracking purposes.
  3. Click add permissions, and using the filter field provided, select the following permissions:
    • bigquery.tables.get
    • bigquery.tables.list
    • cloudasset.assets.listResource
    • cloudasset.assets.searchAllIamPolicies
    • iam.serviceAccounts.disable
    • serviceusage.services.enable
    • storage.buckets.get
    • storage.buckets.getIAMPolicy
  4. Click Add to finalize the permissions.
  5. Click Create to save the role.

Additional GCP-related InsightCloudSec Features

At this point in the process, it would be easiest to update the newly-created harvesting role with permissions for any additional GCP-related InsightCloudSec features.

Step 4: Assign Roles to the Service Account (Organization-level Change)

Organization-level Change

This change must be performed at the organization level!

In the GCP Console:

  1. Go to IAM & Admin > IAM and on the View by Principals tab, click Grant Access.
  2. In the New principals field, paste the Service Account Email (taken from the Service Account details page).
  3. Add the following roles to the Service Account.
    • Resource Manager > Organization Viewer (Organization Administrator if you're setting up write permissions)
    • Resource Manager > Folder Viewer
    • IAM > Security Reviewer
    • Basic > Viewer (Editor to allow InsightCloudSec to have write permissions into GCP).
    • Custom > Custom InsightCloudSec Role created in the previous section.
  4. Click Save.

Manual onboarding instructions complete!

After completing the preceding steps, you have completed the manual onboarding instructions for GCP. Jump to the Connect the Account in InsightCloudSec instructions.

Automated Onboarding using GCP Cloud Shell

Multiple Browser Tabs/Windows Recommended

InsightCloudSec onboarding can proceed much more quickly and easily if you have both your InsightCloudSec instance and the GCP console open side-by-side in your preferred browser's windows/tabs.

Step 1: Create a Service Account Automatically
  1. Login to your InsightCloudSec instance and open the Cloud Onboarding interface.
    • First-time Users:
      1. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
      2. On the Cloud Service Providers screen, select Google Cloud Platform.
      3. Select Yes - I have permissions to create service accounts, roles and enable APIs, then click Next.
      4. For your connection journey, click Google Cloud Platform Script, then click Next.
    • Returning Users:
      1. Navigate to Cloud > Cloud Accounts in the left navigation menu.
      2. Click the + Add Cloud button in the top right corner.
      3. Click the Google Cloud Platform button.
      4. For your connection journey, click Script.
  2. In a separate browser tab or window, login as an Admin to the GCP Console for the project you want to harvest.

In the InsightCloudSec Cloud Onboarding interface:

  1. Select Organization.
  2. Click Generate & Download Script.

In the GCP Console:

  1. In the top bar, click Activate Cloud Shell. If this is your first time using the Cloud Shell, you'll be prompted to learn more about the shell and click Continue. Review the GCP documentation for more information.

  2. Click More (vertical ellipsis), then click Upload and select the onboarding script from its downloaded location.

  3. Optionally, provide an alternative destination directory. By default, the file will be uploaded to /home/<username>.

  4. Click Upload.

  5. Ensure you are logged into the Cloud Shell: gcloud auth login.

  6. Run the script (python onboard.py) and follow the prompts to create everything needed to onboard the Account. If you uploaded the onboarding script to somewhere other than the default, you'll need to include the directory location with the command. If you're prompted to authorize the Cloud Shell using your credentials, click Authorize.

    • Provide an GCP Service Account name (or press Enter to use the default).
    • Provide an GCP Service Account display name (or press Enter to use the default).
    • Optionally, provide a GCP Service Account description (or press Enter to use the default).
    • Provide a JSON key filename (or press Enter to use the default).
    • Provide a GCP Role ID (or press Enter to use the default).
    • Optionally, provide a GCP Role description (or press Enter to use the default).
    • The configuration is complete and the key will be saved in the current directory.

    Additional GCP-related InsightCloudSec Features

    At this point in the process, it would be easiest to update the newly-created harvesting role with permissions for any additional GCP-related InsightCloudSec features.

  7. Click More (vertical ellipsis), then click Download.

  8. Click the folder icon (Toggle File Browser) to open the file browser for the current directory. Expand the current directory in the browser.

  9. Select the JSON key and click Download.

  10. Open the downloaded JSON key file inside a browser tab/window or text editor.

In the InsightCloudSec Cloud Onboarding interface:

  1. Copy/paste the entire JSON key file into the API Credentials field.
  2. Copy/paste the project_id value from the JSON key file into the Project ID field.

Automated onboarding instructions complete!

After completing the preceding steps, you have completed the automated onboarding instructions for GCP. Jump to the Connect the Account in InsightCloudSec instructions.

Connect the Account in InsightCloudSec

The GCP onboarding process is nearly complete; all that remains is to setup an account nickname & optional email delegation in InsightCloudSec and verify the account connection.

In the InsightCloudSec Cloud Onboarding interface:

  1. Provide the Nickname for the Account. This is a unique value that will be used to search Accounts across the system based on an identifiable label.
  2. If you performed the Email Delegation/Directory Support section above, provide the email address.
  3. Click Connect Account.

Success! You onboarded an Account

Congratulations on successfully onboarding an Organization!

  • InsightCloudSec will automatically detect if there are any missing permissions that could cause impaired visibility into your account.
  • If you choose to turn on Account Discovery, Rapid7 can onboard and collect information on related Organizations and accounts via the onboarded organization. Click Enable Auto Discovery at the bottom of the window to start this process.
  • For information about modifying an existing onboarded account, review the Cloud Account Setup & Management page.

Organization Post-Onboarding Information

If you followed the instructions above and onboarded a GCP Organization, you should have at least your Organization account with full visibility in InsightCloudSec. Review the following sections for more information on augmenting your Organization onboarding experience or managing the Organization within InsightCloudSec.

Enabling Account Discovery

After an Organization is onboarded to InsightCloudSec, we automatically detect the Organization and prompt you to enable Account Discovery. If you clicked the "Enable Auto Discovery" button within the onboarding wizard, you'll be taken to the Edit Organization Config window for the new Organization.

  1. From the Edit Organization Config window, select Auto-Sync Projects.
  2. Click UPDATE.

Once enabled, Accounts are discovered via the API dynamically and configured with defaults you provide.

Modifying a GCP Organization in InsightCloudSec

After onboarding a GCP Organization, you can edit configuration information at any time.

  1. From InsightCloudSec, go to Cloud > Cloud Accounts > Organizations.
  2. Next to the desired Organization, click the options button (hamburger icon), then click Edit Organization.
  3. Adjust the nickname or credentials values as necessary.
  4. Adjust the scope/badging options as necessary:
    • Projects to Skip: Enter details for projects (ID’s or Names) to be skipped (e.g., you have a group of development accounts you are not interested in tracking)
    • Auto-Sync Projects: Enable to add all projects associated with the organization. If not enabled, each account must be added manually.
    • Auto-remove deleted accounts: Enable to automatically remove deleted GCP accounts from InsightCloudSec. As soon as this checkbox is enabled, a background process will begin running and remove the accounts automatically as they are found
    • Auto-Badge Projects: Select this box to allow InsightCloudSec to automatically badge your incoming projects
    • Enable API Auto-Enablement: Select this box to automatically enable required APIs for each project. Review the Cloud Account Detail Page for additional details on this feature.
    • Limit import scope: Select this box and provide Parent Folder ID(s) to only include the given folder(s) and anything underneath it
  5. Click UPDATE.

Import Scope Changes

  1. To change the import scope to a different folder, or to remove the scope entirely, go to Clouds > Organizations.
  2. Select the pencil next to the name of the Organization you want to modify.
  3. Input the JSON credentials again in order to make this change.