Google Cloud Platform

Trustle reads IAM role bindings, roles, the resource hierarchy, audit logs, and AI agents from Google Cloud. Trustle can grant and revoke IAM roles on your organization, folders, and projects.

Prerequisites

• A Google Cloud organization.

• These roles at the organization level:

  • Organization Role Administrator, to create the custom role.
  • Organization Administrator, to grant the role to the service account.

  Project IAM Admin is not enough. It cannot create a role at the organization level.

• These roles in the project that holds the service account: Service Account Admin, Service Account Key Admin, and Service Usage Admin.

• An identity provider connected in Trustle, for example Google Workspace or Okta. Trustle hides Cloud Providers until one is connected.

• To change Google group members, a Google Workspace connection in Trustle. Trustle makes group changes through that connection.

Configure Google Cloud Platform

Step 1: Enable the APIs

Use a dedicated project for the Trustle service account. Google Cloud counts the API calls against this project.

1. In the Google Cloud console, select the project.

2. Go to APIs & Services → Library.

3. Enable each API:

   API	Required	What Trustle does with it
   Cloud Resource Manager API	Yes	Reads the organization, folders, projects, and their IAM policies.
   Identity and Access Management (IAM) API	Yes	Reads role definitions.
   Cloud Logging API	Yes	Reads audit logs to find which permissions people use. Without it, Trustle has no usage data.
   Vertex AI API	Optional	Finds Agent Engine agents. Without it, Trustle imports no Agent Engine agents.
   Agent Registry API	Optional	Finds agents in the Agent Registry. Without it, Trustle imports no registry agents.

Step 2: Create a custom role

1. Search for IAM & Admin in the console search bar. Select the result.

   

2. In the resource picker, select your organization. Do not select a project or a folder.

   

3. Go to IAM & Admin → Roles. Click Create role.

4. Enter a Title, for example Trustle Access Manager.

5. Set Role launch stage to General Availability.

6. Click Add permissions. Add each permission from Step 3.

7. Click Create.

Step 3: Grant permissions

Add these permissions to the custom role:

Permission	Required	What Trustle does with it
resourcemanager.organizations.get	Yes	Reads the organization.
resourcemanager.organizations.getIamPolicy	Yes	Imports role bindings set on the organization.
resourcemanager.organizations.setIamPolicy	Yes	Grants and revokes roles on the organization.
resourcemanager.folders.get	Yes	Reads the folders above each project.
resourcemanager.folders.list	Optional	Lists folders to build the resource hierarchy. Without it, Trustle shows projects without their folders.
resourcemanager.folders.getIamPolicy	Yes	Imports role bindings set on folders.
resourcemanager.folders.setIamPolicy	Yes	Grants and revokes roles on folders.
resourcemanager.projects.get	Yes	Finds projects. Test Connection uses it.
resourcemanager.projects.list	Yes	Lists projects.
resourcemanager.projects.getIamPolicy	Yes	Imports role bindings set on projects. Test Connection uses it.
resourcemanager.projects.setIamPolicy	Yes	Grants and revokes roles on projects.
iam.roles.get	Yes	Reads the permissions in each role.
iam.roles.list	Yes	Lists predefined and custom roles.
logging.logEntries.list	Yes	Reads Admin Activity audit logs. Without it, Trustle cannot tell used permissions from unused ones.
logging.privateLogEntries.list	Optional	Reads Data Access audit logs. Without it, Trustle misses data reads, such as a read from a storage bucket.
iam.serviceAccounts.get	Optional	Finds the numeric ID of each agent’s service account. Without it, Trustle shows each agent by email only.
aiplatform.reasoningEngines.list	Optional	Imports Agent Engine agents. Needs the Vertex AI API.
agentregistry.agents.list	Optional	Imports agents from the Agent Registry. Needs the Agent Registry API.

If the console does not let you add an optional permission to a custom role, grant a predefined role at the organization level instead: Vertex AI Viewer (roles/aiplatform.viewer) or Agent Registry Viewer (roles/agentregistry.viewer).

Caution

This role is not read-only. The setIamPolicy permissions let Trustle change IAM policy anywhere in your organization.

