Connect Google Workspace

Agent markdown

Before you start

Engine operator provisions one Google Cloud OAuth client for the Init platform. Connection admin/user grants consent for their Google Workspace tenant when connecting.

You need:

• A Google Cloud project with the Google Workspace APIs you intend to call enabled (for example Admin SDK, Drive, Docs, Calendar).
• Access to create OAuth client credentials in that project.
• For Directory or domain-wide admin APIs, a Google Workspace admin account that can consent to those scopes.
• The engine public base URL so the redirect URI matches production.

Configure the provider

One-time platform OAuth app (Engine operator)

1. In Google Cloud Console, open APIs & Services → Credentials.

2. Configure the OAuth consent screen for a web application. Include only the scopes Init will request for the actions you expose; do not add broad scopes “just in case.”

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

4. Add the authorized redirect URI exactly as:

   {FUSE_PUBLIC_URL}/v1/oauth/google_workspace/callback

   Replace {FUSE_PUBLIC_URL} with your deployed Fuse public URL (no trailing slash).

5. Copy the client ID and client secret into the Fuse environment as GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET. Never commit these values.

6. If the app is still in Testing, add every Workspace admin or user who must complete Connect as a test user on the consent screen.

Per-customer authorization (Connection admin/user)

No Google Cloud credentials are created per customer. Each connection runs Google’s authorization-code consent for that Workspace identity.

Connect to Init

1. Connection admin/user starts a Google Workspace Connect session from the customer product that embeds Init Connect.
2. Complete Google sign-in and consent for the requested scopes.
3. Init exchanges the authorization code at the platform callback and stores the connection. No customer-submitted credential fields are required for this provider.

If Connect asks you to reconnect after new actions are enabled, re-consent so Google returns the expanded grant.

Permissions

Action-required Google scopes are listed on the generated provider scope matrix. Prefer least privilege.

Baseline identity scopes (runtime consent policy, not action-declared): Init also requests openid, https://www.googleapis.com/auth/userinfo.email, and https://www.googleapis.com/auth/userinfo.profile so the connection can bind the signed-in Google identity. These are separate from action-required API scopes.

Directory and other admin scopes typically require a Workspace administrator to consent. Restricted or sensitive scopes may require Google verification for production apps outside Testing mode.

Verify the connection

1. Confirm the connection status is active in Init after consent returns.
2. Run a safe read-only connection test or a low-risk list action (for example listing drives or files) against a non-sensitive resource.
3. Success looks like a completed Connect session, a stored refreshable Google grant, and a successful read response without 401/403 from Google.

Rotate or revoke access

• Rotate platform client secret (Engine operator): create a new secret in Google Cloud, update GOOGLE_OAUTH_CLIENT_SECRET, then retire the old secret after traffic moves.
• Revoke a customer grant (Connection admin/user): remove Init access from the Google Account permissions page or Workspace admin controls, then delete or reconnect the Init connection.
• After scope expansion in Init, reconnect so Google issues a grant that includes the new scopes.

Troubleshooting