Secure60 Google Workspace Connector

Overview

The Secure60 Google Workspace Connector is a lightweight container that collects Google Workspace audit and authentication logs and sends them to Secure60 — either to your Secure60 Collector or directly to the Secure60 ingest endpoint. You deploy it in your own environment, and your Google credentials stay with you: the service-account key and configuration live in local files and are never stored by Secure60.

It polls the Google Admin SDK Reports API — the same approach used by the major SIEM platforms — collecting one feed per Workspace application so you get login, admin, Drive, OAuth-token, SAML, groups and more:

What It Collects

The default set of Reports applications is the security-relevant core: login, admin, drive, token, saml, groups, user_accounts, mobile, context_aware_access, rules, access_transparency. You can change the list, and any application your admin can’t read is skipped automatically.

OAuth / third-party-app visibility. The token feed shows every app a user authorizes (for example Claude or Slack) as operation=oauth-authorize, with the app in the auth_application field and the requested scopes in event_param_scope_*. That lets you inventory connected apps and spot risky grants (drive, gmail.*) versus identity-only ones (userinfo.email, openid).

Key Capabilities

• Reports API collection — polls Google’s audit reports on a schedule (every five minutes by default), one feed per Workspace application.
• Service-account authentication with domain-wide delegation — read-only, and scoped to audit logs only. See What access this grants.
• Common Information Model output — events are normalized into the Secure60 Common Information Model (CIM) before they leave the connector, so Rules and Entity Analysis work out of the box.
• Detection-friendly fields — nested Google structures (including each activity’s parameters) are flattened into discrete, queryable fields, so you can write precise rules without parsing JSON.
• Reliable, resumable collection — a durable checkpoint per feed, automatic de-duplication, and a trailing re-scan window so late-arriving events (Google’s OAuth-token logs can lag a couple of hours) aren’t missed. Restarts resume without gaps.
• No Google Cloud SDK required — a guided setup tool runs inside the connector image; credential creation is a short browser click-through.
• Self-contained — ships as a Docker image with a short configuration file.

How It Works

• The connector authenticates to Google with a service account that impersonates a Workspace administrator (read-only), and requests audit activity on a schedule.
• It reads each Workspace application’s activity feed, normalizes every record into the Secure60 CIM, and forwards the events in batches to your chosen destination.
• It keeps a checkpoint per feed so that, after a restart, collection resumes from where it left off — and de-duplicates so repeated records are dropped.
• A single Google activity record can contain several sub-events; the connector emits one Secure60 event per sub-event, which is friendlier for detections.

What Access This Grants

The connector is deliberately minimal, on two separate surfaces:

• In Google Cloud: the service account is created with no roles, so it has zero access to any Cloud resource. A Cloud project is used only as a container for the credential (Google requires one for every API) — no Google Cloud data is read.
• In Google Workspace: the single scope https://www.googleapis.com/auth/admin.reports.audit.readonly grants read-only access to audit activity reports only — login, admin, Drive, token and SAML audit events. It cannot read email, cannot read Drive file contents, cannot see user data, and cannot change anything. It is the narrowest audit scope Google offers.

Prerequisites

1. A Google Workspace tenant and a super-administrator account to authorize the connector’s read-only access (a one-time, ~30-second step).
2. A Google Cloud project to hold the service-account credential. This is only a credential container — you enable one API and nothing else. If your organization blocks service-account key downloads, see If key creation is blocked.
3. A Docker host in your environment to run the connector.
4. A Secure60 destination — either your Secure60 Collector URL, or a Secure60 project ID and ingest token (from the Secure60 portal).

Quick Start

Step 1: Create the credential and verify (guided)

A guided setup tool runs inside the connector image, so there is nothing to install locally — no Google Cloud SDK, no Python. From the folder where you’ll run the connector:

docker run --rm -it -v "$PWD:/work" -w /work \
  secure60/s60-google-connector:latest python /app/setup.py

It walks you through the browser steps, then does the rest for you:

1. Prints the Google Cloud Console steps — create/select a project, enable the Admin SDK API, create a service account (no roles), and download a JSON key.
2. Reads the key you point it at and shows the exact Client ID + scope to paste into the Admin console (Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new).
3. Verifies end-to-end — reads one login event as your admin, so you know the authorization works before you deploy.
4. Writes your .env-google-connector (it asks whether to send to the Secure60 ingest endpoint or to your Secure60 Collector).

