Skip to main content
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 integration, with its own tile in Lumos, so connecting one doesn’t connect the other. Non-Human Identity Integrations with Lumos 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, select the host project and note its Project number. Then go to APIs & Services → Library and enable each of these APIs:

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:
  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 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:
  5. Select Authorize.
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: 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 for what each status means. Your non-human identities then appear in the NHI Inventory.

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:
Step 5 has no gcloud command. Add the domain-wide delegation entry in the Google Admin console.

What Lumos inventories

Non-human accounts Lumos also lists Workspace users, without access, as the owners of app-specific passwords. Credentials 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.