elastic / elastic/integrations
[New Integration] Google Workspace Entity Analytics
- Dominant language
- Handlebars
- Stars
- 333
- Forks
- 647
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 209
Description
## 1. Summary
Collect user and group inventory from Google Workspace into Elastic Security as first-class entities, compatible with the Entity Store. Google Workspace is the primary identity provider for many organizations; this integration brings Directory user and group data into Entity Analytics — for identity-based detections, enrichment, and investigation — the same way Elastic already does for Okta, Entra ID, and Active Directory.
## 2. Vendor and product
Google Workspace exposes identity inventory through the Admin SDK Directory API (users, groups, members) and Groups Settings API (per-group policy settings).
- **Transport:** Google Admin SDK REST APIs. The integration polls on a schedule; nothing needs to be opened inbound.
- **Auth:** GCP service account with domain-wide delegation (DWD), including GKE Workload Identity with service account impersonation. Required scopes: `admin.directory.user.readonly`, `admin.directory.group.readonly`, and `apps.groups.settings`.
- **Deployment:** built as an entity-analytics API pull in the same pattern as `entityanalytics_okta` / `entityanalytics_entra_id`, so it can run agentless.
## 3. Data
Three typed inventory sources:
- **Users** — Directory user inventory: primary email, display / given / family name, org unit path, account status (active/suspended), admin and delegated-admin flags, last login, creation time, 2SV enrollment and enforcement, aliases, department/title, and phones. Source: `users().list(customer="my_customer")` (paginated). Must-have for v1.
- **Groups** — Group inventory enriched with Groups Settings: name, email, description, member count, group type/kind, plus who can join, post, and view members. Source: `groups().list(...)` plus per-group Groups Settings `groups().get(...)`. Must-have for v1.
- **Group membership** — Which users (and nested groups) belong to each group, with membership role (`member` / `manager` / `owner`). Source: `GET /admin/directory/v1/groups/{groupKey}/members`. Must-have for v1.
These streams should map to the user/group entity fields Entity Analytics keys on, so Google Workspace identities merge with the same users and groups seen from Okta or other sources rather than creating separate entities.
## 4. What we get
Google Workspace identity inventory in Elastic, mapped for Entity Analytics and joinable to the same users across a customer’s other data. User inventory gives account status, org-unit, admin privilege, and 2SV posture for enrichment and detection. Group inventory and membership give security-group membership and privilege context without manual ES|QL joins against audit logs. Closes the identity-source gap for Google-first orgs that today only get partial signal from Google Workspace Reports events.
## 5. Dashboards
A user inventory overview:
- users by org unit and account status (active/suspended)
- admin and delegated-admin population
- 2SV enrolled vs enforced
- recent last-login / stale accounts
- a user detail table for investigation
A group and membership view:
- groups by type and member count
- membership roles (member/manager/owner)
- nested group relationships
- high-privilege or high-membership groups
- a membership table for review
## 6. References
- [Admin SDK Directory API overview](https://developers.google.com/admin-sdk/directory/v1/get-start/getting-started)
- [Users: list](https://developers.google.com/admin-sdk/directory/v1/reference/users/list)
- [Groups: list](https://developers.google.com/admin-sdk/directory/v1/reference/groups/list)
- [Members: list](https://developers.google.com/admin-sdk/directory/v1/reference/members/list)
- [Service account with domain-wide delegation](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority)
- Related packages: `entityanalytics_okta`, `entityanalytics_entra_id`, `entityanalytics_ad`
Contributor guide
Research direction
Compare the related entityanalytics_okta, entityanalytics_entra_id, and entityanalytics_ad packages to understand the entity-analytics API pull pattern. Review the Admin SDK users, groups, and members endpoints plus Groups Settings API, then define the three inventory streams and their Entity Analytics field mappings. Done should include the v1 users, groups, and membership sources with the listed dashboards and authentication support.
Written by the indexing model from the issue text.
Assessment
- Domain
- authentication, backend-api-design, data, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100