classroomio/prd/enterprise-sso [DONE]/README.md

# Enterprise SSO PRD (SAML 2.0 + OIDC)

## Purpose
Add enterprise SSO for ClassroomIO with per-organization configuration, supporting both SAML 2.0 and OIDC, while preserving the current Better Auth session model and multi-tenant org permissions.

## Confirmed Decisions (2026-02-17)
1. IdPs to support: Auth0, Google Workspace, Okta.
2. Scope: per organization (not global tenant-wide config).
3. Protocols: OIDC for v1. SAML 2.0 deferred to v2.
4. Force SSO: enabled (orgs can disable email/password when SSO is enabled).
5. Provisioning: JIT only for v1. SCIM deferred to future phase.
6. SAML deferred to v2 (Better Auth SAML is in active development).
7. Break-glass: simplified emergency access via pre-configured admin bypass.
8. Domain enforcement: simplified to auto-join toggle.
9. Entitlement: SSO is gated to `PLAN.ENTERPRISE`.
10. SCIM deprovisioning: future phase, with interim login-time entitlement checks.

## Architecture: Better Auth SSO Plugin

v1 leverages **Better Auth's official SSO plugin** (`@better-auth/sso`) for OIDC support:
- Built-in OIDC discovery and flow handling
- Automatic callback URL generation
- Domain-based provider routing
- Claim mapping support
- Session management via Better Auth

Our custom layer handles:
- Enterprise plan entitlement checks
- Organization-scoped provider management
- Force SSO policy enforcement
- Org membership JIT provisioning
- Admin configuration UI

## Current-State Audit

| Capability | Current State | Notes |
| --- | --- | --- |
| Auth framework | available | Better Auth with cookie sessions (`packages/db/src/auth.ts`) |
| Email/password auth | available | Enabled via `emailAndPassword` (`packages/db/src/auth/email-password.ts`) |
| Social login | partial | Google social login only (`packages/db/src/auth.ts`, `apps/dashboard/src/lib/features/ui/auth-ui.svelte`) |
| Session handling | available | `/api/auth/*` mounted in API, `auth.api.getSession` middleware (`apps/api/src/app.ts`) |
| Multi-tenant org model | available | `organization`, `organizationmember`, org role checks and `cio-org-id` header enforcement |
| Org invite flows | available | Role-aware organization invites already implemented |
| Enterprise SSO (SAML/OIDC per org) | missing | No SSO connection model, no discovery, no SAML/OIDC enterprise callback flows |
| Force SSO policy | missing | No org-level policy to block local email/password |
| SCIM | missing | No SCIM endpoints or provisioning sync |

## Product Goals
1. Allow each organization to configure one SSO connection.
2. Support Auth0, Google Workspace, and Okta with OIDC.
3. Preserve existing Better Auth sessions/cookies and downstream auth middleware behavior.
4. Add Force SSO policy at org level.
5. Keep invite/onboarding flows compatible with SSO.
6. Ship JIT provisioning for v1.
7. Add simple domain-based auto-join policy.
8. Gate all SSO capabilities to Enterprise plan organizations.

## Non-Goals (v1)
- **SAML 2.0** (deferred to v2 - Better Auth SAML is in active development).
- SCIM implementation (deferred to future phase).
- Multiple SSO connections per organization.
- Custom claim mapping UI (use standard claims).
- Global logout / SAML Single Logout (SLO).
- Arbitrary custom IdP templates beyond Auth0/Google Workspace/Okta.
- Cross-organization identity linking rules beyond current email + org membership model.

## Data Sources Checked
- `packages/db/src/auth.ts`
- `packages/db/src/auth/email-password.ts`
- `apps/api/src/app.ts`
- `apps/api/src/middlewares/auth.ts`
- `apps/api/src/middlewares/org-member.ts`
- `apps/api/src/middlewares/org-admin.ts`
- `packages/db/src/schema.ts`
- `packages/db/src/queries/organization/organization.ts`
- `apps/api/src/services/account.ts`
- `apps/api/src/services/organization/invite.ts`
- `apps/api/src/services/course/invite.ts`
- `apps/dashboard/src/lib/utils/services/auth/client.ts`
- `apps/dashboard/src/lib/utils/services/auth/session.ts`
- `apps/dashboard/src/routes/(auth)/login/+page.svelte`
- `apps/dashboard/src/lib/features/ui/auth-ui.svelte`
- `apps/dashboard/src/lib/features/app/init.svelte.ts`
- `apps/dashboard/src/lib/features/ui/navigation/org-navigation.ts`
- `apps/docs/content/docs/quickstart/self-hosting.mdx`
- `apps/docs/content/docs/meta.json`
- `apps/docs/content/docs/quickstart/meta.json`

## Functional Requirements

