Skip to main content
Google Workspace is the primary identity flow for the disposable EC2 sanity check. Overlay connects directly to Google; Auth0 is not required.

​
1. Create or select a Google Cloud project

Use a customer-controlled Google Cloud project associated with the Workspace organization. For a rehearsal, create a disposable project and label it as nonproduction. The operator needs permission to configure Google Auth Platform and OAuth clients. Do not weaken the organization’s allowed-domain policy to add a personal Gmail account.

​
2. Configure Google Auth Platform

In Google Auth Platform → Branding:
  • Set an application name, such as Overlay.
  • Select a Workspace support email.
  • Add an operator-owned developer contact email.
  • Accept the Google API Services User Data Policy.
In Audience, select Internal when only members of the Workspace organization should sign in. Internal apps do not admit personal Gmail accounts.

​
3. Create the web OAuth client

Create an OAuth client with application type Web application. For local or SSH-tunnel EC2 testing:
For the final hostname:
Save the client ID and client secret in the approved secret manager. Do not commit the downloaded credential JSON.

​
4. Configure Overlay

The google-workspace preset includes Google’s separate trusted token, userinfo, and JWKS endpoint origins. Do not replace it with an issuer-only generic preset unless you also validate all discovery endpoints.

​
5. Migrate and verify

Verify:
  1. /api/auth/options exposes Continue with Google and no unsupported providers.
  2. Sign-in uses an account in the permitted Workspace domain.
  3. Google returns to /api/better-auth/sso/callback/workspace.
  4. The browser lands in /app/chat.
  5. /api/auth/session reports the expected email and emailVerified: true.
  6. Refresh and a second tab retain the session.
  7. Sign-out clears the session.
If Google reports redirect_uri_mismatch, compare the complete callback URI character for character. If Overlay rejects discovery metadata, use the google-workspace preset and run the current release rather than adding broad wildcard trusted origins.