Connect Google Workspace

“Google” shows up in four places in Cengrid. Pick the one that matches what you want to do.

You want to	Use	Page
Let each person’s agent read and act on their own Gmail, Calendar, Tasks, Drive, Sheets, Docs and Slides	Google OAuth account connection	This page
Give a team a shared server-to-server identity for a Google API	Google service account connection	Below
Let people talk to Cengrid in Google Chat	The Google Chat platform	Connect Google Chat
Let people sign in to the web app with their Google account	OIDC sign-in	Sign in with Google

Personal accounts with Google OAuth

An administrator registers one OAuth client for the whole organisation. Each person then connects their own Google account from their Keychain. There is no shared OAuth account: everyone acts as themselves.

What people get

The agent can use Gmail (search, read, draft, reply and send, with approval for writes), Google Calendar, Google Tasks, Drive, Sheets, Docs and Slides. Writes ask for approval first. These come from the starter google-workspace and google-drive-sheets skills. They are visible once the Google provider is configured for the organisation.

1. Create the OAuth client in Google Cloud

1. In the Google Cloud console, open APIs & Services → Credentials in a project owned by your organisation.

2. Enable the APIs: Gmail, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Slides and Google Tasks.

3. Configure the OAuth consent screen. If every person who will connect is in your Workspace, choose the Internal user type. Whether Google requires app verification for sensitive and restricted scopes such as Gmail and Drive depends on your user type and Google’s current policy, so check Google’s documentation for your case.

4. Create an OAuth client ID of type Web application.

5. Add this Authorized redirect URI, using your deployment’s public URL:

   https://<your-public-host>/v1/connectors/oauth/google/callback

6. Copy the client ID and client secret.

2. Register the client in Cengrid

1. Open Connections in the admin console and choose Available.
2. Choose Configure on Google. The drawer has an Organization setup section.
3. Enter the Client ID and Client secret. The secret is encrypted and never shown again.
4. Choose Save app setup. Saving is organisation-wide and does not connect anyone’s account.

The drawer also has Requested scopes, Redirect allowlist, Hosted domain and Enabled. If you use the redirect allowlist, it must contain the exact callback URI above.

Alternatively, set GOOGLE_OAUTH_CLIENT_ID (in env.core) and GOOGLE_OAUTH_CLIENT_SECRET (a secret) in your deployment. A client saved in the console takes precedence over the environment. If you disable the stored client, Cengrid does not fall back to the environment. Remove app setup does fall back.

3. People connect their account

Each person opens Keychain in the web app, finds the Google Workspace card, and chooses Connect account. After Google’s consent screen they return to the Keychain. The card then shows Connected, with Reconnect and Disconnect actions. The agent can also hand someone a one-time consent link for their own account in chat.

Scopes requested

Feature	Scope	API host
Gmail	https://www.googleapis.com/auth/gmail.modify	gmail.googleapis.com
Calendar	https://www.googleapis.com/auth/calendar	www.googleapis.com
Tasks	https://www.googleapis.com/auth/tasks	www.googleapis.com
Drive	https://www.googleapis.com/auth/drive	www.googleapis.com
Sheets	https://www.googleapis.com/auth/spreadsheets	sheets.googleapis.com
Docs and Slides	No dedicated scope. The Docs and Slides APIs must be enabled in the project.	docs.googleapis.com, slides.googleapis.com
Account identity	openid, email	n/a

Cengrid requests offline access with prompt=consent, so Google issues a refresh token. Anything you enter in Requested scopes replaces these defaults.

Domain restriction

The Hosted domain field restricts connections to one Google Workspace domain, but it is applied only to consent links minted for a company account. The standard Connect account button in the Keychain does not apply it. To keep out accounts from other domains, use the Internal user type on the Google consent screen.

Tokens, refresh and reconnect

