Google Connector

• 1: Gmail Connector Setup
• 2: Google Chat Connector Setup
• 3: Google Drive Connector Setup
• 4: Google Sites Connector Setup

https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/drive.activity.readonly

connectors:
  google:
    default:
      enabled: true

export JWT_TOKEN=$(atolioctl connector create-jwt --raw --config-dir . "atolio:*:*:*")

# Run K8s port forward to feeder as background to re-use same shell
kubectl port-forward -n atolio-svc service/feeder 8889 &

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

connectors:
  # ...existing connectors left in place...
  google:
    default:
      google:
        connector: google
        instance: default
        source: google
        common:
          enabled: true
          identity-provider: true      # This connector is the identity provider
          cron-spec: 0 7 * * *         # Re-sync users on this schedule
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

1 - Gmail Connector Setup

Installing the Gmail Connector

Note: For this step, your deployment engineer will be required.

The Gmail and Google Drive connectors depend on a shared Google Workspace configuration section. Google Workspace requires three properties to be set during configuration:

• ProjectID must reference the project created in GCP. The id, not the name, must be specified.
• ServiceUser is currently a reference to a super user or administrator within your organization. For example, the primary IT email. This may change in the future.
• ServiceAccountKey is the base64-encoded string as obtained during initial install of the Google source.

To obtain the service account key, your deployment engineer will run the following Terraform command:

terraform output -raw google_connector_service_account_key

And optionally:

• Domains is a comma-delimited list of domains applicable to this deployment.
• Parallelism is an optimization to increase the concurrency with respect to indexing Google data. Default is 32, so if set, should be higher than this value.

Once the Google source is configured, the Google Drive and Gmail sources can be configured with the same values.

Configuration

Source configuration can be applied in two ways:

Recommended (v4.24+): Use the Admin console to configure this source through the browser. You can paste the YAML configuration shown below directly into the Admin console.

Alternative: Use atolioctl via the command line (for Deployment Engineers). If using atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gdrive:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gmail
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          drive-contrib-hydration-method: activity
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Gmail source sits at connectors.google.default.gmail.

GmailSourceConfiguration

Gmail connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GmailConfiguration

Gmail-specific connector configuration.

2 - Google Chat Connector Setup

Installing the Google Chat Connector

Note: For this step, your deployment engineer will be required.

The Google Chat connector depends on the same Google Workspace configuration section as the Gmail and Google Drive connectors, so ProjectID, ServiceUser, and ServiceAccountKey carry the same values described in the Google connector setup.

Prerequisites

Enable the Required APIs

The GCP project referenced by project-id must have these APIs enabled:

• Google Chat API (chat.googleapis.com)
• Google Workspace Events API (workspaceevents.googleapis.com)
• Cloud Pub/Sub API (pubsub.googleapis.com)

The Atolio Terraform module enables them for you. If the project is managed by hand, enable them from the API Library.

Configure the Chat App

Google requires every project that calls Chat API to have a Chat app configured, manually by an admin.

Open the Google Chat API configuration page and complete the form:

Leave the remaining fields at their defaults and save.

Grant the Chat Scopes

You will need a Service Account as described in Grant Service Account Permissions. In addition to the scopes listed there, the domain-wide delegation entry must carry the following scopes:

https://www.googleapis.com/auth/chat.spaces.readonly
https://www.googleapis.com/auth/chat.messages.readonly
https://www.googleapis.com/auth/chat.memberships.readonly

To add them, open the Google Admin console at https://admin.google.com/ac/owl/domainwidedelegation, edit the existing entry for the Atolio service account client ID, append the three scopes to the list already there, and authorize. Removing a scope that is already in the list will break the Gmail, Drive, or Sites sources.

Create the Pub/Sub Topic and Subscription

To support the indexing of Google Chat messages in real-time (streaming), a Pub/Sub topic is needed.

The Atolio Terraform module creates both, along with the two role bindings. If you are provisioning by hand, make sure to keep the name and bindings as listed above.

Streaming is the only part of the connector that needs Pub/Sub. If you set skip-streaming to true, the topic and subscription are not required, and the connector indexes only what it finds on each backfill.

Configuration

Source configuration can be applied in two ways:

Recommended (v4.24+): Use the Admin console to configure this source through the browser. You can paste the YAML configuration shown below directly into the Admin console.

Alternative: Use atolioctl via the command line (for Deployment Engineers). If using atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address of the feeder server’s gRPC endpoint.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google Chat entry alongside the Google sub-connectors already in the file, using the same values you provided for the Google source:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gchat:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gchat
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Limiting the Backfill Window

By default, backfill reads messages created in the last five years. Narrow that with backfill-start-time, which is useful on a large Workspace where the first pass would otherwise run for a long time against Chat’s per-project read quota:

        configuration:
          backfill-start-time: "2026-01-01T00:00:00Z"

Both bounds are RFC 3339 timestamps. backfill-end-time is unbounded when unset, and is mostly useful for pinning a reproducible window.

Backfill resumes from where it left off. Each space records the point its messages were read up to, so an interrupted or repeated pass reads only what is new rather than starting over.

Discoverable Spaces and Target Audiences

A Google Chat space can be made discoverable to a target audience, which is a group of people your Workspace administrator defines. Anyone in that audience can find the space and read its messages without being a member, and Atolio has to reflect that in its permissions.

Set audiences to map each audience to the groups and users it grants access to, keyed by the audience resource name:

        configuration:
          audiences:
            audiences/00zu0gcz154hwnv:
              - engineering@example.com
              - all-contractors@example.com
              - jane.doe@example.com

To turn an audience id into the list of members, ask your Workspace administrator. Target audiences are managed in the Admin console under Directory > Target audiences, where each audience lists the groups and individuals it contains.

