Authentication Methods

In this guide, you will:

Importing a GCP Organization into Guardrails involves these key steps:

Prerequisites

Supported Authentication

Guardrails provides support for two credential methods to import a GCP Organization. The supported methods are:

[!NOTE] We 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.

In case you want to use JSON Credential File, refer the steps mentioned in Connect a GCP Project to Guardrails in Getting Stated with GCP guide.

Required Permissions on Service Account

The permissions you grant to the service account depend on your organization’s security and compliance requirements. The table below outlines the minimum recommendations for organization-wide governance:

Permission LevelDescriptionRecommended Role
Full RemediationProvides 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-OnlyAllows 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 ViewerGrants read-only access to view metadata and browse resources within a specific GCP folder, without modifying them.roles/resourcemanager.folderViewer.
Organization ViewerAllows 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 ViewerProvides read-only access to view project-level metadata and resources, ensuring visibility without allowing any modifications.roles/viewer.

[!IMPORTANT] For importing the organization, you need only Organization Viewer, Project Viewer, and Folder Viewer roles, which will allow discovery of all resources under the organization.

If Guardrails attempts an action (e.g., enabling APIs, modifying resources) without sufficient permissions, you will encounter access denied errors. To resolve this, ensure the required permissions are granted or update the Guardrails policies to align with your organization's requirements.

Using Service Account Impersonation

Service Account Impersonation grants short-lived credentials to Guardrails, allowing it to act as a specified service account without requiring a JSON key file. This approach reduces the security risk of storing or distributing long-lived credentials.

Prerequisites for Configuration

[!NOTE] Below CLI command is generated in Guardrails console when you choose Access Mode as Service Account Impersonation, provide Organization ID and Client email.

Refer to the example below for guidance:

Generate Service Account Impersonation

Example: Assign Service Account Token Creator
# 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.serviceAccountTokenCreator"

Using JSON Credential File

Example: Using CLI Command
# This command will create a file named "key.json" in your current directory
gcloud iam service-accounts keys create key.json [email protected]

Using Private Key

The private_key in the key.json you generated is the required secret to import the GCP organization into a Guardrails workspace. Guardrails requires this key in multi-line format, not as a single, long string.

For example, after generating your JSON key file (key.json), you can extract the private key portion by running:

cat key.json | jq -r .private_key
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQClvph2e9f6Dl/H
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
<truncated>
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Pwd0PmmSB1U3h3+Ued/eDhw=
-----END PRIVATE KEY-----

[!NOTE] You may use one of the option either Using Using JSON Credential File or Using Private Key or Using Service Account Impersonation

Enterprise Configuration

[!NOTE] This section applies only to Enterprise hosting Guardrails.

The GCP organization import feature requires TED v1.46.x, which introduces the gcp_service_account_private_key_ssm_parameter_name SSM parameter. This parameter must be mapped to a manually created SSM parameter containing the credential JSON value.

Prerequisites

Create SSM Parameter

Log in to the Guardrails primary AWS account and navigate to the AWS Systems Manager service.

Create Parameter

Create a Secure String with the Tier set to Standard.

Paste JSON Credential

See here how to download JSON credential file.

Paste the JSON credential content into the Value field and select Create parameter.

Paste JSON Value

For more details, refer to the AWS guide on Creating a Parameter Store parameter using the console.

Update TED Stack

Follow the steps in Update Turbot Guardrails Enterprise Database (TED).

Navigate to the GCP Service Account Private Key SSM Parameter section of the TED stack (near the end) and update the manually created SSM parameter name as shown below. Select Update to proceed.

Update TED Stack Parameter