Connecting Google Workspace

Last updated: October 7, 2024

After this article...

You'll be able to connect the Google Workspace integration to Lumos and resolve common issues that arise when connecting.

Required plan & roles

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

Your Google Workspace user should have access to the domain-wide delegation page, which is usually scoped to Super Admins.

Instructions

1. Find the Google Workspace card in your Lumos integrations (Reconnect or add new)

2. Click on the card.

3. Enter the email of a Google Workspace user with access to the domain-wide delegation page (usually a Super Admin). It's best practice to use a service account.

4. Click the Generate Client ID button in Lumos and copy the value.

5. Log into Google Workspace using the email you entered in step 3 above and do the following:

a. Go to admin.google.com/ac/owl/domainwidedelegation.

b. Click the Add New button to add a new API client.

c. Paste the value from step 4 above as the Client ID.

d. Paste the following scopes into OAuth Scopes field:

https://www.googleapis.com/auth/admin.directory.user,
https://www.googleapis.com/auth/gmail.metadata,
https://www.googleapis.com/auth/admin.directory.user.security,
https://www.googleapis.com/auth/admin.datatransfer,
https://www.googleapis.com/auth/admin.directory.group,
https://www.googleapis.com/auth/gmail.settings.basic,
https://www.googleapis.com/auth/apps.licensing

Please note that if you've connected with a custom set of scopes (you can read more on this below), Lumos will only prompt you to add the subset of scopes that apply for your tenant.

When you copy the scopes in Google Workspace, you don't need to split them onto separate lines.

e. Click the Authorize button to authorize the Lumos API token.

6. In Lumos, click the Connect Google Workspace button.

Scopes

We cannot and do not need to read your Google Drive, Google Docs, Google Sheets, or other sensitive information in your workspace.

If you want to use a custom set of scopes, please contact us at support@lumos.com or via Slack and describe your use case and requirements so we can recommend the best path forward.

Access to scopes is granted via domain-wide delegation by a Google Workspace administrator.

Scope	Default	Description
https://www.googleapis.com/auth/admin.directory.user	✅	Allows us to list all users in your Google Workspace domain and update those users.
https://www.googleapis.com/auth/admin.directory.user.readonly	✅	Allows us to list all users in your Google Workspace domain, but not update them.
https://www.googleapis.com/auth/admin.directory.group	✅	Allows us to list Google Workspace groups. These are used for group assignments (ex: setting up App approvers).
https://www.googleapis.com/auth/admin.directory.user.security	✅	Allows us to discover all apps your employees signed into through Google.
https://www.googleapis.com/auth/gmail.settings.basic	✅	Allows us to reroute emails upon the offboarding of a user from Google Workspace.
https://www.googleapis.com/auth/admin.datatransfer	✅	Allows us to transfer a user’s data upon the offboarding of a user from Google Workspace.
https://www.googleapis.com/auth/gmail.metadata	✅	Allows our machine learning algorithm to find all apps used by your employees based on email subject lines. This scope does not grant us access to your email bodies and attachments. Many customers appreciate that Lumos can create their full app inventory without access to extremely sensitive data.
https://www.googleapis.com/auth/apps.licensing	✅	View and manage G Suite licenses for your domain

Troubleshooting

I need to connect another Google Workspace tenant with a different domain

Please contact us via Slack or at support@lumos.com so we can assist, as this process currently requires assistance from our team.

I cannot connect Google Workspace.

Make sure that you're using a Super Admin in Google Workspace to connect, that the admin email you plug into Lumos matches the email you're signed into when creating an API client in Google, and that the client ID and scopes in Google match what's in Lumos.

We have seen latency with Google Workspace where it takes several minutes for the API Client in Google to "finish" registering. Sometimes the solution is to just wait 5-10 minutes after generating the client in Google and trying the connection again.