Google Workspace Collector Configuration

Authentication Setup

The collector uses a Google service account with domain-wide delegation. This is the standard pattern for automated access to Google Workspace admin data.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create or select a project for the collector
3. Go to APIs & Services > Enabled APIs and enable the APIs the collector calls. These are separate from the OAuth scopes in Step 5: a granted scope still fails with SERVICE_DISABLED if the API isn't enabled in this project.

| API | Needed for |
|---|---|
| Admin SDK API (admin.googleapis.com) | All levels (users, reports, and at audit+ groups, org units, devices, domains, roles) |
| Groups Settings API (groupssettings.googleapis.com) | audit / internal: per-group external-members and who-can-* settings |
| Cloud Identity API (cloudidentity.googleapis.com) | audit / internal: SAML SSO profiles |
| Google Vault API (vault.googleapis.com) | audit / internal: Vault matters / holds (also needs a Vault license) |
| Access Context Manager API (accesscontextmanager.googleapis.com) | Optional device_access enrichment (when organization_id / access_policy is set) |

For a trust-only run, the Admin SDK API is sufficient. The other APIs are
only called at audit / internal; a disabled one degrades just that surface
(a diagnostic names the API, the rest of the run continues).

Step 2: Create a Service Account

1. Go to IAM & Admin > Service Accounts
2. Click Create Service Account
3. Name it (e.g., epack-collector)
4. Click Create and Continue, then Done (no roles needed at the project level)

Step 3: Enable Domain-Wide Delegation

1. Click into the service account you just created
2. Go to the Details tab
3. Under Advanced settings, click Enable Domain-wide Delegation
4. Copy the Client ID — you'll need it in the next step

Step 4: Create a JSON Key

1. Go to the Keys tab
2. Click Add Key > Create new key > JSON
3. Download the key file and store it securely
4. Important: This key grants access to your tenant. Treat it like a credential.

Step 5: Authorize Scopes in Google Workspace

In the Google Workspace Admin Console:

1. Go to Security > Access and data control > API controls > Domain-wide delegation
2. Click Add new
3. Enter the service account Client ID from Step 3
4. Grant these scopes:

• https://www.googleapis.com/auth/admin.directory.user.readonly
• https://www.googleapis.com/auth/admin.directory.customer.readonly
• https://www.googleapis.com/auth/admin.reports.usage.readonly
• https://www.googleapis.com/auth/admin.reports.audit.readonly (recommended, enables device_access evidence from Context-Aware Access audit logs)

1. Click Authorize

Step 6: Choose the Admin User to Impersonate

Set admin_email to a Google Workspace admin account. The service account impersonates this user to access admin APIs. The account needs permission to read users, customer metadata, usage reports, and optionally audit activity for Context-Aware Access.

Optional Step 7: Enable Access Context Manager Enrichment

If you want the detailed artifact to include Access Context Manager access-level config alongside Context-Aware Access deny evidence:

1. Grant the service account the Access Context Manager Reader role (roles/accesscontextmanager.policyReader) on the relevant Google Cloud organization.
2. Set either:
   • organization_id to let the collector discover the access policy under organizations/{id}, or
   • access_policy to an explicit Access Context Manager policy resource like accessPolicies/123456789 (or just the numeric ID).

This enrichment is optional. It improves the detailed device_access section, but the normalized artifact remains conservative because Workspace-side app assignment and monitor-mode details are not fully exposed by API.

Configuration Options

Environment Variables

Troubleshooting

"creating JWT config" error

• Verify the GOOGLE_SERVICE_ACCOUNT_JSON environment variable contains the full JSON key file content (not a file path)
• Ensure the JSON is valid — copy-paste errors can truncate the key

401 Unauthorized

• Verify the admin_email is a real Google Workspace admin account (not a regular user)
• Ensure domain-wide delegation is enabled on the service account
• Check that the Client ID in the Admin Console matches the service account

403 Forbidden

• Verify all required scopes are authorized in the Admin Console under domain-wide delegation
• Ensure the admin account has permission to access usage reports and user data
• Check that the Admin SDK API is enabled in the Google Cloud project
• If only the audit scope is missing, the collector still emits the core posture artifact but omits device_access evidence and adds a warning to diagnostics
• If Access Context Manager enrichment is configured, verify the service account has roles/accesscontextmanager.policyReader on the organization and that the organization_id or access_policy value is correct

Empty or missing usage report data

• Usage reports are typically available for the previous day. Very new tenants may not have report data yet.
• The usage_report_date field in the output shows which day the report covers.

Examples

Basic Usage

stream: myorg/google-workspace-posture

collectors:
  google-workspace:
    source: locktivity/epack-collector-google-workspace@^0.2
    config:
      admin_email: admin@example.com
    secrets:
      - GOOGLE_SERVICE_ACCOUNT_JSON

Then run:

export GOOGLE_SERVICE_ACCOUNT_JSON="$(cat /path/to/service-account.json)"
epack collect

See Configuration for service account setup instructions.

Explicit Customer Key

If your service account has access to a specific Google Workspace tenant, set the customer key explicitly:

