Egress Google Workspace

Responsibility

Executes Google API interactions for workflow connector steps:

• Gmail (gmail_list_messages, gmail_read_message, gmail_send, gmail_reply)
• Calendar (calendar_list_events, calendar_create_event, calendar_update_event, calendar_free_busy)
• Drive (drive_list_files, drive_upload_file, drive_download_file, drive_create_share_link)

Inbound Authentication

• internal-only service, called by orchestrator
• trust boundary: cluster-internal network

Outbound Authentication (Google)

Auth is service-account based (OAuth 2.0 JWT bearer grant):

1. Orchestrator sends service_account_key, impersonate_user, and scopes to this service.
2. Service signs JWT with the service-account private key.
3. Service exchanges JWT at Google token endpoint for access token.
4. Token is cached in-process per (client_email, scopes, impersonate_user).
5. API requests use Authorization: Bearer <access_token>.

Connection Model

Use google_workspace connection type:

name: google-workspace-calendar
type: google_workspace
service_account_key: "$secret:google-workspace-sa-key"
impersonate_user: "workflow-runner@example.com"  # optional
scopes:
  - https://www.googleapis.com/auth/calendar

Secrets Guidance

• Store full service-account JSON in runtime secrets.
• Reference via $secret:<name> in connection YAML.
• Avoid inline private keys in Git-managed files.

Required IAM / Workspace Setup

• Create Google Cloud service account with required API access.
• Enable target APIs (Gmail, Calendar, Drive) in project.
• If acting as domain user, configure domain-wide delegation and set impersonate_user.
• Grant least-privilege scopes per connection.

Key Config

• Orchestrator env: EGRESS_GOOGLE_WORKSPACE_URL=http://egress-google-workspace:8080
• Service image: meshflows/egress-google-workspace

Health

• GET /healthz
• GET /readyz