Setting up the Google Workspace collector

Follow these steps once. Steps 1 to 3 and 5 to 6 are the same whichever
authentication mode you use; step 4 is where they differ.

Step 1: Create a Cloud project

1. Open the Google Cloud console.
2. Create or select a project for the collector.
3. Go to APIs & Services > Enabled APIs and enable the APIs below.

APIs are separate from OAuth scopes. If an API is off, its surface fails with a
SERVICE_DISABLED diagnostic even when the scope is granted, and 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, for example epack-collector.
4. Click Create and Continue, then Done. It needs no project-level roles.

Step 3: Enable domain-wide delegation

1. Open the service account you just created.
2. On the Details tab, under Advanced settings, click Enable Domain-wide Delegation.
3. Copy the Client ID. Step 5 needs it.

Step 4: Set up authentication

Choose one. oidc creates no key and is preferred on CI.

Option A: auth_mode oidc

Everything here is in the same Cloud project as the service account.

1. Create a workload identity pool.
2. Create a provider in that pool trusting your CI provider's OIDC issuer.
3. Add an attribute condition restricting the provider to your repository or organization. Without one, any repository on that issuer can assume the identity.
4. Grant the workload identity principal roles/iam.workloadIdentityUser on the service account. This lets the runner act as it.
5. Grant the service account roles/iam.serviceAccountTokenCreator on itself. This lets it sign delegation assertions with the Google-managed key.
6. In epack.yaml, set auth_mode: oidc, workload_identity_provider, and service_account, and list ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN under secrets:.
7. In the workflow, grant the id-token: write permission.

Step 5 is easy to miss. The service account holds a role on itself, which looks
odd but is what allows signing without a downloaded key.

The collector builds the exchange and impersonation endpoints from the two
config keys, so no credential file is involved and no auth step is needed in the
workflow.

Option B: auth_mode service_account_key

Skip this if you followed Option A. Some organizations block key creation with
the iam.disableServiceAccountKeyCreation policy.

1. Open the service account's Keys tab.
2. Click Add Key > Create new key > JSON.
3. Store the downloaded file securely and pass its contents as GOOGLE_SERVICE_ACCOUNT_JSON.

This key grants access to your tenant. Treat it as a credential.

Step 5: Authorize scopes in Google Workspace

1. Open the Google Workspace admin console.
2. Go to Security > Access and data control > API controls > Domain-wide delegation.
3. Click Add new.
4. Enter the Client ID from step 3.
5. Add the scopes for the levels you plan to collect, from the table below.
6. Click Authorize.

All scopes as one comma-separated list, for pasting into the admin console:

https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/apps.groups.settings,https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly,https://www.googleapis.com/auth/cloud-identity.policies.readonly,https://www.googleapis.com/auth/ediscovery.readonly

Grants are not retroactive. If you add a scope later, re-grant it here.

Step 6: Choose the admin user to impersonate

Set admin_email to a Super Admin account; several of the admin API reads
require one. The read-only scopes from step 5 still limit what the collector
can read. A common setup is a dedicated epack-collector@<domain> user.

Optional: Access Context Manager enrichment

Adds access-level config to the detailed artifact alongside Context-Aware Access
deny evidence.

1. Grant the service account roles/accesscontextmanager.policyReader on the Cloud organization.
2. Set one of:
   • organization_id, to discover the policy under organizations/{id}.
   • access_policy, an explicit policy resource such as accessPolicies/123456789 or its numeric ID. Takes precedence.

The normalized artifact stays conservative either way, because Workspace-side
app assignment and monitor-mode details are not fully exposed by API.

Config options

Environment variables

Troubleshooting

A missing scope, API, or role never fails the run, except for the tenant
record: it is read first, requires a Super Admin, and stops the run when
denied (step 6). Any other affected surface is omitted and a diagnostic says
which of the three is missing, because each is fixed in a different console.

The run fails to start

Authentication fails on the first API call

With auth_mode: oidc, the exchange and the signing are deferred until
something is collected, so setup mistakes appear here rather than at startup.

A surface is missing from the artifact

Check the diagnostics block. It names which of the three grants is missing.

The password policy is missing

passwords.policy is omitted rather than zeroed when it cannot be read, so an
absent policy never reads as a permissive one. The diagnostics distinguish a
missing scope, a disabled API, an insufficient role, an edition without the
Policy API, and a tenant that exposes no policy.

Usage report data is empty

Usage reports cover the previous day, and very new tenants may have none yet.
The usage_report_date field shows which day the artifact 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,
    "policy": {
      "minimum_length": 8,
      "maximum_length": 100,
      "allowed_strength": "strong",
      "enforce_requirements_at_login": false,
      "allow_reuse": false,
      "expiration_days": 0,
      "distinct_policies": 2
    }
  },
  "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,
    "minimum_password_length": 8,
    "password_strength_required": true,
    "password_policy_enforced_for_existing_users": false
  },
  "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