- Prerequisites
- Step 1: Enable Required APIs
- Step 2: Create Service Account
- Step 3: Grant IAM Roles
- Step 4: Get Organization ID
- Step 5: Import Organization into Guardrails
- Step 6: Setup Service Account Impersonation
- Step 7: Create External ID Label
- Step 8: Exclude Projects
- Step 9: Start Import
- Review
- Next Steps
- Troubleshooting
Importing GCP Organization to SaaS Workspace
In this guide, you will:
- Learn how to import an entire Google Cloud Platform (GCP) Organization into Turbot Guardrails in SaaS environment. This process allows Guardrails to discover and manage resources across all projects and folders under a single GCP Organization.
- Monitor and troubleshoot the process.
Importing a GCP Organization into Guardrails involves these key steps:
- Configuring a GCP Service Account with appropriate permissions at the organization level.
- Importing the organization via the Guardrails console.
Prerequisites
- Access to the Guardrails console with Turbot/Owner or Turbot/Admin permissions at the Turbot resource level.
- Minimum Turbot Enterprise (TE) version
v5.48.0
or later. - GCP mod
5.30+
installed in your Guardrails workspace. - GCP Console: Familiarity with the GCP Console, including admin privileges.
- The
gcloud
CLI configured on your local environment.
Supported Authentication
Guardrails supports two credential methods to import a GCP Organization:
- Service Account Impersonation: Grants temporary credentials using GCP Service account impersonation.
- JSON Credential File: Uses a downloaded JSON key file or requires copying and pasting the
private_key
section of the JSON file.
NoteWe recommend Service Account Impersonation, as it eliminates the need to download or manage a JSON key, reducing security risks. This guide demonstrates Service Account Impersonation.
If you prefer to use the JSON Credential File, refer to the steps mentioned in Connect a GCP Project in the
Getting Started with GCP
guide.
Step 1: Enable Required APIs
Guardrails requires access to the Cloud Resource Manager
and Service Management
APIs to discover and manage organization-wide resources. Refer the GCP documentation to enable the APIs using Console
and gcloud
.
Refer to the image below as example using as example in GCP Console
.

Step 2: Create Service Account
To import an organization into Guardrails, create the service account in any single project under your organization. Prepare a GCP Project for Import to Guardrails. The step Locate IAM & Admin > Service Accounts
elaborates the steps to create service account.
Step 3: Grant IAM Roles
TipIn GCP, service accounts are always associated with a specific project, even if their permissions are applied at the project, folder, or organization level.
Required Permissions
The table below outlines the minimum permissions required for organization-wide governance on service account:
Permission Level | Description | Recommended Role |
---|---|---|
Full Remediation | Provides Guardrails with the broadest level of control across your GCP Organization, allowing full governance and policy enforcement. | Organization Administrator (roles/resourcemanager.organizationAdmin ) or equivalent custom roles. |
Read-Only | Allows Guardrails to perform discovery and track resources but does not enable any remediation actions. | Viewer roles at the organization level (e.g., roles/viewer ). |
Folder Viewer | Grants read-only access to view metadata and browse resources within a specific GCP folder, without modifying them. | roles/resourcemanager.folderViewer . |
Organization Viewer | Allows read-only access to view metadata and monitor all resources at the organization level, enabling oversight without configuration changes. | Organization Viewer roles/resourcemanager.organizationViewer . |
Project Viewer | Provides read-only access to view project-level metadata and resources, ensuring visibility without allowing any modifications. | roles/viewer . |
Follow these steps to assign the required roles at the Organization
scope to the service account:
- Navigate to IAM & Admin > IAM in the Google Cloud console.
- Select your Organization from the resource selector.
- Select Grant Access.
- Enter the Principal as
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
, that you created part of previous step. - Assign the required roles at the organization (or folder) scope as described in Required Permissions on Service Account.
Refer to the image below:

NoteTo import an organization, you need only
Organization Viewer
,Project Viewer
, andFolder Viewer
roles to allow the discovery of all resources under the organization.
Alternatively you can grant roles using gcloud
command line interface as below.
# Create the service account in a specific projectgcloud iam service-accounts create SERVICE_ACCOUNT_NAME --project=PROJECT_ID --description="Service account for Guardrails"# Assign roles at the organization levelgcloud organizations add-iam-policy-binding ORGANIZATION_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="ROLE_NAME"
Step 4: Get Organization ID
In the GCP console, select your organization. Navigate to All to view the list of projects, folders, and the organization itself. Locate and copy the ID
of the organization.

Step 5: Import Organization into Guardrails
Log into the Guardrails console with provided local credentials or by using any SAML based login and select the CONNECT card.

Select GCP and then choose the GCP Organization option.

Choose the folder where the GCP organization will be imported.
Choose one of the
Access modes
from the provided list. In this guide, Service Account impersonation is demonstrated.Provide the
Organization ID
for your GCP organization and theClient email
. Guardrails will use this email ID for impersonation.

