Google Workspace Connector

Complete reference for collecting SOC 2 evidence from Google Workspace using the evidence SDK.

Overview

Controls supported:

CC6.1 - Logical Access Controls (2-Step Verification enforcement)
CC6.6 - Access Removal/Modification (admin roles, user lifecycle)

What it collects:

2-Step Verification (2SV) enforcement status
Admin role assignments
User lifecycle events (suspensions, deletions)
Domain security settings

What it does NOT collect:

❌ User email content (Gmail messages)
❌ Google Drive file contents
❌ Calendar events or details
❌ Chat/Meet conversation content
❌ User passwords
❌ OAuth tokens

Configuration Schema

Required Fields

Field	Type	Description	Example
`mode`	enum	Authentication mode (currently only `service_account`)	`service_account`
`credentials_env`	string	Environment variable with service account JSON path	`GOOGLE_APPLICATION_CREDENTIALS`
`customer_id`	string	Google Workspace customer ID	`C0xxxxxxx`
`admin_email`	string	Admin email for domain-wide delegation	`admin@acme.com`

Optional Fields

Field	Type	Default	Description
`domains`	array	`[]`	Additional domains to collect from
`controls`	array	(all)	Limit which controls to collect for
`timeout_seconds`	number	`60`	Request timeout in seconds

Basic Configuration

Single Domain

framework: soc2_type1
controls:
  - CC6.1
  - CC6.6
sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@acme.com

Collects from:

Primary domain
All users in domain
Admin role assignments

Environment variable:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Multiple Domains

sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C0xxxxxxx
    admin_email: admin@acme.com
    domains:
      - acme.com
      - subsidiary.acme.com

Use case: Organizations with multiple domains

Service Account Setup

Step 1: Create Service Account

Go to Google Cloud Console
Create or select a project
Navigate to "IAM & Admin" → "Service Accounts"
Click "Create Service Account"
Name: evidence-collector
Click "Create and Continue"
Skip "Grant this service account access to project" (not needed)
Click "Done"

Step 2: Create Service Account Key

Click on the service account you created
Go to "Keys" tab
Click "Add Key" → "Create new key"
Select "JSON" format
Click "Create"
Save the downloaded JSON file securely

File format:

{
  "type": "service_account",
  "project_id": "your-project",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "client_email": "evidence-collector@your-project.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

Step 3: Enable Domain-Wide Delegation

In service account details, click "Show Advanced Settings"
Under "Domain-wide Delegation", copy the "Client ID"
Go to Google Admin Console
Navigate to "Security" → "Access and data control" → "API controls"
Click "Manage Domain Wide Delegation"
Click "Add new"
Paste the Client ID
Add OAuth scopes (see Required Scopes section)
Click "Authorize"

Artifacts Collected

Filename	API Endpoint	Controls	Description
`2sv_enforcement.json`	Admin SDK - Settings	CC6.1	2-Step Verification enforcement status
`admin_roles.json`	Admin SDK - Directory	CC6.6	Admin role assignments and privileges
`user_lifecycle.json`	Admin SDK - Reports	CC6.6	User suspension, deletion, recovery events
`domain_security.json`	Admin SDK - Settings	CC6.1	Domain-wide security settings

Artifact Details

2SV Enforcement (`2sv_enforcement.json`)

Purpose: Verify 2-Step Verification is enforced for all users

Sample artifact:

{
  "enforceStrongAuthentication": true,
  "allowStrongAuthentication": true,
  "enforcementDate": "2025-06-01T00:00:00Z",
  "remindersEnabled": true,
  "securityDefaults": {
    "enabled": true
  }
}

Control mapping:

CC6.1: 2SV enforcement prevents unauthorized access

Pass criteria:

✅ enforceStrongAuthentication: true
✅ enforcementDate in the past (enforcement active)
✅ Applied to all users (no exemptions)

Remediation if failing:

Go to Google Admin Console → Security → Authentication → 2-Step Verification
Click "Enforce 2-Step Verification"
Set enforcement date (recommended: immediate)
Enable reminders for users
Remove exemptions for regular users (admins may have temporary exemptions during rollout)

Admin Roles (`admin_roles.json`)

Purpose: Verify admin role assignments are appropriate

Sample artifact:

{
  "roles": [
    {
      "roleId": "1234567890",
      "roleName": "Super Admin",
      "roleDescription": "Full administrative access",
      "isSuperAdminRole": true,
      "rolePrivileges": [
        {
          "privilegeName": "ADMIN_CONSOLE",
          "serviceId": "00uc3kw0akzqdm8bpo3"
        }
      ],
      "assignments": [
        {
          "assignedTo": "admin@acme.com",
          "assigneeType": "user",
          "assignedAt": "2025-01-15T10:00:00Z"
        },
        {
          "assignedTo": "security-lead@acme.com",
          "assigneeType": "user",
          "assignedAt": "2025-02-01T12:00:00Z"
        }
      ]
    },
    {
      "roleId": "0987654321",
      "roleName": "User Management Admin",
      "roleDescription": "Manage users and groups",
      "isSuperAdminRole": false,
      "rolePrivileges": [
        {
          "privilegeName": "USER_MANAGEMENT",
          "serviceId": "00uc3kw0akzqdm8bpo3"
        }
      ],
      "assignments": [
        {
          "assignedTo": "hr-lead@acme.com",
          "assigneeType": "user",
          "assignedAt": "2025-03-10T14:30:00Z"
        }
      ]
    }
  ]
}

Control mapping:

CC6.6: Admin role assignments should follow least privilege principle

Pass criteria:

✅ Super Admin role assigned to 2-5 people maximum
✅ Role assignments documented and justified
✅ No overly broad role assignments
✅ Roles reviewed periodically

Remediation if failing:

Go to Google Admin Console → Admin roles
Review each role assignment
Remove unnecessary Super Admin assignments
Use more specific roles (User Management Admin, Groups Admin, etc.)
Document each admin assignment with justification

User Lifecycle (`user_lifecycle.json`)

Purpose: Track user suspensions, deletions, and recoveries

Sample artifact:

{
  "events": [
    {
      "eventType": "USER_SUSPEND",
      "timestamp": "2026-01-05T16:20:00Z",
      "actor": "admin@acme.com",
      "targetUser": "former-employee@acme.com",
      "reason": "Employment terminated"
    },
    {
      "eventType": "USER_DELETE",
      "timestamp": "2026-01-09T10:00:00Z",
      "actor": "admin@acme.com",
      "targetUser": "contractor@acme.com",
      "reason": "Contract ended"
    },
    {
      "eventType": "USER_RECOVER",
      "timestamp": "2026-01-08T14:15:00Z",
      "actor": "admin@acme.com",
      "targetUser": "returning-employee@acme.com",
      "reason": "Rehire"
    }
  ],
  "period": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-09T23:59:59Z"
  }
}