### 1. Per-Organization SSO Connection Management
- Org admins can create/update/disable one SSO connection per org.
- Supported providers: Auth0, Google Workspace, Okta.
- Supported protocols: OIDC and SAML 2.0.
- Connection supports test/verify before activation.

### 2. SSO Discovery and Login Start
- On org domains (`{org}.domain.com` or custom domain), login should use that org context directly.
- On shared app domain, user can enter email to discover SSO route by org policy/domain mapping.
- Discovery response should indicate:
  - SSO required or optional
  - Provider type
  - Whether password login is allowed

### 3. OIDC Flow (Better Auth SSO Plugin)
Better Auth handles the OIDC flow:
- Authorization code flow with PKCE, `state`, and `nonce`.
- Auto-discovery from `.well-known/openid-configuration`.
- Token validation and userinfo retrieval.
- Claim mapping to user fields.

Our layer handles:
- Provider registration via `auth.api.registerSSOProvider`.
- Post-sign-in org membership provisioning via `dbHooks`.
- Role mapping from `groups` claim.

### 4. SAML 2.0 Flow (v2)
- **Deferred to v2** - will be implemented once Better Auth's SAML support is stable.

### 5. JIT Provisioning and Membership Linking
- On successful SSO callback:
  - Find or create user/profile
  - Upsert org membership in `organizationmember`
  - Link external identity (`connection + subject`) to local user
- If invited member row exists by email, bind `profileId` and mark verified
- Default JIT role for new users: `ROLE.STUDENT`

### 6. Role Mapping
- Simple role mapping from IdP `groups` claim:
  - Map group names to `ROLE.ADMIN`, `ROLE.TUTOR`, `ROLE.STUDENT`
  - If no mapping matched, fallback to `ROLE.STUDENT`
- Configuration: simple key-value mapping in connection settings

### 7. Force SSO
- Org-level `forceSso=true` disables email/password login for that org context
- Enforce server-side, not only UI-level
- Users attempting password login for a force-SSO org receive structured error + SSO redirect hints
- Existing email/password sessions: remain valid until expiry (no forced logout)
- Break-glass: pre-configured emergency admin can bypass (audited)

### 8. Audit and Observability
- Use existing audit/logging infrastructure with structured event types:
  - `sso.connection_created`, `sso.connection_updated`, `sso.connection_disabled`
  - `sso.login_success`, `sso.login_failure`
  - `sso.provisioned`, `sso.role_assigned`
  - `sso.force_sso_block`
- Include orgId, connectionId, actor/profile (when available), IP, user agent

### 9. Domain Auto-Join Policy
- Simple toggle: `auto_join_sso_domains` (boolean)
- When enabled, users with matching email domain can auto-join org via SSO
- When disabled, users must have pending invite to join via SSO
- Trust IdP-verified email domains

### 10. Enterprise Plan Entitlement
- SSO configuration and login endpoints must verify org entitlement to `PLAN.ENTERPRISE`
- Non-enterprise orgs receive explicit upgrade-required responses

## Technical Design

### Architecture Summary
Leverage **Better Auth SSO plugin** (`@better-auth/sso`) for OIDC protocol handling. Our custom layer provides:
1. **Admin management** - CRUD SSO connections (stored in our schema for UI)
2. **Enterprise gating** - Verify `PLAN.ENTERPRISE` before allowing SSO
3. **Force SSO enforcement** - Block email/password when policy enabled
4. **JIT provisioning** - Create org membership post-authentication via `dbHooks`

Better Auth handles:
- OIDC discovery, authorization, token exchange
- Session creation and management
- User creation/linking

### Data Model

#### `organization_auth_policy`
- `organization_id` (uuid, pk/fk)
- `force_sso` (boolean, default `false`)
- `default_role_id` (bigint, default `ROLE.STUDENT`)
- `allow_email_password_fallback` (boolean, default `true`)
- `auto_join_sso_domains` (boolean, default `false`)
- `break_glass_enabled` (boolean, default `true`)
- `created_at`, `updated_at`

#### `organization_sso_connection`
- `id` (uuid, pk)
- `organization_id` (uuid, fk, indexed, unique)
- `provider` (`OKTA` | `GOOGLE_WORKSPACE` | `AUTH0`)
- `protocol` (`OIDC`) - enum for future SAML extension
- `display_name` (text)
- `is_active` (boolean, default `false`)
- `issuer` (text) - IdP issuer URL
- `domain` (text) - email domain for discovery
- `oidc_config` (jsonb) - clientId, scopes, etc (clientSecret stored in Better Auth)
- `role_mapping` (jsonb) - simple key-value: group name → role
- `better_auth_provider_id` (text) - reference to Better Auth's stored provider
- `created_by_profile_id`, `updated_by_profile_id` (uuid)
- `created_at`, `updated_at`

