Skip to main content
Audience: Platform operators / on-call engineers. Scope: Gmail sending only (WS4). Directory, Calendar, Licensing, and Reports onboard through the standard Admin Setup flow. Related: Overview · Compliance · Security Review

​
How sender resolution works during migration

The email adapter (supabase/functions/_shared/email-provider.ts) resolves Gmail credentials PF-101 first, legacy second:
  1. If the tenant has an active pf_google_workspace_connections row with the gmail capability enabled, the adapter uses the PF-76 vault credential referenced by that connection (credential_vault_ref) and enforces the PF-101 gates — sender-domain allowlist (connection primary_domain) and the fail-closed BAA gate for PHI-capable sends (baa_attested_at IS NOT NULL).
  2. Otherwise it falls back to the platform-wide GMAIL_SERVICE_ACCOUNT_JSON edge-function secret (legacy path, shared across all tenants).
Because resolution is per-tenant, migration is incremental: tenants move one at a time, and the legacy secret stays in place until every tenant has passed its smoke test.

​
Per-tenant migration steps

  1. Connect the tenant. Follow Admin Setup §1–2: service account with DWD, scopes authorized in the tenant’s Admin Console, JSON key stored via the PF-76 vault (pf_store_credential) from Settings → Integrations → Google Workspace.
  2. Enable the gmail capability on the connection. If the tenant sends PHI-capable mail, record the BAA attestation first — the gate is fail-closed and unattested PHI sends are rejected with a policy error.
  3. Verify sender identity. The configured sender must match the connection’s primary_domain (sender allowlist). Update the org’s gmail_sender_email setting if it still points at the shared legacy sender.
  4. Run the connection test (Settings → Integrations → Google Workspace → Test connection). The gmail capability must report healthy; a pf_google_workspace_sync_runs row records the result.
  5. Smoke test (gating). Send a non-PHI test message through the platform (e.g. a password-reset or test notification to an operator mailbox) and confirm:
    • the message arrives from the tenant’s domain sender;
    • a pf_google_workspace_sync_runs row with capability gmail and a redacted correlation_id was written;
    • edge-function logs show no Gmail service account not configured or scope errors (supabase functions logs email-send).
  6. Record completion. Note the tenant + date in the cutover tracker before moving to the next tenant.

​
Legacy secret retirement

Only after all tenants have an active PF-101 Gmail connection and a passed smoke test:
  1. Confirm no fallback hits remain: search edge logs for the legacy-path warning over a full business cycle (7 days minimum).
  2. Remove the platform secret: supabase secrets unset GMAIL_SERVICE_ACCOUNT_JSON.
  3. Revoke the legacy shared service account’s DWD grant in the Google Admin Console and delete its key.
  4. Update EMAIL_SMS_SETUP and EDGE_FUNCTIONS to drop the GMAIL_SERVICE_ACCOUNT_JSON instructions (they document the legacy path while it remains supported).

​
Rollback

A tenant can be rolled back instantly by disabling the gmail capability on its connection — the adapter falls back to the legacy secret (while it still exists). Do not retire the legacy secret until the rollback window has closed for every tenant.

​
Current status

  • Adapter precedence, BAA gate, and sender allowlist are implemented and contract-tested (WS4 T4.1–T4.4).
  • Live per-tenant smoke tests are pending the BAA staging tenant (tracked in GOOGLE_WORKSPACE_SECURITY_REVIEW.md §8); no tenant has been migrated yet, and the legacy secret remains active.