Google Workspace

At a glance

Vendor	Google Workspace
Source type	google_workspace
Vendor ID (slug)	google-workspace
Base URL	https://admin.googleapis.com — fixed for every Workspace tenant
Auth method	oauth2 — Authorization: Bearer <access_token> minted per run from a domain-wide-delegated service account JWT
Schedule default	daily
Availability	Stable — presentation refreshed 2026-04-18.

Required scopes & roles

Draxis authenticates as a GCP service account with domain-wide delegation, impersonating a read-only Workspace admin. The service account needs exactly these three read-only OAuth scopes — nothing more:

• https://www.googleapis.com/auth/admin.directory.user.readonly — list users, 2SV enrollment state, admin flags, suspended/archived state. Backs the /admin/directory/v1/users call.
• https://www.googleapis.com/auth/admin.reports.audit.readonly — read Admin, Token, and Drive audit logs. Backs the /admin/reports/v1/activity/users/all/applications/{admin,token,drive} calls.
• https://www.googleapis.com/auth/admin.reports.usage.readonly — reserved for future usage-based KRIs; included now so you don’t need a second consent pass later.

On the Workspace side, the impersonated subject must be a user with a role that can read those APIs. The Google-provided “Services admin” predefined role works; for tighter least-privilege, create a custom admin role that grants only Admin API Privileges → Users → Read and Reports.

Do not grant the service account the Super Admin role — none of these scopes require it, and it would also grant write access.

Setup steps

1. Create a GCP project and service account. In the Google Cloud Console, pick (or create) a project dedicated to third-party integrations, then go to IAM & Admin → Service Accounts → Create Service Account. Name it draxis-workspace-reader. Skip the “Grant this service account access to project” step — it needs zero GCP IAM roles.
2. Enable the Admin SDK API on the project. APIs & Services → Library → Admin SDK API → Enable.
3. Generate a JSON key. On the service account’s Keys tab, Add Key → Create new key → JSON. Save the file — you’ll paste the entire contents into Draxis in the final step. Treat it like a password.
4. Enable domain-wide delegation. On the service account’s Details page, copy its Unique ID (OAuth 2.0 Client ID) — a numeric string. You’ll paste it in the next step.
5. Authorize the scopes in the Workspace Admin Console. Go to admin.google.com → Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new. Paste the numeric Client ID from step 4, then paste these three scopes (comma-separated):

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

   Click Authorize.
6. Pick (or create) a read-only admin user to impersonate. In the Admin Console, Directory → Users → Add new user, e.g. draxis-reader@your-domain.com. Assign it the Services admin role (or the custom read-only role described above). This is the email you’ll put in the Draxis Client ID field — Draxis impersonates this user when calling Google.
7. Verify the customer ID (optional). Most tenants can leave customer_id as my_customer. If you’re a Workspace reseller or manage multiple customers, find the real customer ID under Account → Account settings and put it in the Draxis Extra Config JSON as {"customer_id":"C01xxxxxx"}.

Wire it into Draxis

1. Open Settings → Integrations in your tenant.
2. Click Add integration and pick Google Workspace as the source type.
3. The vendor dropdown auto-selects Google Workspace (Admin SDK + Reports), and Draxis auto-fills the base URL, the OAuth auth method, the daily schedule, and seeds extra_config_json with {"customer_id":"my_customer"}.
4. In Client ID, paste the admin email from step 6 above (e.g. draxis-reader@your-domain.com). This is the user Draxis impersonates — not the service-account numeric ID.
5. In Client Secret, paste the entire contents of the JSON key file from step 3 — every character including the enclosing { … }. Draxis encrypts it server-side with encryption.key before storage.
6. Click Test. Green means Draxis minted a JWT, exchanged it for an access token, and hit the Directory API successfully.
7. Under KRIs to import, tick the KRIs you want Draxis to manage. All seven gws_* KRIs are checked by default; uncheck any you don’t need. Selected rows are created on save with the seeded thresholds (tunable later in the KRIs tab). Unchecking a previously-imported KRI deletes it on save.
8. Save. The connector runs daily by default; use Run now from run history to trigger the first sync immediately.

KRIs produced