This section is only relevant if your organization uses discoverable spaces. Spaces restricted to their members need no audiences configuration.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Google Chat source sits at connectors.google.default.gchat.

GoogleChatSourceConfiguration

Google Chat connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GChatConfiguration

Google Chat-specific connector configuration.

3 - Google Drive Connector Setup

Installing the Google Drive Connector

Note: For this step, your deployment engineer will be required.

The Gmail and Google Drive connectors depend on a shared Google Workspace configuration section. Google Workspace requires three properties to be set during configuration:

• ProjectID must reference the project created in GCP. The id, not the name, must be specified.
• ServiceUser is currently a reference to a super user or administrator within your organization. For example, the primary IT email. This may change in the future.
• ServiceAccountKey is the base64-encoded string as obtained during initial install of the Google source.

To obtain the service account key, your deployment engineer will run the following Terraform command:

terraform output -raw google_connector_service_account_key

And optionally:

• Domains is a comma-delimited list of domains applicable to this deployment.
• Parallelism is an optimization to increase the concurrency with respect to indexing Google data. Default is 32, so if set, should be higher than this value.

Once the Google source is configured, the Google Drive and Gmail sources can be configured with the same values.

Configuration

Source configuration can be applied in two ways:

Recommended (v4.24+): Use the Admin console to configure this source through the browser. You can paste the YAML configuration shown below directly into the Admin console.

Alternative: Use atolioctl via the command line (for Deployment Engineers). If using atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gdrive:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gdrive
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          parallelism: 0
          drive-contrib-hydration-method: activity
          project-id: "<GOOGLE_PROJECT_ID>"
          service-user: "<GOOGLE_SERVICE_USER>"

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Google Drive source sits at connectors.google.default.gdrive.

GoogleDriveSourceConfiguration

Google Drive connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GDriveConfiguration

Google Drive-specific connector configuration.

4 - Google Sites Connector Setup

Installing the Google Sites Connector

Note: For this step, your deployment engineer will be required.

Prerequisites

Google Sites Connector requires you to enable Google Vault for your organization. Google Vault enrollment details are available in the official documentation

You will need a Service Account as described in Grant Service Account Permissions section. In addition to the scopes listed there, you must grant the following scopes to the Service Account:

- https://www.googleapis.com/auth/ediscovery
- https://www.googleapis.com/auth/devstorage.read_only

Vault API access must be manually enabled by the GCP project associated with the Service Account. This can be done via GCP API Console, by following the steps in the official documentation.

Configuration

Source configuration can be applied in two ways:

Recommended (v4.24+): Use the Admin console to configure this source through the browser. You can paste the YAML configuration shown below directly into the Admin console.

Alternative: Use atolioctl via the command line (for Deployment Engineers). If using atolioctl, follow Configuring Sources first. The commands below also need an API token in JWT_TOKEN and the address the feeder server’s gRPC endpoint, both described next.

Edit and Apply the Configuration

Source configuration is stored as a single document that covers every configured connector. The supported workflow is to export the current configuration, edit it, then import it back. Always start from a fresh export so you do not overwrite a change made elsewhere.

Export the current configuration to a local file:

atolioctl configure export --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889 lumen-connectors.yaml

Add a Google entry alongside the connectors already in the file, substituting the values you collected in Step 1:

connectors:
  # ...existing connectors left in place...
  google:
    default:
      # ...existing Google sub-connectors left in place...
      gsites:
        connector: google              # Reference to parent connector, usually Google
        instance: default
        source: gsites
        common:
          enabled: true
          identity-provider: false     # This connector is a workspace tool, not IDP
        secrets:
          service_account_key:
            value: "<GOOGLE_SERVICE_ACCOUNT_B64>"
        configuration:
          service-user: "<GOOGLE_SERVICE_USER>"
          site-urls:
            - https://sites.google.com/your-org/your-site
          site-configs:
            https://sites.google.com/your-org/your-site
              # If you have a custom domain for your Google Site, specify it here.
              top-level-url: https://your-custom-domain.com/path

              # If you want to configure deeplinks for each page, 
              # you can do it by providing a "page name" -> "URL suffix" map here.
              # 
              # For a page titled "Home", the deeplink would be:
              # https://your-custom-domain.com/path/home
              page-name-to-url-suffix:
                Home: /home
                About: /about
              
              # If you have setup "Restricted" access for your site, specify it here. 
              # Default is `false`.
              restricted: true

If you do not prefer to have a static configuration for deeplinks, you can also provide a “url path” on each Google Site page. Simply add a text in the form of urlpath:[/relative-path-to-your-page] in the body of each page, and Atolio will index the page with the user-provided deeplink.

Exported entries also carry a rendezvous-completed flag and a status block reporting each source’s current state and last validation result. Those fields are managed by Atolio. Leave them untouched on existing entries, and omit them when adding a new entry by hand as shown above.

Import the edited file to write the configuration back into the stack:

atolioctl configure import lumen-connectors.yaml --jwt-token-sdk ${JWT_TOKEN} --feeder-address :8889

Import writes the configuration into the stack after checking that the YAML is well formed. It does not contact Google. The connector validates the credentials and connection itself when it starts and picks up the configuration, and it reads users after that. If something is wrong, the source reports as misconfigured and the connector pod logs the error. See Troubleshooting for the specific messages.

Configuration Schema

In the exported file, every source lives at connectors.<connector>.<instance>.<source>, so the Google Sites source sits at connectors.google.default.gsites.

GoogleSitesSourceConfiguration

Google Sites connector configuration.

Common

Common settings shared across all connectors.

Secrets

Sensitive configuration values for authentication.

SecretValue

A reference to a secret value.

GSitesConfiguration

Google Sites-specific connector configuration.

SiteConfig

Per-site configuration for Google Sites.