Control mapping:

CC6.6: User access is removed when no longer authorized

Pass criteria:

✅ Suspended users exist (shows active lifecycle management)
✅ Deletions happen after appropriate retention period
✅ All actions have documented actors
✅ No unexplained recoveries

Remediation if failing:

Implement offboarding process:
- Suspend user immediately upon termination
- Transfer data ownership
- Delete user after retention period (30-90 days)
Document all lifecycle actions
Regularly audit suspended accounts

Domain Security (`domain_security.json`)

Purpose: Verify domain-wide security settings

Sample artifact:

{
  "allowExternalSharing": false,
  "allowPublicSharing": false,
  "passwordMinimumLength": 12,
  "passwordRequireSymbol": true,
  "passwordRequireNumber": true,
  "passwordRequireLowercase": true,
  "passwordRequireUppercase": true,
  "sessionDuration": 14400,
  "idleTimeout": 3600
}

Control mapping:

CC6.1: Password complexity and session management

Pass criteria:

✅ passwordMinimumLength ≥ 12
✅ All password complexity requirements enabled
✅ sessionDuration ≤ 24 hours
✅ External sharing restricted appropriately

Required Scopes

Domain-Wide Delegation Scopes

Add these OAuth scopes when setting up domain-wide delegation:

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

Scope descriptions:

admin.directory.user.readonly - Read user information, suspensions
admin.directory.rolemanagement.readonly - Read admin role assignments
admin.reports.audit.readonly - Read audit logs for user lifecycle events

Never use:

❌ admin.directory.user (write access)
❌ admin.directory.rolemanagement (write access)
❌ Read-write scopes

Environment Variables

Standard Configuration

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

File permissions:

chmod 600 /path/to/service-account.json
chown $USER:$USER /path/to/service-account.json

CI/CD Secrets

GitHub Actions:

- name: Set up service account
  run: |
    echo '${{ secrets.GOOGLE_SERVICE_ACCOUNT_JSON }}' > /tmp/sa.json
    export GOOGLE_APPLICATION_CREDENTIALS=/tmp/sa.json

GitLab CI:

before_script:
  - echo "$GOOGLE_SERVICE_ACCOUNT_JSON" > /tmp/sa.json
  - export GOOGLE_APPLICATION_CREDENTIALS=/tmp/sa.json

Customer ID

Find Your Customer ID

