Search documentation

Find a documentation page by title, topic or keyword.

Google Workspace

On this page

Google Workspace is a two-part setup: authorise Governax in your Admin console first, then connect in Governax. It is polled rather than pushed, because the admin audit log has no webhook.

Before you start#

What you need
ItemDetail
Super administrator accessDomain-wide delegation can only be authorised by a super admin.
Your primary domainFor example example.com.
A super admin email in that domainGovernax impersonates this account to read the audit log. It must end with your domain.

Authorising domain-wide delegation#

The Governax Integrations page for Google Workspace shows the client id and the exact scope list to paste. Take those values from that page rather than from here, because they are specific to your deployment.

  1. Open the Google Admin console

    Go to Security, then Access and data control, then API controls.

  2. Open Domain-wide delegation and add a new client

    Choose Manage domain-wide delegation, then Add new.

  3. Paste the client id from the Governax page

    Copy it from the Governax connect screen exactly as shown.

  4. Paste all four scopes as a comma-separated list

    https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

    All four end in .readonly. Governax cannot change anything in your Workspace with these.

  5. Authorise

    Delegation can take a few minutes to become effective. If the connect step fails immediately after authorising, wait and retry before assuming something is wrong.

What each scope is for
ScopePurpose
admin.reports.audit.readonlyThe admin audit log. This is the whole of ingestion.
admin.directory.user.readonlyThe connect-time user snapshot.
admin.directory.group.readonlyGroup detail.
admin.directory.rolemanagement.readonlyAdministrative role detail.

Connecting#

  1. Enter your primary domain

    Without a protocol prefix.

  2. Enter the super admin address to impersonate

    It must be an address within the domain you just entered. Governax validates this before attempting anything.

  3. Connect

    Governax immediately calls the Reports API using that identity. If the call fails, the connection is not left in a healthy state: it is marked disconnected and Google's own error is stored so you can see exactly what it objected to.

How polling works#

Google Workspace polling behaviour
PropertyValue
IntervalEvery 10 minutes
First pollBackfills the previous 7 days
Each subsequent pollRe-scans a 24-hour trailing window to catch late-arriving activity
Sources pulledAdmin console actions, and third-party OAuth grants

The trailing re-scan looks wasteful but is not: re-seen events are discarded by the ledger's duplicate handling, so the only cost is a query. Google's audit log can surface an activity well after it happened, and without the overlap those would be missed permanently.

Events captured#

Google Workspace event types by area
AreaEvent types
User lifecycleresource.user_created, resource.user_deleted, resource.user_restored, access.user_suspended, access.user_unsuspended
Groupsaccess.group_member_added, access.group_member_removed, access.group_member_role_changed, resource.group_created, resource.group_deleted
Organisational unitsaccess.org_unit_changed, resource.org_unit_created, resource.org_unit_deleted, resource.org_unit_renamed, resource.org_unit_moved
Administrative privilegeaccess.admin_role_granted, access.admin_role_revoked
Authentication posturesecurity.two_step_disabled, security.two_step_enforcement_changed, security.password_changed
Third-party accesssecurity.oauth_app_trusted, security.oauth_app_untrusted, access.third_party_app_granted, access.third_party_app_revoked
Connect timeaccess.baseline_observed for every active user

Where the meaning matches, Google events use the same event types as Okta and AWS, so a filter on access.admin_role_granted spans all three tools.

Not captured: settings toggles and usage events. Governax also excludes its own OAuth grant, so connecting does not log Governax into your ledger.

Disconnecting#

Reconnecting later keeps the previous poll position, so a reconnect does not re-import everything from scratch.

Troubleshooting#

Common Google Workspace problems
SymptomCause and fix
Access check failed at connectDelegation is missing, incomplete, or has not propagated. Confirm all four scopes are present with no typos, and that the impersonated address is a super admin. Wait a few minutes and retry.
Admin email rejectedThe address must be within the domain you entered, and it must contain exactly one @.
Connected but no eventsGive it a poll cycle plus Google's own lag. Then check the connection's last error.
Events stoppedThe impersonated account may have been suspended or lost super admin. Check the last error on the connection.

General connector behaviour is covered in Connecting a tool.