Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Google Chat Connector

The Google Chat connector provides bidirectional, real-time message routing between corporate Google Chat spaces and the cognitive assistant runtime.

1. Flow Architecture

graph TD
    subgraph GoogleWorkspace [Google Workspace Perimeter]
        User[Corporate User]
        ChatAPI[Google Chat App: Bot Identity]
    end

    subgraph GoogleCloud [Customer Dedicated Google Cloud Project]
        Topic[Pub/Sub Topic: chat-events-topic]
        Sub[Pub/Sub Subscription: chat-events-sub]

        subgraph VMRuntime [Compute Engine Private VM]
            Assistant[Org Assistant Runtime]
        end
    end

    User -->|Sends @mention / Direct Message| ChatAPI
    ChatAPI -->|Pub/Sub Push Event| Topic
    Topic --> Sub
    Sub -->|Pull Stream: Long-Polling| Assistant
    Assistant -->|REST API: chat.bot Scope| ChatAPI
  1. Inbound Webhook Delivery: When a user interacts with the bot via direct message or @mention in a space, Google Chat delivers the event payload to an encrypted Pub/Sub topic (chat-events-topic).
  2. Asynchronous Pull Ingestion: The assistant daemon running on the private VM pulls message events from chat-events-sub over an outbound TLS connection. The VM exposes no inbound open ports.
  3. Outbound Response Dispatch: The assistant formats structured messages or interactive cards and posts responses back to Google Chat using the Google Chat REST API.

2. Identity & Privilege Boundaries

  • Dedicated Service Account: The Chat connector uses the dedicated identity org-assistant@<project_id>.iam.gserviceaccount.com.
  • Minimal OAuth Scopes: The bot identity requests strictly the following scope:
    • https://www.googleapis.com/auth/chat.bot (Permits posting messages as the bot in spaces where invited).
  • Scope Quarantine: The service account holds no access to user mailboxes (gmail.*), Google Drive documents (drive.*), or Workspace administrative settings. It cannot impersonate domain users.

3. Threat Model & Mitigations

Threat VectorAttack PathSecurity Mitigation
Untrusted Input ParsingMalicious formatted JSON or exploit payloads sent in chat messages.Strongly typed deserialization in Rust via serde. Memory-safe buffer management with no raw pointer dereferencing.
Prompt InjectionMalicious prompt instructions designed to override agent directives.Strict prompt compartmentalization separating user input from system instructions; deterministic tool call validation.
Message SpoofingAdversary attempts to push fake chat events to Pub/Sub.Pub/Sub topic enforces IAM policy: only Google Chat service agent (chat-api-push@system.gserviceaccount.com) has publish permissions (roles/pubsub.publisher).
Service Account AbuseCompromised container uses ambient token to access other services.Scope is locked to chat.bot. The token cannot access internal emails, employee documents, or project infrastructure.