Skip to main content

​
After this article

You’ll be able to connect Google Workspace to Lumos to sync users, groups, and roles, discover apps, manage licenses, and run offboarding actions.

​
Capabilities

Custom capabilities. These are additional actions the Google Workspace connector can perform. They can optionally be enabled, reach out to Support to use them. Activity tracking is supported. Last activity is based on the lastLoginTime field from the Google Admin SDK Directory API users endpoint.

​
Required plan and roles

  • Google Workspace plan: there’s no required plan to connect this integration.
  • Google Workspace role: the connecting user needs access to the domain-wide delegation page, which is usually scoped to Super Admins.
  • Permission scoping options:
    • Default scopes (listed below) enable sync, app discovery, license management, and offboarding actions.
    • Read-only or custom scope sets are available. Reach out to Slack Support or support@lumos.com to enable them. Connecting with default scopes then later downgrading them to read-only versions still lets syncs complete, but provisioning actions won’t be supported.
    • Full Provisioning must be enabled by Support.
Access to scopes is granted through domain-wide delegation by a Google Workspace administrator. Lumos cannot and does not need to read your Google Drive, Google Docs, Google Sheets, or other sensitive information. If you want to enable provisioning or use a custom set of scopes, contact Support at support@lumos.com or through Slack and describe your use case.
To use a set of non-default scopes, reach out to Support with your use-case to configure it. Lumos supports variations such as JIT access for entitlements only, mail scanning enabled or disabled, and more.

​
Read-only access vs provisioning

Is read-only possible? Yes, but it isn’t self-serve. The default scopes above grant Lumos read and write access for offboarding, group management, and license actions. A read-only or custom scope set is possible. Contact Support before you connect to enable it. What read-only requires. Contact Lumos Support or support@lumos.com to enable a read-only or custom scope set, then follow the steps below using the reduced scope list Support provides in place of the default scopes. What full provisioning requires. The default scopes shown above (admin.directory.user, admin.directory.group, admin.directory.user.security, gmail.settings.basic, admin.datatransfer, gmail.metadata, apps.licensing), authorized through domain-wide delegation as described below. Provisioning Google Workspace Admin roles specifically also needs the admin.directory.rolemanagement scope.

​
Instructions

Phase 1: Start in Lumos and generate a Client ID
  1. Find the Google Workspace card in your Lumos integrations (reconnect or add new) and click it.
  2. Enter the email of a Google Workspace user with access to the domain-wide delegation page (usually a Super Admin).
  3. Click Generate Client ID in Lumos and copy the value.
Phase 2: Authorize the client in Google Log into Google Workspace as the same user you entered in Phase 1, then:
  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 to add a new API client.
  3. Paste the value from Phase 1 as the Client ID.
  4. Paste the following scopes into the OAuth Scopes field. You don’t need to split them onto separate lines.
If you connected with a custom set of scopes, Lumos prompts you to add only the subset of scopes that apply for your tenant.
  1. Click Authorize to authorize the Lumos API token.
Phase 3: Finish in Lumos
  1. In Lumos, click Connect Google Workspace.
Google can take several minutes to finish registering a new API client. If the connection fails right after authorizing, wait 5 to 10 minutes and try again.

​
API Endpoints Used

​
Troubleshooting