Go to Google Admin Console
Click "Account" → "Account settings"
Look for "Customer ID"
Format: C0xxxxxxx (9 characters)

Example: C01234567

Collection Process

Step 1: Authenticate with Service Account

Authenticating with Google Workspace...
  → Service account: evidence-collector@project.iam.gserviceaccount.com
  → Impersonating: admin@acme.com
  ✓ Domain-wide delegation authorized
  ✓ Customer ID: C01234567

Step 2: Fetch 2SV Enforcement

Fetching 2-Step Verification settings...
  → Admin SDK: Security Settings
  ✓ 2SV enforcement: enabled
  ✓ Enforcement date: 2025-06-01
  ✓ Reminders enabled

Step 3: Fetch Admin Roles

Fetching admin role assignments...
  → Admin SDK: Directory - Roles
  ✓ Found 5 roles
  ✓ Super Admin: 2 users
  ✓ User Management Admin: 1 user
  ✓ Groups Admin: 1 user
  ✓ Help Desk Admin: 3 users

Step 4: Fetch User Lifecycle Events

Fetching user lifecycle events (last 90 days)...
  → Admin SDK: Reports - Audit
  ✓ Suspensions: 3
  ✓ Deletions: 1
  ✓ Recoveries: 0

✓ Collection complete (4 artifacts)

Common Patterns

Basic Configuration

sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C01234567
    admin_email: admin@acme.com

Use case: Single domain, standard setup

Multi-Domain Organization

sources:
  google_workspace:
    mode: service_account
    credentials_env: GOOGLE_APPLICATION_CREDENTIALS
    customer_id: C01234567
    admin_email: admin@acme.com
    domains:
      - acme.com
      - subsidiary.acme.com
      - vendor.acme.com

Use case: Organizations with multiple domains under one customer ID

Troubleshooting

Authentication Failed

Symptom:

✗ Google Workspace connector failed

Error: Invalid service account credentials (HTTP 401)

Causes:

Service account JSON file invalid
File path incorrect
File permissions denied

Solutions:

Verify file exists:
```
ls -l $GOOGLE_APPLICATION_CREDENTIALS
```

Check file format:

cat $GOOGLE_APPLICATION_CREDENTIALS | jq .type
# Should output: "service_account"

Test credentials:

gcloud auth activate-service-account \
  --key-file=$GOOGLE_APPLICATION_CREDENTIALS

Domain-Wide Delegation Not Authorized

Symptom:

✗ Google Workspace connector failed

Error: Not Authorized to access this resource/api (HTTP 403)

Domain-wide delegation may not be enabled.

Causes:

Domain-wide delegation not set up
OAuth scopes not authorized
Wrong client ID used

Solutions:

Get Client ID from service account:

cat $GOOGLE_APPLICATION_CREDENTIALS | jq -r .client_id

Verify delegation in Admin Console:
- Go to Security → API controls → Domain-wide Delegation
- Search for client ID
- Verify scopes are correct

Re-authorize with correct scopes:

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

Invalid Customer ID

Symptom:

✗ Google Workspace connector failed

Error: Invalid customer ID 'C0xxxxxxx'

Causes:

Customer ID incorrect
Customer ID format wrong
Service account doesn't have access to customer

Solutions:

Find correct customer ID:
- Go to Admin Console → Account → Account settings
- Copy Customer ID (format: C01234567)
Verify format:
- Must start with C
- Followed by 8 digits
- Total 9 characters
Check service account access:
- Service account must be in same organization
- Or organization must allow external service accounts

Admin Email Not Found

Symptom:

✗ Google Workspace connector failed

Error: User 'admin@acme.com' not found or not an admin

Causes:

Admin email incorrect
User not an admin
User suspended

Solutions:

Verify admin email:
- Must be a super admin or have appropriate admin role
- Check spelling carefully
Check user status:
- Go to Admin Console → Directory → Users
- Search for user
- Verify user is active and has admin privileges
Use correct admin:
- Must have privileges for all required scopes
- Recommended: Use dedicated service admin account

Insufficient Permissions

Symptom:

✗ Google Workspace connector failed

Error: Insufficient permissions for this operation (HTTP 403)

Required scope: admin.directory.user.readonly

Causes:

OAuth scopes not complete
Scopes not authorized in delegation

Solutions:

Check authorized scopes:
- Go to Admin Console → Security → API controls
- Find domain-wide delegation entry
- Verify all three required scopes are listed
Add missing scopes:
- Edit delegation entry
- Add missing scopes
- Click "Authorize"
Wait for propagation:
- Changes may take 5-10 minutes to propagate
- Retry collection after waiting