Skip to main content
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

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 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).
  2. Click Add new.
  3. Enter the following Client ID:
  1. Paste the following OAuth Scopes and click Authorize:
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:
The three setIamPolicy permissions are what let Lumos assign and unassign IAM role bindings. Leave them out for a read-only connection.
  1. Set the role’s launch stage to at least Beta or General Availability.
  2. Go to IAM & Admin → IAM (with the Organization still selected), click Grant Access, and assign the custom role to the Lumos service account:
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

​
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 or contact your Lumos representative.