Setting up Google

You create one OAuth application in your Google Cloud project. Members then connect their own accounts against it, and the assistant acts with each member's own permissions.

This page is the setup walkthrough. Connectors covers the policy questions worth deciding first, and Setting up Microsoft is the equivalent for Microsoft 365.

Guided setup in Google Cloud ShellCopy Anchor Link

Use your Google Workspace account, with access to a Cloud project inside your Workspace organization. A Cloud administrator must grant you permission to enable APIs (roles/serviceusage.serviceUsageAdmin) and manage OAuth configuration (roles/oauthconfig.editor). Creating a project also requires Project Creator on its organization. Workspace app-access policy is separate: a Workspace administrator may need to approve your OAuth client in Security > Access and data control > API controls.

Download the setup script, or open Google Cloud Shell and run:

curl -fsSLo setup-google-connector.py \
  https://docs.asteria-labs.com/scripts/setup-google-connector.py
python3 setup-google-connector.py

Enter the project ID, not its display name. Press Enter to prepare all services, including Directory for group access to shared files. Keep Directory in a smaller selection too, for example drive,gmail,calendar,directory. Review the signed-in account, project and API list before approving. The script enables APIs and verifies they are enabled; the default OAuth setup does not attach billing, grant IAM roles or create service-account keys. Selecting any document-editing service also enables Docs, Sheets, Slides and Drive because those services share one permission.

To create a new project inside your organization instead, choose a globally unique project ID and replace the example organization number:

python3 setup-google-connector.py --project YOUR-PROJECT-ID \
  --create-project --organization YOUR-ORGANIZATION-NUMBER

Find the numeric organization ID in the Cloud Console project selector. If your organization requires projects in a particular folder, ask your Cloud administrator to create the project there first, then use the existing-project flow. If project creation or API enablement is denied, ask that administrator to resolve the reported IAM, quota or billing requirement; the script does not change these policies. Rerun a partially completed setup with the same --project and services, without --create-project if the project already exists.

Optional: Workspace Events Pub/SubCopy Anchor Link

For Workspace Events, rerun the script with the same OAuth project and the exact Workspace Events callback copied from the Google connector settings. This is different from the OAuth redirect URI.

python3 setup-google-connector.py --project YOUR-PROJECT-ID --services drive \
  --workspace-events-callback 'https://YOUR-APP-HOST/api/connectors/google/workspace-events/YOUR-ORGANIZATION-UUID'

This option provisions an authenticated push subscription, topics, a push service account and dead-letter handling. It looks up the project number and prints the configuration to copy into Asteria Cloud. Review the displayed resource-scoped IAM grants, seven-day retention and retry settings before confirming. Reruns reuse matching resources and refuse conflicting subscriptions; --verify-only checks resources and IAM without writes. Existing topic storage policies remain unchanged. The operator needs Pub/Sub and service-account management permissions, IAM policy permissions and iam.serviceAccounts.actAs. Developer Preview enrollment and real delivery still require validation; provisioning does not expose a new workflow trigger.

Complete the console stepsCopy Anchor Link

The script prints links already scoped to your project and the full scope names to copy. Keep its output open and follow these steps:

1. Google Auth platform > Branding: choose Get started if prompted. Enter Asteria Cloud connector and your own support/contact email addresses. Finish App information and App domain with the branding values below, then save.
2. Audience: select Internal for members of your Workspace. If Internal is missing, check that the project belongs to your Workspace organization. Do not choose External just to get past this screen; read the consent-screen section below first.
3. Data Access > Add or remove scopes: add the exact scopes printed by the script. The list includes identity scopes and the selected services. Save.
4. Clients > Create client > Web application: use the name Asteria Cloud connector and paste the printed callback into Authorized redirect URIs. The production value is https://app.asteria-labs.com/api/connectors/callback. No JavaScript origin is required. For another deployment, start the script with --redirect-uri and its exact HTTPS callback.
5. Copy the client ID and client secret immediately into your secret manager. If Google offers a client JSON download, keep it securely. Never use a desktop client, API key or service-account JSON in the connector form.
6. For Chat, also open the script's Chat API configuration link, set the app name, avatar URL and description, and save. Reading uses user OAuth; sending messages and creating spaces additionally require this Chat app configuration. Use a dedicated connector project, turn Interactive features off, and save; do not change an existing interactive Chat app. Ask for Chat apps Owner access if this page is unavailable. For the avatar URL, paste https://app.asteria-labs.com/pwa-512x512.png. This configures access as the connected user; it does not install a bot in Google Chat. Test it from Asteria Cloud as described below. See Google’s Chat configuration guide.
7. As an organization administrator, open Connectors in the Asteria Cloud admin console > Google, save the client ID and client secret, then enable Google Workspace. For incoming-mail workflows, complete the Gmail Pub/Sub steps below as well. The organization registration takes precedence over the platform application for new connections.

