> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Choose an Overlay session backend, identity protocol, and provider recipe.

Overlay authentication has three independent layers:

1. **Session backend** — WorkOS or Better Auth owns the browser session.
2. **Identity protocol** — the private deployment currently uses OpenID Connect (OIDC).
3. **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 |

> [!WARNING]
>
> 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.

```text theme={null}
Browser
  -> Overlay /api/auth/sso/workspace
  -> Better Auth
  -> Google Workspace OIDC
  -> Overlay Better Auth callback
  -> Overlay session
  -> normalized user/session contract
```

Start with:

* [Authentication Backends](https://getoverlay.io/docs/self-hosting/configure/authentication/backends.md)
* [OIDC Protocol](https://getoverlay.io/docs/self-hosting/configure/authentication/oidc.md)
* [Google Workspace](https://getoverlay.io/docs/self-hosting/configure/authentication/recipes/google-workspace.md)

Use [Auth0](https://getoverlay.io/docs/self-hosting/configure/authentication/recipes/auth0.md) only when Auth0 is the approved identity broker. Use [Generic OIDC](https://getoverlay.io/docs/self-hosting/configure/authentication/recipes/generic-oidc.md) for Cognito, Okta, and Keycloak.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.