googleworkspacedirectorysync

Overview ¶

Package googleworkspacedirectorysync pulls the Google Workspace user directory and upserts it into saas_identities. Until this package landed, no production producer wrote to saas_identities for ANY provider — Security Graph and the executive report sourced their identity / MFA / privileged-account counts from a table that only the demo seed populated, so live tenants always saw zero. This sync closes that gap for Google.

Why a separate binary from the audit-log poller: the two read different Google APIs (admin.reports vs admin.directory), have different rate limits, and progress on very different cadences — audit-logs are minute-fresh and drive findings; the directory typically only shifts when employees join, leave, or get promoted. Running them in the same loop would force them to share an interval and would couple a Directory API outage to the audit pipeline's recovery latency.

Design notes:

• The Directory API has no streaming "since" filter; the sync does a full users.list page-walk on every tick. For a typical workspace (low thousands of users) that completes in seconds.
• Pagination uses nextPageToken; maxPagesPerTick bounds runaway fetches the same way the audit poller's maxPagesPerApp does.
• HTTP failures on a single integration update last_error and continue to the next integration; one broken tenant must not freeze the fleet.
• The saas_identities upsert is keyed on (organization_id, provider, external_id) — Google's stable user id — so renames, email changes, and re-provisioning all converge on the same row.