If you downloaded the Web client JSON, upload it into Cloud Shell and check it without modifying the project:

python3 setup-google-connector.py --project YOUR-PROJECT-ID \
  --verify-only --credentials ./client.json

The example above verifies the default all-services setup and production callback. If you customized the first run, repeat the same --services and --redirect-uri options on this command; verification must check the same plan. This checks API availability and the JSON's project, client type and callback, then prints the values for the admin console. It cannot prove the secret is still valid or that the audience and Workspace policy allow your members. Remove the downloaded JSON and its Cloud Shell copy after saving the credentials securely. Without a JSON file, --verify-only still checks the APIs and prints the remaining steps.

The final test is a real connection. In Profile > Connections, connect a pilot Workspace account, select the intended services and complete consent. Read a known file, calendar or message before inviting everyone else. Keep Directory selected at consent and complete the group-access check below with another member who should have access. A client ID and secret alone cannot perform Google's authorization-code exchange; the pilot connection tests that exchange through Asteria Cloud's actual callback.

This walkthrough configures per-user OAuth. Domain-wide delegation is not accepted by the Google Workspace connector; BigQuery service accounts and Chat agent deployments are separate features. Never paste a service-account key into these OAuth fields.

Branding values for Google Auth platformCopy Anchor Link

In Branding > App information, upload the application logo: download this PNG and select the file in Google's upload field. The same image is the Chat avatar, where Google takes its URL instead of a file. These brand the OAuth application and Chat app, not the Cloud project's display name.

For the hosted Asteria Cloud service, fill App domain as follows:

The privacy policy and terms of use describe the hosted service. For a self-hosted deployment, use the operator's own applicable pages and logo. If Google requires domain-ownership verification for an External application, contact Asteria Labs about the hosted URLs; a customer cannot verify ownership of asteria-labs.com. Keep your own support and developer contact emails on the application.

Check group access during onboardingCopy Anchor Link

Directory is included by default in the script. It prepares the Admin SDK and Cloud Identity APIs and prints both Directory scopes. Members must also include Directory when connecting in Profile > Connections; preparing the Cloud project does not grant user consent. If an existing connection lacks it, use Grant more access.

Test a mirrored Drive collection with a file shared only through a Google group and a second member of that group. Nested groups resolve where the member's rights and Workspace edition allow Cloud Identity lookup. For the direct-group fallback, a Workspace administrator or Groups Reader must connect their own account with Directory, then select that connection under Directory account for collection access in the admin console's Connectors page. OAuth scopes alone do not grant directory privileges. Without a successful group check, group-only files remain hidden.

Gmail workflows: topic and push subscriptionCopy Anchor Link

The script enables Gmail API access but does not create Pub/Sub resources. The Gmail Pub/Sub topic field in the admin console is needed for incoming-mail workflow triggers; ordinary Gmail reading and sending work without it.

Follow Workflows that trigger on incoming mail before testing a Gmail trigger. In the same Cloud project as the OAuth client, enable the Pub/Sub API, create the topic, grant Google's Gmail publisher access, and save the full topic name (for example projects/your-project/topics/asteria-gmail) in Admin console > Connectors > Google > Update the application. Then copy the Gmail push endpoint shown on the Google card and create a push subscription on that topic using the full endpoint. The linked procedure covers the publisher principal and Domain Restricted Sharing.

To test, connect Gmail as the workflow owner, create and enable an incoming-mail workflow, then send a new message matching its filter and check its run history. A saved topic alone does not establish the mailbox watch; enabling the trigger does. Without the push subscription, the fallback check runs every 20 minutes.