Step 4: Create the service account

1. Select the project from Step 1.
2. Go to IAM & Admin → Service accounts. Click Create service account.
3. Enter a Service account name, for example trustle. Click Create and continue.
4. Skip Grant this service account access to project. You grant the role in Step 5.
5. Click Done.
6. Copy the service account email, for example service-account-name@project-id.iam.gserviceaccount.com.

Step 5: Grant the role at the organization level

1. In the resource picker, select your organization.
2. Go to IAM & Admin → IAM. Click Grant access.
3. In New principals, paste the service account email from Step 4.
4. In Select a role, select the custom role from Step 2.
5. Click Save.

Caution

Grant the role on the organization, not on a project. A project-level grant covers only that project, and Test Connection still passes.

Step 6: Create a JSON key

1. Go to IAM & Admin → Service accounts. Click the service account email.
2. Select the Keys tab. Click Add key → Create new key.
3. Select JSON. Click Create. The key file downloads.

Caution

Google Cloud lets you download the key once. If you lose it, create a new key.

Step 7: Collect the values for Trustle

Trustle field	Where to find it in Google Cloud	Example
Service Account Key File	The JSON key file from Step 6	{"type": "service_account", "project_id": "<project-id>", …}

Connect in Trustle

1. In Trustle, go to Connections.

2. Under Cloud Providers, find Google Cloud and click Connect.

3. Enter a Connection Name, for example Google Cloud production. Description is optional.

4. In Service Account Key File, click Paste JSON and paste the whole file. Or click Upload File and select the file from Step 6.

   

5. Click Test Connection.

   

6. After the test passes, click Save Connection.

Note

Test Connection lists one project and reads its IAM policy. It does not check the organization-level grant, the audit logs, or the optional permissions. Do the steps in Verify after the first sync.

Verify

1. On the Connections page, open the Google Cloud connection.
2. Wait for the first sync to finish.
3. Check that the project count matches the number of projects in your organization.
4. Check that Trustle shows role bindings set on the organization, not only on projects.

If something is missing, see Troubleshooting.

Security notes

Note

• Use a dedicated service account in a dedicated project for Trustle only.
• Protect the key like an administrator credential. The role can grant any role in your organization, to anyone, including the service account itself.
• Store the key file in a secret manager. Never commit it to a repository. Delete the downloaded copy after you connect.
• Rotate the key on your normal schedule. Then paste the new key into the Trustle connection.

Troubleshooting

Test Connection fails

Read the error message:

• “Invalid JSON in service_account_key”: paste the whole file, from { to }.
• “Invalid service account key format”: the file is not a service account key. Create a JSON key in Step 6.
• “No projects accessible with provided credentials”: the service account has no role on any project. Do Step 5. Check that you pasted the service account email, not your own.
• SERVICE_DISABLED or “has not been used in project”: enable the API that the message names. Do Step 1 in the project that holds the service account.

Test Connection passes, but Trustle shows only one project

The role is granted on a project, not on the organization. Do Step 5. Then run the sync again.

Google Cloud does not let you create a key

An organization policy blocks service account keys, for example iam.disableServiceAccountKeyCreation. Ask your organization policy administrator to allow keys for the Trustle project only.

Usage data or last-used dates are missing

• Enable the Cloud Logging API in Step 1.
• Add logging.logEntries.list to the role. For data reads, also add logging.privateLogEntries.list.
• Google Cloud records Data Access audit logs only when you turn them on. Go to IAM & Admin → Audit Logs and turn them on for the services you want to track.

Trustle shows the data after the next sync.

AI agents are missing

• Agent Engine agents: enable the Vertex AI API and add aiplatform.reasoningEngines.list.
• Agent Registry agents: enable the Agent Registry API and add agentregistry.agents.list.

Trustle shows the agents after the next sync.

Trustle cannot grant or revoke a role

The custom role is missing a setIamPolicy permission for that level: organization, folder, or project. Add it in Step 3.

None of these fixes work

Email support@trustle.com. Include the error message, the connection name, and the Google Cloud organization ID and the service account email. Never send a secret, key, or token.