> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Platform

*This integration surfaces permission insights and user access visibility across your GCP organization, and it can provision access: assign and unassign IAM role bindings, and suspend or reactivate the underlying Google account. It requires a Google Cloud Organization (project-only setups are not supported).*

## After this article

You'll be able to connect Google Cloud Platform to Lumos so that Lumos can securely audit which users, groups, and service accounts have access to which projects across your GCP organization. Lumos can also assign and unassign IAM role bindings and suspend or reactivate users.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Projects | App | Yes | No | Each GCP project appears as an app in Lumos (filter the All Apps page Source column by "Google Cloud") |
| Users | Account | Yes | Yes | Principals with project access (users, Google Groups, and service accounts), shown with their account type. Lumos can suspend and reactivate Google user accounts via the Admin SDK. Create and delete are not supported |
| Roles | Permission | Yes | Yes | IAM role bindings granted to each principal. Lumos can assign and unassign role bindings on the resources it syncs |

**Provisioning behavior:**

* **Assign a role:** Lumos reads the resource's IAM policy, adds the member to the role binding, and writes the policy back. Assigning a role the member already holds is rejected as already assigned.
* **Unassign a role:** Lumos removes the member from the role binding in the resource's IAM policy. Deleted users are matched by principal so stale bindings can still be cleaned up.
* **Suspend and reactivate:** these set the `suspended` flag on the Google account through the Admin SDK Directory API. This suspends the whole Google account, not just GCP access, so use it deliberately.

Lumos displays which users have access to which **projects** within your GCP organization. This does **not** imply access to the entire organization, only to specific resources where they have permission.

Lumos may show more role bindings than the GCP IAM console UI, which hides some roles (for example, certain billing roles). Lumos pulls in all available role bindings, and you can scope roles out of an Access Review if they are not relevant.

## Required plan and roles

There's no required Google Cloud plan to connect this integration.

To complete setup you need:

* **Google Workspace Super Admin** (or a user with access to the [domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation) page) to delegate API access to Lumos.
* **Organization-level administrator access in Google Cloud** to create a custom role and bind it at the organization level. Assigning the custom role to a service account requires the **Organization Role Administrator** role at the org level.
* An **Admin User Email** that Lumos impersonates for organization-level endpoints. This user must hold the **Cloud Asset Viewer** and **Organization Administrator** roles at the Org level. For auditability, Lumos recommends creating a dedicated service account email specifically for Lumos use.

Permission scoping: the custom role in the steps below combines read permissions (list/get) with the `setIamPolicy` permissions that role-binding provisioning needs. The Admin SDK `admin.directory.user` scope lets Lumos suspend and reactivate users. A read-only connection is possible

## Instructions

### Step 1: Delegate access to Lumos in Google Workspace

1. In the Google Admin console, go to **Security → Access and data control → API controls → Manage Domain Wide Delegation** (direct link: [admin.google.com/ac/owl/domainwidedelegation](https://admin.google.com/ac/owl/domainwidedelegation)).
2. Click **Add new**.
3. Enter the following **Client ID**:

```plaintext theme={null}
103971392043253917010
```

4. Paste the following **OAuth Scopes** and click **Authorize**:

```plaintext theme={null}
https://www.googleapis.com/auth/cloud-platform,
https://www.googleapis.com/auth/admin.directory.domain.readonly,
https://www.googleapis.com/auth/admin.directory.user,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly
```

The `admin.directory.user` scope is what lets Lumos suspend and reactivate users. The other Admin SDK scopes are read-only.

### Step 2: Create and assign a custom role in Google Cloud Console

1. In the Google Cloud Console, go to **IAM & Admin → Roles**. Make sure your **Organization** (not an individual project) is selected in the resource picker in the top left.
2. Create a new **custom role** with the following permissions:

```plaintext theme={null}
cloudasset.assets.listAccessPolicy
cloudasset.assets.listIamPolicy
cloudasset.assets.listOrgPolicy
cloudasset.assets.listResource
domains.locations.list
iam.serviceAccounts.list
managedidentities.domains.list
recommender.iamPolicyInsights.get
recommender.iamPolicyInsights.list
resourcemanager.folders.get
resourcemanager.folders.getIamPolicy
resourcemanager.folders.list
resourcemanager.folders.setIamPolicy
resourcemanager.organizations.get
resourcemanager.organizations.getIamPolicy
resourcemanager.organizations.setIamPolicy
resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.list
resourcemanager.projects.setIamPolicy
```

The three `setIamPolicy` permissions are what let Lumos assign and unassign IAM role bindings. Leave them out for a read-only connection.

3. Set the role's **launch stage** to at least **Beta** or **General Availability**.
4. Go to **IAM & Admin → IAM** (with the Organization still selected), click **Grant Access**, and assign the custom role to the Lumos service account:

```plaintext theme={null}
googlecloudintegration@lumos-gcloud-integration-prod.iam.gserviceaccount.com
```

Binding the role at the organization level grants the permissions across the organization and all of its folders and projects.

### Step 3: Find your Organization ID

1. In the Google Cloud Console, click the **resource drop-down menu** in the top left corner (or go to **IAM & Admin → Settings**).
2. Copy your **Organization ID**, a purely numeric string like `123456789`.

Do not use your Google Workspace **Customer ID** (which starts with a `C`, for example `C0xxxxxxx`). It is a different identifier and the connection will fail.

### Step 4: Connect in Lumos

1. Find the **Google Cloud Platform** card in your Lumos integrations and click it.
2. Enter your **Organization ID** from Step 3.
3. Enter the **Admin User Email**, the user Lumos will impersonate to access endpoints that require Organization-level admin permissions. This user must have the **Cloud Asset Viewer** and **Organization Administrator** roles assigned at the Org level.
4. Complete the connection flow.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

### The custom role doesn't appear when assigning it to the service account

* Ensure your account has the **Organization Role Administrator** role at the org level.
* Confirm the custom role's **launch stage** is set to at least **Beta** or **General Availability**.
* Confirm the role was created with the **Organization** selected, not an individual project. A role created or bound at the project level will not grant Lumos visibility across the organization.

### Connection fails with `HttpError 400: Fail to resolve resource organizations/<id>`

The value entered in the Organization ID field is likely your Google Workspace **Customer ID** (starts with `C`), not your numeric GCP **Organization ID**. Enter the numeric Organization ID found in **IAM & Admin → Settings** (or in the Cloud Console URL).

### Organization-level endpoints return permission errors

Verify that the **Admin User Email** entered in Lumos holds the **Organization Administrator** and **Cloud Asset Viewer** roles at the org level, and that the domain-wide delegation entry (Step 1) was authorized with the exact Client ID and scope shown above.

## Need Help?

If you encounter any issues or have questions, reach out to [support@lumos.com](mailto:support@lumos.com) or contact your Lumos representative.