I need to connect another Google Workspace tenant with a different domain. Contact Lumos through Slack or at support@lumos.com, because this process currently needs help from the Lumos team. New email domains must be allowlisted in your Lumos tenant before you can add them (see the FAQ below). I cannot connect Google Workspace. Make sure you’re using a Super Admin in Google Workspace, that the admin email you enter in Lumos matches the email you’re logged in to when creating an API client in Google, and that the Client ID and scopes in Google match what’s in Lumos. Google sometimes takes several minutes to finish registering the API client, so wait 5 to 10 minutes after generating the client and try the connection again. Syncs fail with 403 “Not Authorized to access this resource/api”. A 403 on the Directory API almost always points to a domain-wide delegation misconfiguration rather than a Lumos issue. Verify that the configured admin email is a Super Admin and that all required OAuth scopes are authorized for the Lumos Client ID on the domain-wide delegation page. If you edited scopes on an existing API client and errors persist, remove the API client entry and re-add it with the full scope list. Google sometimes fails to apply scope edits in place. I need to change the Google Workspace user email for connecting. Add the new email in the Admin Email field, click Generate Client ID (this still uses the same existing Client ID but links the new email), then click Reconnect. A Google Group isn’t showing up in Lumos. If a group doesn’t appear (for example, in the access policy permissions picker), it may not have synced yet. Run Sync Google Workspace Groups, wait a few minutes, then Sync Google Workspace Users, and search by the group’s exact primary email address. Confirm the integration has the admin.directory.group scope. Dynamic groups are managed automatically by Google, and their membership can’t be modified through the API. The Client ID Lumos generates is the same no matter which admin email I enter. That’s expected. The value shown is the OAuth 2.0 client ID of the Google service account Lumos uses for domain-wide delegation, and it’s a fixed value for your Lumos tenant rather than something derived from the email you type. The admin email is stored separately and is the account Lumos impersonates when it calls Google’s Admin APIs. Paste the Client ID into the domain-wide delegation page in Google and authorize it for the scopes listed in Lumos. Can I connect Google Workspace with OAuth 2.0 instead of domain-wide delegation? Domain-wide delegation with the Lumos service-account Client ID is the only authentication method this connector supports. If a consented OAuth 2.0 flow is a requirement in your environment, contact Support at support@lumos.com or through Slack so your use case can be logged with the product team. Syncs fail with a missing scopes error. This means at least one scope your integration is configured to use was not granted to the Lumos Client ID in Google. Open the domain-wide delegation page, open the Lumos API client, and confirm every scope shown in the Lumos instructions card is present, including any added after your first setup. If your tenant uses a custom scope set, the scopes authorized in Google need to match the reduced list Support configured for you rather than the default list above. Roles like “Delegated Administrator” show in Lumos but I can’t find them in the Admin console. Lumos surfaces the roles the Google Admin SDK Directory API returns, which includes built-in roles that aren’t prominently displayed in the Admin console UI. To see the full list in Google, go to Account → Admin roles → View all roles. Roles that Lumos doesn’t have a friendly name for appear with the raw name Google returns. An entitlement named “Archived” appears in Lumos. “Archived” is a Google Workspace Archived User license rather than an admin role. It shows up when a user in your domain has that license assigned. You can confirm which license types your domain holds in the Google Admin console under Billing → Subscriptions. Lumos shows license data even though I didn’t add a license scope myself. Reading assigned licenses comes from apps.licensing, which is part of the default scope set authorized through domain-wide delegation, so it’s usually granted alongside the other defaults even if you didn’t add it individually. If your tenant is on a custom reduced scope set, license data needs apps.licensing and Google Workspace Admin roles need admin.directory.rolemanagement. Contact Support to have either one added. Account data in Lumos never changes. If the Google Workspace app in Lumos was created from a one-time file import rather than a live connection, no sync runs against the Google APIs and the account list stays static. Check the app’s last sync time in Lumos. If it has never synced, complete the connection steps above so Lumos can pull directly from Google. I can’t browse Google Groups and their members in the Lumos UI. Groups synced from Google Workspace are available wherever you select permissions, for example in access policies and pre-approval rules, but there’s no dedicated view today for opening a group and listing its members. To review group membership in the meantime, query it through the Lumos API. Why am I getting a “not an approved email for your domain” message when connecting Google Workspace? Your new Google Workspace tenant likely has a different email domain, and new domains need to be allowlisted in your Lumos tenant before you can add them. Contact Lumos through Slack or support@lumos.com with the email domain tied to your new Google Workspace tenant and the team can add it to your account. Once it’s confirmed, you can finish the connection.

​
Reconciling Google Workspace

To match user counts between the Google Workspace UI and the Google Workspace integration in Lumos:
  1. Go to the Google Workspace app in Lumos.
  2. Apply these filters to the table. Set Account Status to All Active Statuses and Source to Lumos integration.
  3. In Google Workspace, download the file of users from the admin console and filter the Status [READ ONLY] column to “Active”. The number of records in the file after filtering should match the number of rows after applying your filters.
If the data still doesn’t match, create a ticket for Lumos Support through Slack or at support@lumos.com with the User CSV you pulled directly from the app (and how you pulled it) and the link to your Google Workspace app in Lumos with the filters applied.