> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Integration (PF-101) — Admin Setup

> Audience: Tenant admins / platform operators connecting a Google Workspace tenant. Permissions required: pf.google_workspace.manage and org_admin system role.…

**Audience:** Tenant admins / platform operators connecting a Google Workspace tenant.
**Permissions required:** `pf.google_workspace.manage` and `org_admin` system role.
**Pre-reqs:** Signed Google Workspace BAA (Business Associate Agreement) for any PHI-capable capability.

## 1. Provision the Google service account

1. In Google Cloud Console, create a project for the EncoreOS connector.
2. Enable APIs: **Admin SDK**, **Gmail**, **Calendar**, **Drive**, **Chat**, **Licensing**, **Reports**.
3. Create a service account; download the JSON private key.
4. In **Workspace Admin Console → Security → API controls → Domain-wide Delegation**, authorize the service account's client ID with the **least-privilege scopes** for the capabilities you intend to enable. The exact scope list per capability is in `CAPABILITY_SCOPES` inside `supabase/functions/_shared/google-workspace-client.ts`.
5. Designate a Workspace **delegated subject** (a real super-admin email) — DWD impersonates this user for all admin reads/writes.

## 2. Store credentials in PF-76 Credential Vault

Never paste the JSON key into Supabase env, table columns, or chat. Use the credential vault wrapper:

1. In Settings → Integrations → Google Workspace, click **"Connect"**.
2. Paste the service account JSON; the UI hands it directly to the `pf_store_credential` RPC.
3. The connection row in `pf_google_workspace_connections` only stores `credential_vault_ref` (an opaque ID).

## 3. Capability flags

On the connection row, enable only the capabilities the tenant actually needs:

| Column                         | Capability                      | PHI-capable                  |
| ------------------------------ | ------------------------------- | ---------------------------- |
| `capability_directory_enabled` | User provisioning / suspend     | No                           |
| `capability_gmail_enabled`     | Outbound email send             | **Yes**                      |
| `capability_calendar_enabled`  | Calendar events / Meet links    | **Yes**                      |
| `capability_drive_enabled`     | Drive metadata / mappings       | **Yes**                      |
| `capability_chat_enabled`      | Chat notifications              | **Yes (PHI blocked in MVP)** |
| `capability_licensing_enabled` | License Manager assign / revoke | No                           |
| `capability_reports_enabled`   | Audit Reports ingestion         | No                           |

## 4. BAA attestation (required before PHI-capable use)

After signing the Google Workspace BAA:

1. Org admin opens **Settings → Integrations → Google Workspace → Compliance**.
2. Records BAA reference (Google contract ID), attesting user, and date.
3. Backend writes `baa_attested_at` and `baa_attested_by` on the connection.

Until both BAA attestation **and** the capability flag are set, all Gmail / Calendar / Drive / Chat operations fail closed.

## 5. Test the connection

Call the per-capability health check from the UI ("Test connection") or directly:

```bash theme={null}
curl -X POST "$SUPABASE_URL/functions/v1/google-workspace-test-connection" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"connection_id":"<uuid>"}'
```

The response lists pass/fail per capability. Failures include a sanitized `reason_code` (e.g., `scope_missing`, `baa_required`, `domain_mismatch`) — never raw Google error bodies.

## 6. Migrate from legacy Gmail (`GMAIL_SERVICE_ACCOUNT_JSON`)

The shared `email-provider.ts` adapter prefers a PF-101 connection when one exists for the tenant; otherwise it falls back to the legacy env var. Per-tenant migration:

1. Connect Workspace + attest BAA + enable Gmail capability (steps 1–4).
2. Send a test email through any platform notification flow.
3. Once smoke-tested, the platform team can remove the tenant's reliance on `GMAIL_SERVICE_ACCOUNT_JSON`. Do **not** delete the env until every tenant has migrated.

## 7. Operations & monitoring

* **Sync runs:** every provision / offboard / reconcile / Reports pull writes a row to `pf_google_workspace_sync_runs`. Filter by `status = 'failed'` for triage.
* **Directory reconcile:** scheduled cron compares HR employees vs Workspace suspended state and records drift.
* **Audit:** Reports ingestion writes hashed-actor rows to `pf_audit_log` for HIPAA audit trail.

## 8. Troubleshooting

| Symptom                  | Likely cause                                   | Fix                                                                          |
| ------------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------- |
| `baa_required`           | Capability is PHI-capable but BAA not attested | Complete §4                                                                  |
| `scope_missing`          | DWD authorization missing for capability scope | Re-authorize service account in Workspace Admin Console with required scopes |
| `domain_mismatch`        | Gmail sender domain ≠ `primary_domain`         | Use a sender on the connected domain                                         |
| `credential_unavailable` | PF-76 vault ref invalid / rotated              | Reconnect the service account JSON                                           |