SSO & Session Management

Physical Basis

SSO is built on shared cookies, not shared tokens. All applications deployed under the same parent domain (.example.com) share the session cookie set by saas-core.

saas-core sets:
  Set-Cookie: better-auth.session_token=xxx; Domain=.example.com; Path=/; HttpOnly

This cookie is sent by the browser to ALL *.example.com subdomains:
  → tobby.example.com   ✓
  → studio.example.com   ✓
  → auth.example.com     ✓ (this is saas-core itself)

Because the session cookie is shared, any application in the same parent domain can call /api/auth/get-session and immediately retrieve the user’s session — no redirect, no authentication prompt.

SSO Groups

SSO Groups control which applications share sessions. The mechanism is straightforward:

Applications in the same group → session shared (no login prompt) Applications not in any group → no automatic session sharing

This is implemented at two points:

1. Path A (direct client): Cookie is naturally shared by the browser. There is no additional check needed — if the cookie is present and valid, the session is recognized.

2. Path B (OAuth redirect): The authorize endpoint checks whether the requesting application is in the same SSO group as the user’s current session. If not, it redirects to the login page.

Application Modes

Application type	SSO Group	Behavior
Shared (Acme, Beta)	tobby-suite	Session shared. User logs into one, automatically recognized by the other.
Isolated (gamma)	None	Session not shared. User must authenticate explicitly.
iOS companion	Same group as web	Session shared via OAuth authorize. Web session is recognized, iOS gets silent authorization code.

Admin Configuration

In the admin console, assigning an application to an SSO Group is done during registration or via the API:

# Create application with SSO Group
POST /api/admin/applications
{ "id": "studio", "ssoGroupId": "tobby-suite", ... }

# Or later via dedicated API
POST /api/admin/sso-groups/tobby-suite/apps
{ "appId": "studio" }

Session Management API

Users can view and manage their active sessions via the self-service API:

GET    /api/me/sessions          → List all active sessions
DELETE /api/me/sessions/:sid     → Revoke a specific session

Administrators can manage sessions for any user in their application:

GET    /api/admin/applications/:id/sessions     → List sessions
DELETE /api/admin/applications/:id/sessions/:sid → Revoke session