Slug	Meaning	Derivation
gws_2sv_enrollment_pct	% of active users enrolled in 2-Step Verification	round(count(active[].isEnrolledIn2Sv) / count(active), 1) where active = users[!suspended && !archived]
gws_super_admin_count	Count of users flagged isAdmin=true in the Directory API	count(users[].isAdmin == true)
gws_ext_shared_sensitive_files	Drive ACL changes that set visibility to an external audience, last 7 days	count(drive_events where name in (change_user_access, change_acl_editors, change_document_visibility) and visibility in (people_with_link, public_on_the_web, public_in_the_domain_with_link, shared_externally))
gws_oauth_high_risk_apps	Distinct OAuth client_ids authorized with high-risk scopes in the last 7 days	distinct(token_events[authorize].client_id where any(scope matches mail.google.com | gmail.send|modify|insert | drive | admin.directory | admin.reports | cloud-platform | cloud_search))
gws_suspended_active_ratio_pct	Suspended users as a % of active users	round(count(suspended) / count(active) * 100, 1)
gws_admin_audit_anomalies_7d	Count of privileged admin events in the last 7 days	count(admin_events where name or type in (ASSIGN_ROLE, UNASSIGN_ROLE, CREATE_ROLE, DELETE_ROLE, UPDATE_ROLE, DELEGATED_ADMIN_SETTINGS, GRANT_ADMIN_PRIVILEGE, REVOKE_ADMIN_PRIVILEGE, TOGGLE_2SV_ENFORCEMENT, CHANGE_ALLOWED_TWO_STEP_VERIFICATION_METHODS, SSO_PROFILE_CREATED, SSO_PROFILE_DELETED))
gws_dlp_violations_7d	Count of Drive DLP rule-violation events in the last 7 days	count(drive_events where name startsWith 'dlp_' or type contains 'dlp')

Each row is a slug the connector writes to. Draxis creates the matching kri rows automatically when you check them in the KRIs to import section of the integration form — no manual API call or seed script needed. Thresholds shown in the table are the seeded defaults; you can edit them freely in the KRIs tab afterwards.

Vendor quirks

• Domain-wide delegation is mandatory. Without it the JWT-bearer token exchange returns unauthorized_client. The scope list in Workspace must match exactly — a typo in one scope silently blocks access to that API.
• Service-account impersonation is how Google Workspace does least-privilege. The service account itself has no powers; the impersonated subject’s Workspace role is what actually gates access. Keep that subject on a read-only custom role if you want the strictest least-privilege posture.
• Reports API has a ~20-minute lag. Events appearing in the Admin Console may take up to ~20 minutes to surface through /admin/reports/v1/activity. Draxis’s 7-day window always trails real time, so this is invisible in practice.
• customer_id=my_customer works for almost everyone. Only resellers or multi-customer setups need the real numeric customer ID. If Test returns HTTP 400 with “Invalid Input: customer”, replace it with your real ID from the Admin Console’s account settings.
• Pagination is capped at 200 pages per endpoint. At 500 users/page that’s 100k users; at default Reports page sizes it’s well past any 7-day window we’ve seen. Very large tenants that hit the cap should open a support request — we’ll tune the window or paginate in chunks.
• Service-account JSON keys are credentials. If a key is ever exposed, revoke it in the GCP console (Keys → Delete) and generate a new one — the old key stops working immediately, so do this only after you’re ready to update Draxis.

Troubleshooting

• HTTP 401 unauthorized_client at the token exchange — domain-wide delegation isn’t set up, or the scope list in the Workspace Admin Console doesn’t match the three scopes above. Re-check the numeric Client ID and the exact scope strings.
• HTTP 403 on Directory or Reports calls — the impersonated user’s Workspace role is too narrow. Grant them Services admin (or add Users → Read and Reports privileges to your custom role).
• HTTP 400 “Invalid Input: customer” — you’re a reseller or multi-customer tenant and my_customer doesn’t resolve. Replace the customer_id in Extra Config with the real customer ID.
• “Client Secret is not valid JSON” on Test — you pasted something other than the full service-account key file. Paste the entire JSON including the outer braces.
• rowsSkipped > 0 and rowsWritten = 0 — your tenant hasn’t imported any KRIs for this integration yet. Open the integration in Settings → Integrations, tick the KRIs under KRIs to import, and save.
• Still stuck? Open a support ticket with the run ID (from Run history) and we’ll dig in.