#### `sso_identity_link`
- `id` (uuid, pk)
- `organization_id` (uuid, indexed)
- `connection_id` (uuid, fk)
- `user_id` (uuid, fk to `user.id`)
- `external_subject` (text)
- `email_at_link` (text)
- `last_login_at` (timestamp)
- `created_at`, `updated_at`

Constraints:
- unique `(connection_id, external_subject)`
- unique `(organization_id, user_id, connection_id)`

## API and Route Plan

### Better Auth Integration
The SSO plugin provides these endpoints automatically:
- `POST /api/auth/sso/register` - Register OIDC provider (admin only)
- `GET/POST /api/auth/sso/authorize/:providerId` - Start SSO flow
- `GET/POST /api/auth/sso/callback/:providerId` - OIDC callback

### Our Custom Layer

#### Validation Layer
- `packages/utils/src/validation/organization/sso.ts`
  - `ZCreateSsoConnection`
  - `ZUpdateSsoConnection`
  - `ZSsoDiscoveryQuery`

#### Query Layer
- `packages/db/src/queries/organization/sso.ts`
  - connection CRUD
  - org auth policy read/write

#### Service Layer
- `apps/api/src/services/organization/sso.ts`
  - Admin CRUD with Enterprise plan check
  - Call `auth.api.registerSSOProvider` on activation
  - Call `auth.api.deleteSSOProvider` on deactivation
- `apps/api/src/services/auth/sso.ts`
  - Discovery logic
  - Force SSO enforcement

#### Route Layer
- `apps/api/src/routes/organization/sso.ts` - Admin CRUD endpoints
- `apps/api/src/routes/sso/discovery.ts` - Public discovery endpoint
- Register in:
  - `apps/api/src/routes/organization/index.ts`
  - `apps/api/src/app.ts`

#### Better Auth Hooks
- `dbHooks.user.afterCreate` - JIT org membership provisioning

## Frontend Plan (Dashboard)

### Login UX
- Update:
  - `apps/dashboard/src/routes/(auth)/login/+page.svelte`
  - `apps/dashboard/src/lib/features/ui/auth-ui.svelte`
- Add SSO discovery step:
  - org-site context: direct SSO action for current org
  - shared app login: email-based discovery before method selection
- If Force SSO for org, hide password fields and show SSO-only CTA

### Org Settings UX
- Add new page: `apps/dashboard/src/routes/org/[slug]/settings/sso/+page.svelte`
- Add settings feature page: `apps/dashboard/src/lib/features/settings/pages/sso.svelte`
- Export page in `apps/dashboard/src/lib/features/settings/pages/index.ts`
- Add org navigation nested route in `apps/dashboard/src/lib/features/ui/navigation/org-navigation.ts`
- Add controls for:
  - Provider selection (Auth0, Google Workspace, Okta)
  - Protocol selection (OIDC, SAML)
  - Force SSO toggle
  - Auto-join toggle
  - Simple role mapping
  - Break-glass enable/disable
- Add translation keys in `apps/dashboard/src/lib/utils/translations/en.json`

### Admin SSO Configuration UI Spec

#### Page Information Architecture
- `Connection` section:
  - Current SSO connection status (provider, protocol, active/inactive)
  - Actions: `Configure`, `Edit`, `Disable`, `Test`, `Activate`
- `Policies` section:
  - Force SSO toggle
  - Auto-join toggle
  - Break-glass toggle
- `Role Mapping` section:
  - Simple table: IdP group name → ClassroomIO role

#### Setup Wizard (Create/Edit Connection)
- Step 1 `Choose Provider`:
  - Provider: `Auth0`, `Google Workspace`, `Okta`
  - Protocol: `OIDC` or `SAML`
- Step 2 `Configure Identity Provider`:
  - Render provider/protocol-specific fields
  - Show generated callback values to copy into IdP
- Step 3 `Test Connection` (optional):
  - Run live test with state/nonce checks
  - Display pass/fail results with remediation hints
- Step 4 `Activate`:
  - Summary of config
  - Activate now or save as draft
  - If Force SSO enabled, require explicit confirmation

#### Provider-Specific Form Fields (OIDC Only)
- Common fields:
  - `display_name` (required)
  - `domain` (required) - email domain for discovery (e.g., `company.com`)
- OIDC fields:
  - `issuer` (required URL) - e.g., `https://company.okta.com`
  - `client_id` (required)
  - `client_secret` (required) - sent to Better Auth, not stored locally
  - `scopes` (default `openid profile email`)
  - Read-only: callback URL (`/api/auth/sso/callback/{providerId}`)