Test Chat access from Asteria CloudCopy Anchor Link

With Interactive features off, there is no bot to add or message in Google Chat. Connect your Google account in Profile > Connections with Chat selected. In Asteria Cloud, ask Asteria to list your Chat spaces, read a known thread, then send a short test message to a test space after confirming the destination. Check Google Chat: the message is sent as your connected account. Sending and creating spaces require the Chat API configuration from step 6.

Let an agent reply inside Google ChatCopy Anchor Link

Asteria Cloud also supports a separate project-owned custom agent deployment. Use this when people should address an app in Chat. It runs with the project's service identity, not each participant's personal Google grant. Its history contains the messages delivered to the bot and its replies in that thread, not every message in the space. Replies are visible in the originating conversation, so only expose an agent whose outputs are appropriate for its members.

1. Use a separate Google Cloud project for this interactive app; keep the connector project's interactive features off. Enable the Chat API and create a service account in the app's project. Create its JSON key if your organization's policy permits it; no domain-wide delegation is needed.
2. In Asteria Cloud Platform > Projects, open your project and Settings > Google Chat agent as a project administrator. Select an active custom agent owned by that project, enter the numeric Google Cloud project number, and paste the service-account JSON. Google Workspace must already be enabled in the admin console. Save and copy the deployment's HTTP endpoint URL.
3. In the app project's Google Chat API > Configuration, set the app name (for example Asteria), description and avatar URL https://app.asteria-labs.com/pwa-512x512.png. Enable Interactive features, allow joining spaces/group conversations, choose HTTP endpoint URL, paste the deployment endpoint and select Project number as the authentication audience.
4. Under Visibility, add your own Workspace email and the other pilot testers, then save. They must be allowed to install Chat apps by your Workspace policy. See Google's testing instructions.
5. Sign into Google Chat with that tester account. Choose New chat, search the app's configured name and open a direct message. Send a question. In a test space, select the app from the @ suggestions, add it when prompted, and send @Asteria followed by your question. Merely adding the app does not produce a welcome reply; send a message to test it.
6. For a slash-command pilot, add a command in Chat API > Configuration > Commands: type Slash command, name /asteria, an unused numeric ID such as 1, and description Ask the project agent a question. Leave Open a dialog off. Try /asteria followed by a question. Google's slash commands deliver message events to the existing handler; Asteria Cloud has no command-specific dispatch, and this path still needs a live pilot. Quick commands, dialogs and cards are not supported by this deployment. See Google's command configuration.

If the app is missing from search, check Visibility, the signed-in Workspace account and Workspace installation policy. If it is present but never replies, check that the deployment is enabled, its project-owned agent is active, and the endpoint and project-number audience match. Public Marketplace publication is not required for the listed pilot testers.

Consent screen: Internal or ExternalCopy Anchor Link

This is the decision that determines whether your rollout survives, so make it before creating anything.

Internal is the right answer if everyone who will connect is in your own Google Workspace. Connections last, and none of the verification below applies.

External means Google treats your application as public. Two consequences follow:

• While the screen is in Testing, Google expires every connection after seven days no matter how often it is used. Members reconnect weekly, blame the assistant, and stop using it.
• Moving it to production while requesting Gmail or full Drive access requires Google's verification and a third-party security assessment, renewed annually.

If your members are all in your Workspace, choose Internal.

The scopes each service usesCopy Anchor Link

You do not enter these anywhere in Asteria Cloud; we request them when a member connects, based on the services they select. They are listed so you can see what your members are approving, and add them to your consent screen's scope list.

Three things about this table are Google's design rather than ours, and members will ask about all three.

Docs, Sheets, Slides and Drive uploads share one scope. They are one permission with four names, so enabling any of them enables all four. There is no way to offer document editing without also allowing spreadsheet editing.

That shared scope is full Drive access, not just the documents being edited. Google only grants document commenting together with access to files generally, so editing one document means the application can reach the member's Drive. This is the scope that makes an External consent screen expensive.

Gmail and full Drive are both restricted scopes. On an Internal consent screen this costs nothing. On an External one it is the verification and assessment described above.