> ## 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 Workspace

## 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

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | User account records |
| Groups | Permission | Yes | Yes | Access control groups |
| Roles | Permission | Yes | Yes | Role definitions in the Admin Console\* |

| Deprovisioning Action | Type | Description |
| :- | :- | :- |
| Deprovision | User | Permanently deletes the user's account and data. Recoverable within 20 days. |
| Suspend | User | Signs the user out of all G Suite sessions and marks the account suspended. Files stay intact, the license is unaffected, and it can be restored anytime. |
| Archive | User | Signs the user out of G Suite and archives the account. Files stay in Google Vault, but no new emails or calendar invites arrive. This uses an Archive User license and can be restored anytime. |

**Custom capabilities.** These are additional actions the Google Workspace connector can perform. They can optionally be enabled, reach out to Support to use them.

| Name | Description |
| :- | :- |
| Remove from Calendar Events | Removes the user from all future Google Calendar events. |
| Remove from all Groups | Removes the user from all Google Groups. |
| Transfer Group Ownership | Reassigns group ownership to another user. |
| Sign User Out | Signs the user out of all web and device sessions. |
| Change Users OU | Updates the organizational unit the user belongs to. |
| Transfer Data | Assigns a user to receive the data of offboarded users. |
| Reroute Emails | Assigns a user to receive rerouted emails. |
| Free Resources | Frees up resources occupied or reserved by a user (seats, memberships, and similar). |

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](https://admin.google.com/ac/owl/domainwidedelegation) page, which is usually scoped to [Super Admins](https://support.google.com/a/answer/2405986?hl=en).
* **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](mailto: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](mailto:support@lumos.com) or through Slack and describe your use case.

| Scope | Default | Description |
| :- | :- | :- |
| `https://www.googleapis.com/auth/admin.directory.user` | Yes | List all users in your Google Workspace domain and update those users. |
| `https://www.googleapis.com/auth/admin.directory.user.readonly` | Yes | List all users in your Google Workspace domain, but not update them. |
| `https://www.googleapis.com/auth/admin.directory.group` | Yes | List and manage Google Workspace groups, used for group assignments (for example, setting up App approvers). |
| `https://www.googleapis.com/auth/admin.directory.user.security` | Yes | Discover all apps your employees signed into through Google. |
| `https://www.googleapis.com/auth/gmail.settings.basic` | Yes | Reroute emails when a user is offboarded from Google Workspace. |
| `https://www.googleapis.com/auth/admin.datatransfer` | Yes | Transfer a user's data when they're offboarded from Google Workspace. |
| `https://www.googleapis.com/auth/gmail.metadata` | Yes | Find apps used by your employees based on email subject lines. This scope does not grant access to email bodies and attachments. |
| `https://www.googleapis.com/auth/apps.licensing` | Yes | View and manage G Suite licenses for your domain. |
| `https://www.googleapis.com/auth/calendar` | No | Perform calendar-related offboarding actions, including removing a user from all Calendar events. |
| `https://www.googleapis.com/auth/admin.directory.rolemanagement` | No | Provision and manage access to Google Workspace Admin roles. |
| `https://www.googleapis.com/auth/admin.directory.userschema.readonly` | No | Sync custom fields associated with users. |

> 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](mailto: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](https://app.lumosidentity.com/integrations?tab=connected) or [add new](https://app.lumosidentity.com/integrations?tab=can_integrate)) 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](https://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.

```text theme={null}
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
```

If you connected with a custom set of scopes, Lumos prompts you to add only the subset of scopes that apply for your tenant.

5. 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

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

## Troubleshooting

**I need to connect another Google Workspace tenant with a different domain.** Contact Lumos through Slack or at [support@lumos.com](mailto: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](mailto: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](https://admin.google.com/ac/owl/domainwidedelegation) 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](mailto: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](mailto: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.