#### Validation Rules and Error UX
- Field-level validation:
  - URLs must be valid HTTPS (localhost exception for dev)
  - Required fields present before activation
  - Claim mapping must include `email` and `sub`/`NameID`
- Cross-field validation:
  - `force_sso=true` requires active connection
  - Connection can be saved as draft without full validation
- Error presentation:
  - Inline field errors for input validation
  - Structured backend errors for: issuer mismatch, invalid cert, callback mismatch, missing claims

#### Safety and Recovery UX
- Draft mode supported; drafts cannot be used for login
- Disable/rollback action always available to org admins
- All admin actions write visible audit entries

### Client Types/API Class
- Add request types in `apps/dashboard/src/lib/features/org/utils/types.ts`
- Add API class in `apps/dashboard/src/lib/features/org/api/sso.svelte.ts`
- Use `this.execute<RequestType>()` pattern only

## Documentation Plan (`apps/docs`)

### Required Documentation Updates
- Add core feature documentation:
  - `apps/docs/content/docs/enterprise-sso.mdx` - feature overview
- Add how-to guides:
  - `apps/docs/content/docs/how-to/sso-auth0.mdx`
  - `apps/docs/content/docs/how-to/sso-google-workspace.mdx`
  - `apps/docs/content/docs/how-to/sso-okta.mdx`
- Register pages in root docs nav:
  - `apps/docs/content/docs/meta.json` under `---Core Features---`
- Update self-hosting reference:
  - `apps/docs/content/docs/quickstart/self-hosting.mdx`
  - Include SSO-related env vars and callback URL guidance

### Required Topics in Docs
- SSO prerequisites and Enterprise plan requirement
- Provider-by-provider setup checklist (Auth0, Google Workspace, Okta)
- Force SSO behavior and user experience
- JIT behavior and invite interactions
- Break-glass policy
- Troubleshooting: callback mismatch, certificate issues, entitlement errors

## Security Requirements
1. Encrypt all SSO secrets at rest
2. Strict signature/issuer/audience checks for SAML/OIDC
3. Anti-CSRF and replay protection via `state`/`nonce` and one-time callback state
4. Rate-limit discovery/start/callback endpoints
5. Full audit trail for admin config and auth outcomes via existing logging
6. No trust of frontend-enforced Force SSO alone; must be validated on backend

## Rollout Plan

### Phase 1: Foundation + OIDC + JIT
- Install `@better-auth/sso` plugin
- Schema + policy/connection management
- Integration with Better Auth SSO plugin
- OIDC flows for Auth0/Google Workspace/Okta via Better Auth
- SSO discovery + login UI
- Force SSO enforcement
- Domain auto-join policy + admin settings UI
- Enterprise plan entitlement checks
- JIT org membership via `dbHooks`
- Publish docs updates

### Phase 2: SAML 2.0
- Enable when Better Auth SAML is stable
- SAML flows for supported providers
- Force SSO parity for SAML

### Phase 3: Future Enhancements
- SCIM provisioning (if customer demand)
- Multiple connections per org (if customer demand)
- Advanced claim mapping (if customer demand)

## Acceptance Criteria
1. Org admin can configure an active SSO connection (OIDC).
2. User can successfully login through Auth0, Google Workspace, and Okta.
3. Successful SSO login creates/links user and org membership via JIT.
4. Force SSO org cannot authenticate through email/password for org-context access.
5. Auto-join policy is configurable in UI and enforced server-side.
6. SSO access is blocked for non-enterprise orgs.
7. Existing non-SSO orgs keep current auth behavior unchanged.
8. Audit events are logged for config changes and SSO auth events.
9. `apps/docs` includes SSO feature docs and provider how-to guides before GA.
10. Org admins can configure Auth0, Google Workspace, and Okta through a setup wizard.
11. Connection can be saved as draft without full validation.
12. UI surfaces actionable errors for provider setup and configuration issues.

## Risks and Mitigations
- Risk: Force SSO lockout due to bad config.
  - Mitigation: connection can be disabled by any org admin + break-glass emergency access.
- Risk: role escalation by incorrect claim mapping.
  - Mitigation: simple mapping validation + default least privilege (`ROLE.STUDENT`).
- Risk: callback replay attacks.
  - Mitigation: one-time state, timestamp windows, assertion ID tracking.

## Finalized Decisions
1. **OIDC only for v1** - SAML deferred to v2 (Better Auth SAML in active development).
2. Use **Better Auth SSO plugin** (`@better-auth/sso`) for OIDC flow handling.
3. Break-glass local admin access is included with strict auditing.
4. Domain enforcement simplified to auto-join toggle.
5. SSO is gated to `PLAN.ENTERPRISE`.
6. SCIM deferred to future phase.
7. Single connection per org for v1.
8. Standard claims only, no custom claim mapping UI.