> ## 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 (NHI)

> Connect Lumos to Google Workspace with Workload Identity Federation and domain-wide delegation to inventory OAuth apps, delegation clients and service accounts.

> [!NOTE]
>
> The Google Workspace (NHI) connector is in Early Access. Contact your Lumos team to have it enabled for your domain.

## What you're setting up

You're giving Lumos read-only access to one Google Workspace without creating a service account key. Lumos signs a short-lived token with a key pair it generates for you. A Workload Identity Federation provider in a Google Cloud project you choose trusts that key and exchanges the token. Lumos then signs a domain-wide delegation assertion as a service account you create, the reader, and acts as a super admin with only read scopes.

Lumos uses that access to inventory the non-human identities in your Workspace:

* **OAuth apps** that your users granted access to.
* **Domain-wide delegation clients**, service accounts and OAuth clients that can act as any user.
* **Service accounts** that hold a Workspace admin role or a group membership.

It also reads the credentials that act for them (each user's OAuth grant, and app-specific passwords), the OAuth scopes, admin roles and privileges they hold, and when they were last used.

This is a separate connector from the standard [Google Workspace](https://docs.lumos.com/integrations/library/google-workspace.md) integration, with its own tile in Lumos, so connecting one doesn't connect the other. [Non-Human Identity Integrations with Lumos](https://docs.lumos.com/integrations/library/non-human/non-human-identity-integrations-with-lumos.md) explains what an NHI connector adds.

**What Lumos does NOT do:**

* **No writes.** Lumos doesn't revoke tokens, delete app-specific passwords, or change users, groups, roles or settings.
* **No service account keys.** Lumos never creates one. You upload only the public half of a key pair, and the private key never leaves Lumos.
* **No passwords.** Lumos reads app-specific passwords as metadata only: name, creation time and last use. Google never returns the password itself.
* **No content reads.** Lumos does not read mail, files, calendars or chat messages.

***

## Prerequisites

Before you start, make sure you have:

* A **host project** in Google Cloud to hold the federation trust and the reader service account. It can be an existing project.
* In the host project, permission to enable APIs, create a service account, create a workload identity pool and provider, and grant IAM roles on the service account.
* A Google Workspace **super admin** account, to add the domain-wide delegation entry and for Lumos to act as. A delegated admin can't read admin roles, the Policy API, or the OAuth grants of other admins.
* The Lumos integration page open.

One connection covers one Google Workspace.

***

## Step 1: Generate the key in Lumos

1. In the Lumos app, go to **Integrations**, open the **Discover** tab, and search for **"Google Workspace (NHI)"**.
2. Under **Workload Identity Federation**, enter a **Key Identifier**, for example `lumos-gws-nhi` (letters, numbers and hyphens). Note it; you'll use it in Step 4.
3. Select **Get Key** and save the public key as a file named `lumos-jwks.json`.

Keep this page open. You'll come back to it in Step 6.

***

## Step 2: Enable the APIs in the host project

In the [Google Cloud console](https://console.cloud.google.com/), select the host project and note its **Project number**. Then go to **APIs & Services → Library** and enable each of these APIs:

| API | Used for |
| :- | :- |
| Security Token Service API (`sts.googleapis.com`) | Exchanging the Lumos token |
| IAM Service Account Credentials API (`iamcredentials.googleapis.com`) | Signing the domain-wide delegation assertion as the reader |
| Admin SDK API (`admin.googleapis.com`) | Users, groups, organizational units, admin roles, OAuth tokens, app-specific passwords and audit logs |
| Cloud Identity API (`cloudidentity.googleapis.com`) | Service account group memberships and the Policy API |

***

## Step 3: Create the reader service account and the federation trust

1. In the host project, go to **IAM & Admin → Service Accounts** and create a service account, for example `lumos-gws-nhi-reader`. Don't grant it roles and don't create a key for it.
2. Open the service account and copy its email and its **Unique ID**, its numeric OAuth client ID. You'll use the client ID in Step 5 and the email in Step 6.
3. Go to **IAM & Admin → Workload Identity Federation** and create a pool, for example `lumos-gws-nhi-pool`, with an **OpenID Connect (OIDC)** provider:
   * **Issuer (URL)**: `https://lumos.com`, exactly, with no trailing slash
   * **JWK file (JSON)**: upload `lumos-jwks.json` from Step 1
   * **Audiences**: keep **Default audience**
   * **Attribute mapping**: map `google.subject` to `assertion.sub`
4. Open the new provider and copy its resource name, `projects/<project number>/locations/global/workloadIdentityPools/<pool ID>/providers/<provider ID>`. You'll enter it in Lumos in Step 6.

***

## Step 4: Let Lumos sign as the reader

Grant `roles/iam.serviceAccountTokenCreator` on the reader service account to the Lumos subject only. Lumos needs this role to sign the domain-wide delegation assertion as the reader.

1. Open the reader service account and go to its **Principals with access** tab.

2. Select **Grant access**.

3. **New principals**, using your project number, pool ID and key identifier:

   ```plaintext theme={null}
   principal://iam.googleapis.com/projects/<project number>/locations/global/workloadIdentityPools/<pool ID>/subject/lumos:gws-nhi:<key identifier>
   ```

4. **Role**: **Service Account Token Creator** (`roles/iam.serviceAccountTokenCreator`).

5. Select **Save**.

***

## Step 5: Add the domain-wide delegation entry

1. Sign in to the [Google Admin console](https://admin.google.com/) as a super admin.

2. Go to **Security → Access and data control → API controls → Manage Domain Wide Delegation** and select **Add new**.

3. **Client ID**: the reader's unique ID from Step 3, not its email.

4. **OAuth scopes**: paste this comma-separated list:

   ```plaintext theme={null}
   https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/cloud-identity.groups.readonly,https://www.googleapis.com/auth/cloud-identity.policies.readonly
   ```

5. Select **Authorize**.

| Scope | Used for |
| :- | :- |
| `admin.directory.customer.readonly` | The customer (tenant) |
| `admin.directory.user.readonly` | Users and the super admin check |
| `admin.directory.user.security` | Each user's OAuth tokens and app-specific passwords |
| `admin.directory.group.readonly` | Groups and their members |
| `admin.directory.orgunit.readonly` | Organizational units |
| `admin.directory.rolemanagement.readonly` | Admin roles, privileges and role assignments |
| `admin.reports.audit.readonly` | The `admin` and `token` audit logs, for domain-wide delegation clients and last activity |
| `cloud-identity.groups.readonly` | Group memberships of service accounts. Only Cloud Identity identifies a group member as a service account |
| `cloud-identity.policies.readonly` | API controls and Marketplace settings from the Policy API |

Every scope is read-only except `admin.directory.user.security`. It's the only scope Google offers for listing OAuth tokens and app-specific passwords. It would also allow revoking them, which Lumos never does.

A new or changed entry can take a few minutes to apply.

***

## Step 6: Connect in Lumos

Back on the Lumos page from Step 1, fill in the settings:

| Setting | Value |
| :- | :- |
| **Workload Identity Federation provider** | The provider resource name from Step 3, for example `projects/123456789012/locations/global/workloadIdentityPools/lumos-gws-nhi-pool/providers/lumos-nhi` |
| **Reader service account** | The reader's email from Step 3 |
| **Super admin email** | The email of the super admin Lumos acts as |
| **Fetch app password metadata** | On by default. Lists every user's app-specific passwords: name, creation time and last use |
| **Fetch last activity** | On by default. Reads when domain-wide delegation clients, and on Enterprise editions OAuth apps, were last used, from the `token` audit log |

Select **Validate**. When **Valid Credentials** appears, select **Complete**.

When you validate, Lumos signs a token, exchanges it with Google, signs as the reader, and requests one token per scope, so a scope missing from the domain-wide delegation entry is named. It then checks that the admin is a super admin and that the Policy API answers. If a check fails, the message names what to fix. If Google returns a server error or the network fails at that moment, Lumos saves the connection without finishing the check.

After you connect, the connector's **"Integrations"** tab shows its sync status. See [NHI Connector Sync Status](https://docs.lumos.com/nhi-sync-status.md) for what each status means. Your non-human identities then appear in the [NHI Inventory](https://docs.lumos.com/nhi-inventory.md).

***

## Setting up with the gcloud CLI

Steps 2 to 4 can also be run from the `gcloud` CLI. Do Step 1 in Lumos first, save the key as `lumos-jwks.json`, then replace the values at the top and run:

```bash theme={null}
HOST_PROJECT_ID=my-host-project
KEY_ID=lumos-gws-nhi   # the Key Identifier from Step 1
HOST_PROJECT_NUMBER=$(gcloud projects describe "$HOST_PROJECT_ID" --format='value(projectNumber)')
READER="lumos-gws-nhi-reader@${HOST_PROJECT_ID}.iam.gserviceaccount.com"

# Step 2: enable the APIs in the host project
gcloud services enable sts.googleapis.com iamcredentials.googleapis.com \
  admin.googleapis.com cloudidentity.googleapis.com --project="$HOST_PROJECT_ID"

# Step 3: create the reader, the pool and the OIDC provider with the Lumos public key
gcloud iam service-accounts create lumos-gws-nhi-reader \
  --project="$HOST_PROJECT_ID" --display-name="Lumos Google Workspace NHI reader"
gcloud iam workload-identity-pools create lumos-gws-nhi-pool \
  --project="$HOST_PROJECT_ID" --location=global --display-name="Lumos GWS NHI Pool"
gcloud iam workload-identity-pools providers create-oidc lumos-nhi \
  --project="$HOST_PROJECT_ID" --location=global --workload-identity-pool=lumos-gws-nhi-pool \
  --issuer-uri="https://lumos.com" \
  --jwk-json-path=lumos-jwks.json \
  --attribute-mapping="google.subject=assertion.sub"

# Step 4: let only the Lumos subject sign as the reader
gcloud iam service-accounts add-iam-policy-binding "$READER" \
  --project="$HOST_PROJECT_ID" \
  --role=roles/iam.serviceAccountTokenCreator \
  --member="principal://iam.googleapis.com/projects/${HOST_PROJECT_NUMBER}/locations/global/workloadIdentityPools/lumos-gws-nhi-pool/subject/lumos:gws-nhi:${KEY_ID}"

# Values for Steps 5 and 6
echo "Client ID: $(gcloud iam service-accounts describe "$READER" --format='value(uniqueId)')"
echo "Workload Identity Federation provider: projects/${HOST_PROJECT_NUMBER}/locations/global/workloadIdentityPools/lumos-gws-nhi-pool/providers/lumos-nhi"
echo "Reader service account: ${READER}"
```

Step 5 has no `gcloud` command. Add the domain-wide delegation entry in the Google Admin console.

***

## What Lumos inventories

**Non-human accounts**

| Account type | What it is |
| :- | :- |
| OAuth app | An app your users granted OAuth access to, combining all of its grants |
| Domain-wide delegation client | A service account or OAuth client holding domain-wide delegation. Lumos marks its own reader |
| Service account | A Google Cloud service account that holds a Workspace admin role or a group membership. It links to the same service account in the [Google Cloud (NHI)](https://docs.lumos.com/integrations/library/non-human/google-cloud-nhi.md) connector |

Lumos also lists Workspace users, without access, as the owners of app-specific passwords.

**Credentials**

| Credential | What Lumos reads |
| :- | :- |
| OAuth grant | One per app and user, with the scopes that user granted |
| App-specific password | Name, creation time and last use, for the user it belongs to. Only with **Fetch app password metadata** on |

**Resources.** The customer, with its API controls and Marketplace settings from the Policy API, organizational units, groups with their nesting, groups of other customers nested in yours, and one resource per Google service family.

**Entitlements.** Admin roles where they're assigned (customer or organizational unit) and their privileges, group memberships, and each OAuth scope on its service family, with a sensitivity. Lumos assigns the scopes of each grant, app and domain-wide delegation client, and the admin roles and group memberships of service accounts. A role assignment with a condition is kept separate from unconditional access to the same role.

**Last activity.** With **Fetch last activity** on, Lumos reads each domain-wide delegation client's newest token request in the last 6 months from the `token` audit log. On Enterprise editions, it also reads each OAuth app's newest API call.

***

## Known limitations

* **Domain-wide delegation inventory is reconstructed from audit logs.** Google has no API that lists domain-wide delegation clients. Lumos replays the `admin` audit log, which Google retains for 6 months, and adds service accounts seen in the last 30 days of the `token` log. A service account authorized earlier and idle for 30 days is missed, and so is any OAuth client authorized more than 6 months ago. Clients with a numeric client ID are treated as service accounts.
* **OAuth app last activity needs an Enterprise edition,** the only edition that logs app API calls.
* **A super admin is required.** A delegated admin can't read admin roles, the Policy API, or the grants of other admins.
* **Large tenants produce many scope assignments,** because scopes are recorded per grant. For example, 10,000 users with 30 apps of 5 scopes each produce about 1.5 million rows.

***

## Security FAQ

**Why does Lumos need a scope that isn't read-only?**

`admin.directory.user.security` is the only scope Google offers for listing OAuth tokens and app-specific passwords. It would also allow revoking them. Lumos only reads with it.

**How is the key pair handled?**

Lumos generates the key pair and keeps the private key. You upload only the public key to your provider. No service account key exists for the reader. Each Google token Lumos obtains is short-lived, but the signing key stays valid until you replace or remove the public key in your provider.

**Can I remove the integration later?**

Yes. Delete the domain-wide delegation entry in the Admin console, remove the `roles/iam.serviceAccountTokenCreator` grant on the reader, disable or delete the provider or the pool, or disable or delete the reader service account. Once the change takes effect, Lumos's reads fail.
