Authentication - Overlay Web

Overlay authentication has three independent layers:

Session backend — WorkOS or Better Auth owns the browser session.
Identity protocol — the private deployment currently uses OpenID Connect (OIDC).
Provider recipe — Google Workspace, Auth0, Entra ID, or a generic OIDC provider supplies identities.

Keeping these layers separate prevents provider-specific assumptions from leaking into the application. Overlay consumes one normalized session and user contract after login.

Supported combinations

Session backend	Protocol/provider	Intended deployment	Status
WorkOS	WorkOS AuthKit connections	Hosted Overlay	Supported and retained
Better Auth	Google Workspace OIDC	Customer-controlled web deployment	Supported; primary EC2 flow
Better Auth	Auth0 OIDC	Customer-controlled or managed IdP	Supported alternative
Better Auth	Entra ID OIDC	Microsoft enterprise tenant	Supported preset
Better Auth	Generic OIDC	Cognito, Okta, Keycloak, or another standards-compliant IdP	Supported with provider-specific issuer configuration
OIDC bearer verifier	Generic OIDC access token	API/service-client verification	Supported, but it is not a browser login/session backend

Better Auth and WorkOS identities are intentionally separate. Matching email addresses do not merge accounts, chats, settings, or billing data.

Recommended private deployment

Use Better Auth + OIDC + Google Workspace when the customer already manages staff accounts in Google Workspace. Overlay stores its own sessions in Postgres while Google remains the identity authority.

Browser
  -> Overlay /api/auth/sso/workspace
  -> Better Auth
  -> Google Workspace OIDC
  -> Overlay Better Auth callback
  -> Overlay session
  -> normalized user/session contract

Start with:

Use Auth0 only when Auth0 is the approved identity broker. Use Generic OIDC for Cognito, Okta, and Keycloak.

Providers Authentication Backends

​Supported combinations

​Recommended private deployment

Supported combinations

Recommended private deployment