Prefer to do every step by hand? Follow the Manual Google Setup guide — the same Cloud Console and Admin console click-through, no tools required.

Step 2: Configure the connector

The guided tool writes .env-google-connector for you. It contains your delegated admin, the key path, and one Secure60 destination — for example:

# The Workspace super-admin the connector reads audit logs as
DELEGATED_ADMIN_EMAIL=admin@yourdomain.com
# Path to the service-account key inside the container (mounted by compose)
GOOGLE_CREDENTIALS_PATH=/secrets/sa.json

# Secure60 destination — choose ONE:
#   Send to the Secure60 ingest endpoint:
PROJECT_ID=301
TOKEN=your-secure60-ingest-token
#   …or send to your Secure60 Collector instead (TLS cert not verified):
# S60_COLLECTOR_BASE=https://your-collector:443

That is a complete configuration — everything else has a sensible default. The distinct filename lets several connectors share one deploy folder.

Step 3: Run the connector

Save this compose.yaml next to your .env-google-connector and sa.json:

services:
  s60-google-connector:
    image: "secure60/s60-google-connector:latest"
    container_name: "s60-google-connector"
    pull_policy: always
    env_file:
      - .env-google-connector
    volumes:
      # The service-account key (read-only); path matches GOOGLE_CREDENTIALS_PATH.
      - ./sa.json:/secrets/sa.json:ro
      - s60-google-state:/state
    restart: always

volumes:
  s60-google-state:

Then start it:

docker compose up -d
docker compose logs -f

You should see lines like Reports login: 3 records ... and Forwarded 3 events -> ingest (HTTP 200). Events appear in your Secure60 project within a few minutes.

Configuration Reference

A working configuration is the delegated admin plus one destination (the mounted sa.json supplies the credential). Everything below is optional and shown with its default.

The destination mode is inferred automatically: set PROJECT_ID + TOKEN for ingest, or S60_COLLECTOR_BASE for your collector.

Data Format

Events are sent as flat JSON aligned with the Secure60 CIM. Every event carries vendor=google, product=google workspace, app_name=gworkspace, technology_group=cloud, plus normalized fields and the original Google fields (prefixed event_).

Common fields:

• operation — the normalized activity, e.g. user-login, oauth-authorize, data-access, user-modify, user-password-modify, user-permission-modify, group-modify, admin-service-modify.
• outcome — success or failure.
• type — the entity the event targets: user (login/admin/groups), file (Drive), application (OAuth token), endpoint (mobile). This drives entity correlation across systems.
• user_name — the acting user (email).
• ip_src_address — the source IP address (geo-enriched on arrival).
• auth_application — on the token feed, the third-party app a user authorized (for example Claude), so you can inventory and govern OAuth grants.
• source_type — gworkspace; the specific feed is in event_id_applicationname (login, token, drive, …).
• timestamp — the time the activity occurred at the source.
• event_* — the full Google record, flattened. Each activity parameter becomes a discrete field you can match on directly, for example event_param_login_type or event_param_scope_0.

Because the data is normalized to CIM, you can correlate Google Workspace activity with other sources and write Rules against these fields immediately.

Best Practices

1. Use a super-admin only for the one-time delegation step. After that, the connector runs on its own read-only service account — it needs no interactive login.
2. Keep the scope minimal. The connector needs only admin.reports.audit.readonly; don’t add broader scopes to the same client.
3. Rotate the service-account key periodically and update the mounted sa.json. Watch for revoked delegation or a deleted key — both stop collection.
4. Run one connector per Workspace tenant.
5. Pin the image version (for example secure60/s60-google-connector:1.0) for reproducible deployments, and upgrade deliberately.
6. Watch the heartbeat. The connector emits a periodic health event; alert on its absence to catch a stalled connector quickly.
7. Govern OAuth apps. Build a report or rule on operation=oauth-authorize | group by auth_application to track third-party apps and flag high-risk scopes or newly-seen apps.

Support

For help deploying the Secure60 Google Workspace Connector, contact the integrations team at integrations@secure60.io.