• Cengrid refreshes tokens on demand when a token is within about ten minutes of expiry. There is no refresh cron.
• If a refresh fails, the Keychain shows Reconnect needed with the error, and the next use fails with a message telling the owner to reconnect.
• If a person has not connected, the skill tells the agent to ask them to connect. It never asks for a token.
• The OAuth state in a connect flow lasts ten minutes and is single use.

How the agent uses the token

For personal OAuth accounts, the person’s access token is available inside their sandbox as an environment variable named after the API host, such as VAULT_TOKEN_GMAIL_GOOGLEAPIS_COM. The skills are told never to log it or use another person’s. This differs from connections, where the secret never enters the sandbox.

Network egress

If your organisation uses an egress allowlist, allow gmail.googleapis.com, www.googleapis.com, sheets.googleapis.com, docs.googleapis.com and slides.googleapis.com, and for service accounts also oauth2.googleapis.com. An empty allowlist allows all hosts. See secrets and egress.

Google service accounts

A Google service account is a shared, server-to-server identity. Use it for a Google API that you have shared with the service account’s email, such as Google Ad Manager. It is an authentication method (google-service-account) on an API or MCP connection, configured by an administrator for the organisation or a team.

1. In Google Cloud, create a service account and a JSON key.
2. Share the Google resource or API with the service account’s email address.
3. In Connections, create or configure the connection with authentication Google service account.
4. Upload or paste the Service account key (JSON), and enter the Google scopes, at least one. For Ad Manager that is https://www.googleapis.com/auth/admanager.
5. Save, then Test connection.

Cengrid keeps only client_email, private_key and private_key_id, encrypted. Core signs a short-lived assertion and exchanges it at https://oauth2.googleapis.com/token (the key’s own token_uri is ignored), caches the access token until a minute before expiry, and retries once on a 401. The sandbox never receives the key or token. The assertion carries no sub, so it does not impersonate a person: it reaches only what is shared with the service account itself.

Sign in with Google

Signing in to the web app is separate from API access. The built-in email sign-in needs no Google setup. To use Google Workspace as the identity provider instead:

1. Create an OAuth client of type Web application with the redirect https://<your-public-host>/auth/callback, and choose Internal on the consent screen.

2. Drop "auth" from services in cengrid.config.jsonc and set these in env.portal:

   OIDC_AUTH_ENDPOINT=https://accounts.google.com/o/oauth2/v2/auth
   OIDC_TOKEN_ENDPOINT=https://oauth2.googleapis.com/token
   OIDC_USERINFO_ENDPOINT=https://openidconnect.googleapis.com/v1/userinfo
   OIDC_ISSUER=https://accounts.google.com
   OIDC_JWKS_URI=https://www.googleapis.com/oauth2/v3/certs
   OIDC_SCOPES="openid email profile"
   OIDC_PRINCIPAL_CLAIM=email
   OIDC_ALLOWED_EMAIL_DOMAIN=example.com

3. Set OIDC_CLIENT_ID, and supply OIDC_CLIENT_SECRET as a secret.

In production the portal requires a trust boundary, so set OIDC_ALLOWED_EMAIL_DOMAIN or OIDC_ALLOWED_EMAILS, and it rejects accounts whose Google hd claim does not match the domain. You can also connect an identity provider at Admin → Onboarding → Single sign-on with an issuer URL, client ID, client secret and allowed email domain. Using the email as the principal means Slack, Google Chat and web sign-ins all resolve to the same person.

Troubleshooting

Symptom	Check
The Keychain has no Google Workspace card	The Google provider is not configured. Save the organisation setup first.
Google reports a redirect URI mismatch	The URI in Google Cloud must exactly equal https://<your-public-host>/v1/connectors/oauth/google/callback.
“provider not configured”	Set the client in Connections → Available → Google, or set both GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET.
“Reconnect needed”	The refresh token was revoked or expired. The person chooses Reconnect.
Calls fail with a blocked host	Add the Google API hosts to the egress allowlist.