collectors:
  google-workspace:
    source: locktivity/epack-collector-google-workspace@^0.2
    config:
      customer: C0123abc
      organization_id: "987654321"
      admin_email: admin@example.com
    secrets:
      - GOOGLE_SERVICE_ACCOUNT_JSON

Sample Output

The collector always emits the detailed artifact. The normalized artifact is included when the usage report contains data (omitted for new tenants or delayed reports).

artifacts/google-workspace.json

{
  "schema_version": "1.0.0",
  "collected_at": "2026-04-08T12:00:00Z",
  "usage_report_date": "2026-04-07",
  "provider": "google-workspace",
  "org_domain": "example.com",
  "customer_id": "C123abc",
  "users": {
    "total": 120,
    "suspended": 10,
    "archived": 5,
    "locked_pct": 0.83,
    "inactive_pct": 4.76,
    "inactive_days": 90
  },
  "activity": {
    "active_7d_pct": 78.33,
    "active_30d_pct": 91.67
  },
  "authentication": {
    "2sv_enrolled_pct": 92.5,
    "2sv_enforced_pct": 88.33,
    "2sv_protected_pct": 90.0,
    "passkey_users_pct": 12.5,
    "security_keys_total": 35
  },
  "admins": {
    "privileged_users_count": 7,
    "super_admin_count": 3,
    "delegated_admin_count": 5,
    "privileged_users_2sv_enrolled_pct": 85.71,
    "privileged_users_2sv_enforced_pct": 100.0
  },
  "passwords": {
    "weak_password_pct": 4.17,
    "password_length_non_compliant_pct": 2.5
  },
  "apps": {
    "authorized_apps_count": 47
  },
  "device_access": {
    "lookback_days": 90,
    "context_aware_access_denied_events": 12,
    "device_state_denied_events": 4,
    "managed_device_requirement_evidenced": true,
    "access_context_manager": {
      "access_policy_name": "accessPolicies/123456789",
      "access_policy_parent": "organizations/987654321",
      "basic_access_levels_count": 6,
      "custom_access_levels_count": 1,
      "basic_device_policy_access_levels_count": 2,
      "basic_managed_device_access_levels_count": 1,
      "basic_device_policy_access_level_titles": ["Corp Device", "High Trust Device"]
    }
  }
}

artifacts/google-workspace.idp-posture.json

{
  "schema_version": "1.0.0",
  "collected_at": "2026-04-08T12:00:00Z",
  "provider": "google_workspace",
  "org_domain": "example.com",
  "user_security": {
    "mfa_coverage_pct": 90.0,
    "mfa_phishing_resistant_pct": 12.5,
    "inactive_pct": 4.76,
    "locked_out_pct": 0.83,
    "weak_password_pct": 4.17,
    "password_policy_noncompliant_pct": 2.5
  },
  "app_security": {
    "authorized_third_party_apps_count": 47
  },
  "privileged_access": {
    "privileged_users_count": 7,
    "super_admin_count": 3,
    "privileged_mfa_coverage_pct": 85.71,
    "standing_privileged_users_count": 7
  },
  "policy": {
    "mfa_required": false,
    "mfa_required_coverage_pct": 88.33,
    "legacy_auth_blocked": true
  },
  "lifecycle": {
    "suspended_pct": 8.33,
    "archived_pct": 4.17
  },
  "device_access": {
    "managed_device_required": true
  }
}

All coverage values are percentages (0-100). See Overview for detailed metric descriptions.

CI/CD Integration

GitHub Actions

name: Collect Google Workspace Posture

on:
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install epack
        run: |
          curl -sSL https://install.epack.dev | bash

      - name: Collect evidence
        run: epack collect --frozen
        env:
          GOOGLE_SERVICE_ACCOUNT_JSON: ${{ secrets.GOOGLE_SERVICE_ACCOUNT_JSON }}

Store the service account JSON as a repository secret named GOOGLE_SERVICE_ACCOUNT_JSON.

Multiple Google Workspace Tenants

If a single service account has domain-wide delegation across tenants, use the customer key to target each one in its own epack.yaml:

# epack-prod.yaml
collectors:
  google-workspace:
    source: locktivity/epack-collector-google-workspace@^0.2
    config:
      customer: C0abc123
      admin_email: admin@company.com
    secrets:
      - GOOGLE_SERVICE_ACCOUNT_JSON

# epack-subsidiary.yaml
collectors:
  google-workspace:
    source: locktivity/epack-collector-google-workspace@^0.2
    config:
      customer: C0def456
      admin_email: admin@subsidiary.com
    secrets:
      - GOOGLE_SERVICE_ACCOUNT_JSON

export GOOGLE_SERVICE_ACCOUNT_JSON="$(cat service-account.json)"
epack collect -c epack-prod.yaml
epack collect -c epack-subsidiary.yaml

If each tenant requires its own service account, run separate invocations with different credentials:

GOOGLE_SERVICE_ACCOUNT_JSON="$(cat prod-sa.json)" epack collect -c epack-prod.yaml
GOOGLE_SERVICE_ACCOUNT_JSON="$(cat subsidiary-sa.json)" epack collect -c epack-subsidiary.yaml