GCP Organisation Level Onboarding Guide

Last updated: April 6, 2026

This guide explains how to onboard a GCP Organisation into the Matters platform using the Organisation access scope.

As part of the setup, you will need to download and run a Terraform template provided by Matters.

The provided Terraform template (gcp_org_onboarding.tf and gcp_org_onboarding.tfvars) will:

Create a custom IAM role at the Organisation level

Assign the required permissions to that role

Bind the role to an existing Service Account

Optionally restrict access to a specific Folder

Prerequisites

Before starting, ensure the following:

You have Matters Super Admin access.

You have access to the target GCP Organisation with permissions to:
- Create organisation-level custom IAM roles
- Create IAM bindings
- List folders and projects

The required Google Cloud APIs are already enabled (IAM, Cloud Resource Manager, BigQuery, Storage, etc.).

1. Enable Following Required Google APIs

		APICapability ProvidedAPI Links
serviceusage	Allows API enablement	https://console.cloud.google.com/apis/library/serviceusage.googleapis.com?
iam	IAM management (roles & SA)	https://console.cloud.google.com/apis/library/iam.googleapis.com?
cloudresourcemanager	Access org/project structures	https://console.cloud.google.com/apis/library/cloudresourcemanager.googleapis.com?
bigquery	Read BigQuery metadata/data	https://console.cloud.google.com/apis/library/bigqueryunified.googleapis.com?
cloudkms	Access encrypted data exports	https://console.cloud.google.com/apis/library/cloudkms.googleapis.com?
sqladmin	Work with Cloud SQL exports	https://console.cloud.google.com/apis/library/sqladmin.googleapis.com?
storage	Read objects from GCS buckets	https://console.cloud.google.com/apis/library/storagetransfer.googleapis.com?
dataplex	Inventory & metadata	https://console.cloud.google.com/apis/library/dataplex.googleapis.com?
dataform	Dataform queries/inventory	https://console.cloud.google.com/apis/library/dataform.googleapis.com?

Step 1 Configure Integration in Matters Console

Navigate to:
Integrations → Cloud → Google Cloud
(URL: https://app.matters.ai/data-security/integrations?type=cloud.
If you use a dedicated tenant, replace app with your tenant name.)

Click Connect on the GCP integration card.

Provide:
- Integration Name
- Access Level Scope → Organisation

Enter:
- Organization ID
- Folder ID (Optional)

	FieldPurpose
Organization ID	Identifies the GCP Organisation where integration will take place
Folder ID	Restricts role creation to a specific folder (otherwise applies to the entire organisation)

Click Continue Setup.

Step 2: Download and Extract the Terraform Script

Click on the Google Cloud Shell hyperlink to log in to the GCP Admin account.

In the next step on the Matters Dashboard, click Download Script.

A .zip file will be downloaded.

Extract the zip — it contains two Terraform files:
- gcp_org_onboarding.tf → Terraform configuration to create:
  - Custom IAM Role (Organisation level)
  - Required IAM permissions inside the role
  - IAM role binding (Organisation or Folder level)
- gcp_org_onboarding.tfvars → Variable file where you provide:
  - org_id
  - folder_id (optional)
  - matters_service_account_email (existing Service Account)

These files automate IAM role creation and role binding inside Google Cloud.

⚠ Note: The Terraform template does NOT create a Service Account, generate a key, or enable APIs.

Step 3: Open Google Cloud Shell

In the GCP Management Console, click SSH (top-right corner) to activate Cloud Shell.

Authorize access when prompted. Cloud Shell will now be ready for Terraform execution.

Step 4: Upload the Terraform Folder to Cloud Shell

In Cloud Shell, click the Upload option.

Select the extracted folder from your system and click on upload.

Once upload is complete, navigate into the folder:
```
cd <folder_name>
```

Confirm files exist:

ls

You should see gcp_org_onboarding.tf and gcp_org_onboarding.tfvars.

Step 5: Run Terraform to Create Required Resources

In Cloud Shell, navigate to the folder where the files were uploaded and execute the following command (you may also copy this command from the Matters Dashboard):

terraform init && terraform apply -auto-approve -var-file="gcp_org_onboarding.tfvars"

After Terraform completes successfully:
Click Validate in the Matters Console. Matters will verify access and permissions.

Step 6: Select Projects to Onboard

After validation is successful:

You will see a list of all accessible GCP projects.

Select the projects you want to add into Matters.