Proceed for setting up Service Account Impersonation.
Step 6: Setup Service Account Impersonation
The impersonating user or service account (i.e.
the identity that runs Guardrails
) must have the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator
) on the target service account.The target service account just created for organization importing purpose i.e. the one being impersonated must have the required organization-level permissions as as described in What Permissions to Grant to discover or manage resources across your GCP Organization.
In the same page, select Copy gcloud command.

Now execute copied command using gcloud CLI in your local environment.
# Replace SERVICE_ACCOUNT_NAME and PROJECT_ID with your service account's name/project# Replace IMPERSONATOR_EMAIL with the user or service account that will impersonate it
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:IMPERSONATOR_EMAIL" --role="roles/iam.serv
Validate the output.
ā gcloud iam service-accounts add-iam-policy-binding mrk-sa-test@mrk-sandbox.iam.gserviceaccount.com --member=serviceAccount:integration-gcp@turbot-guardrails-dev.iam.gserviceaccount.com --role=roles/iam.serviceAccountTokenCreator --format=jsonUpdated IAM policy for serviceAccount [mrk-sa-test@mrk-sandbox.iam.gserviceaccount.com].{ "bindings": [ { "members": [ "serviceAccount:integration-gcp@turbot-guardrails-dev.iam.gserviceaccount.com" ], "role": "roles/iam.serviceAccountTokenCreator" } ], "etag": "BwYsqn0-odQ=", "version": 1}
Step 7: Create External ID Label
The External ID label
acts as a key service account identifier within the project that your service account belongs to. Create a label with the key guardrails_external_id
and value: turbot_162167737252865_f1da2779-92c8-46b1-83dd-95d629023211
. This value is randomly populated by Guardrails.
NoteThe
Label
key and the highlighted portion of the value (i.e.,turbot_162167737252865
in the formatturbot_{current workspace id}
) cannot be modified. However, the third part of the text can be customized by clicking theCustomize
icon.

Log in to the GCP console and navigate to the project where the configured service account resides. Select Labels from the side navigation panel, add guardrails_external_id
as the label key, and turbot_162167737252865_f1da2779-92c8-46b1-83dd-95d629023211
as the value. Click +Add label to save the label.

WarningThe
External ID
label created in the GCP project for the organization import must be retained within the respective GCP project to prevent errors in Guardrails.
Step 8: Exclude Projects
This step is required if you wish to exclude specific projects or folder under organization from being imported into Guardrails.
ImportantExisting projects already connected individually in Guardrails will automatically move under the organization hierarchy. If you do not wish to move them, list them in the YAML exclusion list.
Click the Edit button to provide a list of project IDs or folder names under the organization to be excluded.

Click the Preview button to ensure no errors are displayed. Move to Step 14.
Step 9: Start Import
Click Connect to begin the import process.

Guardrails will create and execute discovery controls for your GCP Organization, scanning each folder, project and resources under it.

Review
- Confirm that the organization CMDB and discovery controls are in the
OK
state.
Navigate to the Resources tab, search for the organization name, then select Controls tab besides to check the controls are on OK
state.

- Verify that the projects and folders are successfully imported into Guardrails and match the GCP console.
Navigate to the Resources tab, search for the organization name to check the list of resources the import process is discovered matching to the structure in GCP console.

Next Steps
- Learn how to Enable GCP Services in Guardrail.
- Learn how to Configure Real-Time Event Handlers.
Troubleshooting
Issue | Description | Guide |
---|---|---|
Access Denied: Missing Token Creator Role | If using Service Account Impersonation, the impersonating user or workload must have roles/iam.serviceAccountTokenCreator on the service account. | Refer to the Service Account Token Creator Role Documentation. |
Access Denied: Malformed Secret Key | Guardrails requires the multi-line format of the Secret Key. Ensure it includes the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- headers. | |
Access Denied: Improper Client Email | Guardrails cannot use a non-service account email to access the project. Ensure the Client Email is in the form of {identifier}@{your-project-id}.iam.gserviceaccount.com . | Check GCP Service Account Documentation. |
Access Denied: Missing or Insufficient Permissions | If Guardrails is asked to discover, track, or remediate resources without the necessary permissions, access denied errors will appear in the Discovery and CMDB controls in the Guardrails console. Resolve by granting the required permissions. | Check Required Permission. |
Lots of Controls in Error State | If there were issues with credentials during project import, many Discovery controls may show an error state. You can either delete and reimport the project or rerun the controls in error using scripts provided in the Guardrails Samples Repo. | Use the Python, Node, or Shell scripts. |
GCP Service API Enabled Policies Aren't Set | If the GCP > {Service} > API Enabled policy is not set to Enforce: Enabled , Discovery and CMDB controls will be skipped . Enable the applicable service APIs manually if Guardrails lacks permissions to do so. | Enable GCP APIs Documentation. |
Bad Request: Error processing runnable input organizationcredentials Cloud Resource Manager API has not been used in project 265919995000 before or it is disabled. | If Guardrails import process errors out in CMDB and discovery control run. | Enable it by visiting https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=265919995000 then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry. |
Further Assistance | If you continue to encounter issues, please open a ticket with us and attach the relevant information to assist you more efficiently. | Open Support Ticket. |