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.
- 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.
Step 1: Generate the key in Lumos
- In the Lumos app, go to Integrations, open the Discover tab, and search for “Google Workspace (NHI)”.
- 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. - Select Get Key and save the public key as a file named
lumos-jwks.json.
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
- 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. - 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.
- 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.jsonfrom Step 1 - Audiences: keep Default audience
- Attribute mapping: map
google.subjecttoassertion.sub
- Issuer (URL):
- 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
Grantroles/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.
- Open the reader service account and go to its Principals with access tab.
- Select Grant access.
-
New principals, using your project number, pool ID and key identifier:
-
Role: Service Account Token Creator (
roles/iam.serviceAccountTokenCreator). - Select Save.
Step 5: Add the domain-wide delegation entry
- Sign in to the Google Admin console as a super admin.
- Go to Security → Access and data control → API controls → Manage Domain Wide Delegation and select Add new.
- Client ID: the reader’s unique ID from Step 3, not its email.
-
OAuth scopes: paste this comma-separated list:
- 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 thegcloud CLI. Do Step 1 in Lumos first, save the key as lumos-jwks.json, then replace the values at the top and run:
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
adminaudit log, which Google retains for 6 months, and adds service accounts seen in the last 30 days of thetokenlog. 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.