Click Save to complete onboarding.

Step 7: Integration Complete

You will see “Integration Successful” message once Integration is complete

Once the accounts are successfully integrated, all supported data stores across the selected GCP accounts will be automatically discovered in the Matters dashboard.

After discovery, you can click on the data store selectively and can run scans on specific data stores to identify and classify sensitive entities as per your requirements. This allows you to focus on relevant resources and efficiently manage sensitive data across your organization.

Understanding What the Terraform Script Configures

1. Custom IAM Role Creation (Organisation Level)

The Terraform script creates a custom IAM role at the Organisation level.

This role includes permissions required for:

BigQuery discovery and metadata access

Cloud Storage visibility

Cloud SQL metadata access

Cloud KMS visibility

Dataform and Dataplex visibility

Organisation, folder, and project listing

IAM policy visibility

The following permissions are added to the custom role:

IAM Permissions Included in the Custom Role

Service Area	IAM Permission	Purpose / Capability
BigQuery	bigquery.readsessions.update	Manage read sessions
	bigquery.readsessions.create	Create read sessions
	bigquery.readsessions.getData	Retrieve read session data
	bigquery.tables.get	Read table metadata
	bigquery.tables.list	List tables
	bigquery.tables.getData	Read table data
	bigquery.tables.getIamPolicy	Read table IAM policy
	bigquery.tables.export	Export BigQuery data
	bigquery.tables.replicateData	Replicate table data
	bigquery.tables.createSnapshot	Create table snapshots
	bigquery.datasets.get	Read dataset metadata
	bigquery.datasets.create	Create datasets
	bigquery.datasets.getIamPolicy	Read dataset IAM policies
	bigquery.jobs.list	List query jobs
	bigquery.jobs.create	Run jobs (queries, exports, etc.)
	bigquery.models.list	List ML models
	bigquery.models.getMetadata	Read ML model metadata
	bigquery.models.getData	Read ML model data
	bigquery.models.export	Export ML models
	bigquery.routines.list	List routines
	bigquery.routines.get	Read routines (UDFs)
	bigquery.savedqueries.list	List saved queries
	bigquery.savedqueries.get	Read saved query definitions
	bigquery.transfers.get	View Data Transfer configurations
	bigquery.config.get	Read project BigQuery configuration
	bigquery.reservations.get	View reservation configuration
	bigquery.reservations.list	List reservations
	bigquery.reservations.use	Use BigQuery slots
	bigquery.reservations.listFailoverDatasets	List failover datasets
	bigquery.reservationAssignments.list	List reservation assignments
	bigquery.reservationAssignments.search	Search reservation assignments
	bigquery.capacityCommitments.get	View capacity commitments
	bigquery.capacityCommitments.list	List capacity commitments
	bigquery.bireservations.get	View BI reservation settings
	bigquerymigration.translation.translate	Translate SQL to BigQuery
Dataform	dataform.locations.list	List Dataform locations
	dataform.locations.get	Read location information
	dataform.repositories.list	List Dataform repositories
	dataform.repositories.create	Create repositories
Dataplex	dataplex.projects.search	Discover projects in Dataplex
Cloud KMS	cloudkms.keyHandles.create	Create Key Handles for cryptographic APIs
	cloudkms.keyHandles.get	Read key handles
	cloudkms.keyHandles.list	List key handles
	cloudkms.operations.get	Inspect KMS operations
	cloudkms.projects.showEffectiveAutokeyConfig	View Autokey configuration
Cloud SQL	cloudsql.instances.get	View instance metadata
	cloudsql.instances.list	List SQL instances
	cloudsql.instances.connect	Allow connection using ephemeral certificate
	cloudsql.instances.export	Export Cloud SQL data
Cloud Storage	storage.objects.get	Read objects
	storage.objects.list	List objects in buckets
	storage.buckets.get	View bucket configuration
	storage.buckets.list	List buckets
	storage.buckets.getIamPolicy	View bucket IAM policy
Resource Manager	resourcemanager.folders.get	Read folder metadata
	resourcemanager.folders.list	List folders
	resourcemanager.projects.list	List projects in org/folder
	resourcemanager.projects.getIamPolicy	Read project IAM policy

2. Role Binding

After creating the custom IAM role, Terraform:

Binds the role to the existing Service Account specified in:
matters_service_account_email

Applies the binding at:
- Organisation level (default), or
- Folder level (if Folder ID is provided)