From 254da353003a8b50f0519baf4b6b6e6b58d2a398 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Wed, 18 Mar 2026 21:17:11 -0500
Subject: [PATCH 1/4] feat(auth): add WorkOS + Keycloak SSO providers (P8-001)

- Refactor auth.ts to build OAuth providers array dynamically; extract
  buildOAuthProviders() for unit-testability
- Add WorkOS provider (WORKOS_CLIENT_ID/SECRET/REDIRECT_URI env vars)
- Add Keycloak provider with realm-scoped OIDC discovery
  (KEYCLOAK_URL/REALM/CLIENT_ID/CLIENT_SECRET env vars)
- Add genericOAuthClient plugin to web auth-client for signIn.oauth2()
- Add WorkOS + Keycloak SSO buttons to login page (NEXT_PUBLIC_*_ENABLED
  feature flags control visibility)
- Update .env.example with SSO provider stanzas
- Add 8 unit tests covering all provider inclusion/exclusion paths

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .env.example                           |  19 +++-
 apps/web/src/app/(auth)/login/page.tsx |  46 +++++++++-
 apps/web/src/lib/auth-client.ts        |   4 +-
 packages/auth/src/auth.test.ts         | 115 +++++++++++++++++++++++++
 packages/auth/src/auth.ts              |  82 ++++++++++++------
 5 files changed, 235 insertions(+), 31 deletions(-)
 create mode 100644 packages/auth/src/auth.test.ts

diff --git a/.env.example b/.env.example
index 4cbd157..7132b24 100644
--- a/.env.example
+++ b/.env.example
@@ -123,7 +123,24 @@ OTEL_SERVICE_NAME=mosaic-gateway
 # TELEGRAM_GATEWAY_URL=http://localhost:4000
 
 
-# ─── Authentik SSO (optional — set AUTHENTIK_CLIENT_ID to enable) ────────────
+# ─── SSO Providers (add credentials to enable) ───────────────────────────────
+
+# --- Authentik (optional — set AUTHENTIK_CLIENT_ID to enable) ---
 # AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic/
 # AUTHENTIK_CLIENT_ID=
 # AUTHENTIK_CLIENT_SECRET=
+
+# --- WorkOS (optional — set WORKOS_CLIENT_ID to enable) ---
+# WORKOS_CLIENT_ID=client_...
+# WORKOS_CLIENT_SECRET=sk_live_...
+# WORKOS_REDIRECT_URI=http://localhost:3000/api/auth/callback/workos
+
+# --- Keycloak (optional — set KEYCLOAK_CLIENT_ID to enable) ---
+# KEYCLOAK_URL=https://auth.example.com
+# KEYCLOAK_REALM=master
+# KEYCLOAK_CLIENT_ID=mosaic
+# KEYCLOAK_CLIENT_SECRET=
+
+# Feature flags — set to true alongside provider credentials to show SSO buttons in the UI
+# NEXT_PUBLIC_WORKOS_ENABLED=true
+# NEXT_PUBLIC_KEYCLOAK_ENABLED=true
diff --git a/apps/web/src/app/(auth)/login/page.tsx b/apps/web/src/app/(auth)/login/page.tsx
index b01d04f..836e062 100644
--- a/apps/web/src/app/(auth)/login/page.tsx
+++ b/apps/web/src/app/(auth)/login/page.tsx
@@ -5,6 +5,10 @@ import { useRouter } from 'next/navigation';
 import Link from 'next/link';
 import { signIn } from '@/lib/auth-client';
 
+const workosEnabled = process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
+const keycloakEnabled = process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
+const hasSsoProviders = workosEnabled || keycloakEnabled;
+
 export default function LoginPage(): React.ReactElement {
   const router = useRouter();
   const [error, setError] = useState<string | null>(null);
@@ -30,6 +34,16 @@ export default function LoginPage(): React.ReactElement {
     router.push('/chat');
   }
 
+  async function handleSsoSignIn(providerId: string): Promise<void> {
+    setError(null);
+    setLoading(true);
+    const result = await signIn.oauth2({ providerId, callbackURL: '/chat' });
+    if (result?.error) {
+      setError(result.error.message ?? 'SSO sign in failed');
+      setLoading(false);
+    }
+  }
+
   return (
     <div>
       <h1 className="text-2xl font-semibold">Sign in</h1>
@@ -44,7 +58,37 @@ export default function LoginPage(): React.ReactElement {
         </div>
       )}
 
-      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
+      {hasSsoProviders && (
+        <div className="mt-6 space-y-3">
+          {workosEnabled && (
+            <button
+              type="button"
+              disabled={loading}
+              onClick={() => handleSsoSignIn('workos')}
+              className="flex w-full items-center justify-center gap-2 rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:bg-surface-hover focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+            >
+              Continue with WorkOS
+            </button>
+          )}
+          {keycloakEnabled && (
+            <button
+              type="button"
+              disabled={loading}
+              onClick={() => handleSsoSignIn('keycloak')}
+              className="flex w-full items-center justify-center gap-2 rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:bg-surface-hover focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+            >
+              Continue with Keycloak
+            </button>
+          )}
+          <div className="relative flex items-center">
+            <div className="flex-1 border-t border-surface-border" />
+            <span className="mx-3 text-xs text-text-muted">or</span>
+            <div className="flex-1 border-t border-surface-border" />
+          </div>
+        </div>
+      )}
+
+      <form className={hasSsoProviders ? 'space-y-4' : 'mt-6 space-y-4'} onSubmit={handleSubmit}>
         <div>
           <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
             Email
diff --git a/apps/web/src/lib/auth-client.ts b/apps/web/src/lib/auth-client.ts
index 398c251..ae07f03 100644
--- a/apps/web/src/lib/auth-client.ts
+++ b/apps/web/src/lib/auth-client.ts
@@ -1,9 +1,9 @@
 import { createAuthClient } from 'better-auth/react';
-import { adminClient } from 'better-auth/client/plugins';
+import { adminClient, genericOAuthClient } from 'better-auth/client/plugins';
 
 export const authClient = createAuthClient({
   baseURL: process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:4000',
-  plugins: [adminClient()],
+  plugins: [adminClient(), genericOAuthClient()],
 });
 
 export const { useSession, signIn, signUp, signOut } = authClient;
diff --git a/packages/auth/src/auth.test.ts b/packages/auth/src/auth.test.ts
new file mode 100644
index 0000000..31b76a8
--- /dev/null
+++ b/packages/auth/src/auth.test.ts
@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { buildOAuthProviders } from './auth.js';
+
+describe('buildOAuthProviders', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    // Clear all SSO-related env vars before each test
+    delete process.env['AUTHENTIK_CLIENT_ID'];
+    delete process.env['AUTHENTIK_CLIENT_SECRET'];
+    delete process.env['AUTHENTIK_ISSUER'];
+    delete process.env['WORKOS_CLIENT_ID'];
+    delete process.env['WORKOS_CLIENT_SECRET'];
+    delete process.env['KEYCLOAK_CLIENT_ID'];
+    delete process.env['KEYCLOAK_CLIENT_SECRET'];
+    delete process.env['KEYCLOAK_URL'];
+    delete process.env['KEYCLOAK_REALM'];
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('returns empty array when no SSO env vars are set', () => {
+    const providers = buildOAuthProviders();
+    expect(providers).toHaveLength(0);
+  });
+
+  describe('WorkOS', () => {
+    it('includes workos provider when WORKOS_CLIENT_ID is set', () => {
+      process.env['WORKOS_CLIENT_ID'] = 'client_test123';
+      process.env['WORKOS_CLIENT_SECRET'] = 'sk_live_test';
+
+      const providers = buildOAuthProviders();
+      const workos = providers.find((p) => p.providerId === 'workos');
+
+      expect(workos).toBeDefined();
+      expect(workos?.clientId).toBe('client_test123');
+      expect(workos?.authorizationUrl).toBe('https://api.workos.com/sso/authorize');
+      expect(workos?.tokenUrl).toBe('https://api.workos.com/sso/token');
+      expect(workos?.userInfoUrl).toBe('https://api.workos.com/sso/profile');
+      expect(workos?.scopes).toEqual(['openid', 'email', 'profile']);
+    });
+
+    it('excludes workos provider when WORKOS_CLIENT_ID is not set', () => {
+      const providers = buildOAuthProviders();
+      const workos = providers.find((p) => p.providerId === 'workos');
+      expect(workos).toBeUndefined();
+    });
+  });
+
+  describe('Keycloak', () => {
+    it('includes keycloak provider when KEYCLOAK_CLIENT_ID is set', () => {
+      process.env['KEYCLOAK_CLIENT_ID'] = 'mosaic';
+      process.env['KEYCLOAK_CLIENT_SECRET'] = 'secret123';
+      process.env['KEYCLOAK_URL'] = 'https://auth.example.com';
+      process.env['KEYCLOAK_REALM'] = 'myrealm';
+
+      const providers = buildOAuthProviders();
+      const keycloak = providers.find((p) => p.providerId === 'keycloak');
+
+      expect(keycloak).toBeDefined();
+      expect(keycloak?.clientId).toBe('mosaic');
+      expect(keycloak?.discoveryUrl).toBe(
+        'https://auth.example.com/realms/myrealm/.well-known/openid-configuration',
+      );
+      expect(keycloak?.scopes).toEqual(['openid', 'email', 'profile']);
+    });
+
+    it('excludes keycloak provider when KEYCLOAK_CLIENT_ID is not set', () => {
+      const providers = buildOAuthProviders();
+      const keycloak = providers.find((p) => p.providerId === 'keycloak');
+      expect(keycloak).toBeUndefined();
+    });
+  });
+
+  describe('Authentik', () => {
+    it('includes authentik provider when AUTHENTIK_CLIENT_ID is set', () => {
+      process.env['AUTHENTIK_CLIENT_ID'] = 'authentik-client';
+      process.env['AUTHENTIK_CLIENT_SECRET'] = 'authentik-secret';
+      process.env['AUTHENTIK_ISSUER'] = 'https://auth.example.com/application/o/mosaic';
+
+      const providers = buildOAuthProviders();
+      const authentik = providers.find((p) => p.providerId === 'authentik');
+
+      expect(authentik).toBeDefined();
+      expect(authentik?.clientId).toBe('authentik-client');
+      expect(authentik?.discoveryUrl).toBe(
+        'https://auth.example.com/application/o/mosaic/.well-known/openid-configuration',
+      );
+    });
+
+    it('excludes authentik provider when AUTHENTIK_CLIENT_ID is not set', () => {
+      const providers = buildOAuthProviders();
+      const authentik = providers.find((p) => p.providerId === 'authentik');
+      expect(authentik).toBeUndefined();
+    });
+  });
+
+  it('registers all three providers when all env vars are set', () => {
+    process.env['AUTHENTIK_CLIENT_ID'] = 'a-id';
+    process.env['WORKOS_CLIENT_ID'] = 'w-id';
+    process.env['KEYCLOAK_CLIENT_ID'] = 'k-id';
+    process.env['KEYCLOAK_URL'] = 'https://kc.example.com';
+    process.env['KEYCLOAK_REALM'] = 'test';
+
+    const providers = buildOAuthProviders();
+    expect(providers).toHaveLength(3);
+    const ids = providers.map((p) => p.providerId);
+    expect(ids).toContain('authentik');
+    expect(ids).toContain('workos');
+    expect(ids).toContain('keycloak');
+  });
+});
diff --git a/packages/auth/src/auth.ts b/packages/auth/src/auth.ts
index 0d97718..65ae69d 100644
--- a/packages/auth/src/auth.ts
+++ b/packages/auth/src/auth.ts
@@ -1,6 +1,7 @@
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
 import { admin, genericOAuth } from 'better-auth/plugins';
+import type { GenericOAuthConfig } from 'better-auth/plugins';
 import type { Db } from '@mosaic/db';
 
 export interface AuthConfig {
@@ -9,35 +10,62 @@ export interface AuthConfig {
   secret?: string;
 }
 
+/** Builds the list of enabled OAuth providers from environment variables. Exported for testing. */
+export function buildOAuthProviders(): GenericOAuthConfig[] {
+  const providers: GenericOAuthConfig[] = [];
+
+  const authentikClientId = process.env['AUTHENTIK_CLIENT_ID'];
+  if (authentikClientId) {
+    const authentikIssuer = process.env['AUTHENTIK_ISSUER'];
+    providers.push({
+      providerId: 'authentik',
+      clientId: authentikClientId,
+      clientSecret: process.env['AUTHENTIK_CLIENT_SECRET'] ?? '',
+      discoveryUrl: authentikIssuer
+        ? `${authentikIssuer}/.well-known/openid-configuration`
+        : undefined,
+      authorizationUrl: authentikIssuer ? `${authentikIssuer}/application/o/authorize/` : undefined,
+      tokenUrl: authentikIssuer ? `${authentikIssuer}/application/o/token/` : undefined,
+      userInfoUrl: authentikIssuer ? `${authentikIssuer}/application/o/userinfo/` : undefined,
+      scopes: ['openid', 'email', 'profile'],
+    });
+  }
+
+  const workosClientId = process.env['WORKOS_CLIENT_ID'];
+  if (workosClientId) {
+    providers.push({
+      providerId: 'workos',
+      clientId: workosClientId,
+      clientSecret: process.env['WORKOS_CLIENT_SECRET'] ?? '',
+      authorizationUrl: 'https://api.workos.com/sso/authorize',
+      tokenUrl: 'https://api.workos.com/sso/token',
+      userInfoUrl: 'https://api.workos.com/sso/profile',
+      scopes: ['openid', 'email', 'profile'],
+    });
+  }
+
+  const keycloakClientId = process.env['KEYCLOAK_CLIENT_ID'];
+  if (keycloakClientId) {
+    const keycloakUrl = process.env['KEYCLOAK_URL'] ?? '';
+    const keycloakRealm = process.env['KEYCLOAK_REALM'] ?? '';
+    providers.push({
+      providerId: 'keycloak',
+      clientId: keycloakClientId,
+      clientSecret: process.env['KEYCLOAK_CLIENT_SECRET'] ?? '',
+      discoveryUrl: `${keycloakUrl}/realms/${keycloakRealm}/.well-known/openid-configuration`,
+      scopes: ['openid', 'email', 'profile'],
+    });
+  }
+
+  return providers;
+}
+
 export function createAuth(config: AuthConfig) {
   const { db, baseURL, secret } = config;
-  const authentikIssuer = process.env['AUTHENTIK_ISSUER'];
-  const authentikClientId = process.env['AUTHENTIK_CLIENT_ID'];
-  const authentikClientSecret = process.env['AUTHENTIK_CLIENT_SECRET'];
-  const plugins = authentikClientId
-    ? [
-        genericOAuth({
-          config: [
-            {
-              providerId: 'authentik',
-              clientId: authentikClientId,
-              clientSecret: authentikClientSecret ?? '',
-              discoveryUrl: authentikIssuer
-                ? `${authentikIssuer}/.well-known/openid-configuration`
-                : undefined,
-              authorizationUrl: authentikIssuer
-                ? `${authentikIssuer}/application/o/authorize/`
-                : undefined,
-              tokenUrl: authentikIssuer ? `${authentikIssuer}/application/o/token/` : undefined,
-              userInfoUrl: authentikIssuer
-                ? `${authentikIssuer}/application/o/userinfo/`
-                : undefined,
-              scopes: ['openid', 'email', 'profile'],
-            },
-          ],
-        }),
-      ]
-    : undefined;
+
+  const oauthProviders = buildOAuthProviders();
+  const plugins =
+    oauthProviders.length > 0 ? [genericOAuth({ config: oauthProviders })] : undefined;
 
   const corsOrigin = process.env['GATEWAY_CORS_ORIGIN'] ?? 'http://localhost:3000';
   const trustedOrigins = corsOrigin.split(',').map((o) => o.trim());

From b89503fa8c5fb8c94f006257e4cbb439c8e776b7 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Wed, 18 Mar 2026 21:17:57 -0500
Subject: [PATCH 2/4] chore: fix prettier formatting on scratchpad files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/scratchpads/BUG-CLI-scratchpad.md   |  7 +++
 docs/scratchpads/p8-001-sso-providers.md | 62 ++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/scratchpads/p8-001-sso-providers.md

diff --git a/docs/scratchpads/BUG-CLI-scratchpad.md b/docs/scratchpads/BUG-CLI-scratchpad.md
index a69911e..4c37825 100644
--- a/docs/scratchpads/BUG-CLI-scratchpad.md
+++ b/docs/scratchpads/BUG-CLI-scratchpad.md
@@ -1,9 +1,11 @@
 # BUG-CLI Scratchpad
 
 ## Objective
+
 Fix 4 CLI/TUI polish bugs in a single PR (issues #192, #193, #194, #199).
 
 ## Issues
+
 - #192: Ctrl+T leaks 't' into input
 - #193: Duplicate React keys in CommandAutocomplete
 - #194: /provider login false clipboard claim
@@ -12,28 +14,33 @@ Fix 4 CLI/TUI polish bugs in a single PR (issues #192, #193, #194, #199).
 ## Plan and Fixes
 
 ### Bug #192 — Ctrl+T character leak
+
 - Location: `packages/cli/src/tui/app.tsx`
 - Fix: Added `ctrlJustFired` ref. Set synchronously in Ctrl+T/L/N/K handlers, cleared via microtask.
   In the `onChange` wrapper passed to `InputBar`, if `ctrlJustFired.current` is true, suppress the
   leaked character and return early.
 
 ### Bug #193 — Duplicate React keys
+
 - Location: `packages/cli/src/tui/components/command-autocomplete.tsx`
 - Fix: Changed `key={cmd.name}` to `key={`${cmd.execution}-${cmd.name}`}` for uniqueness.
 - Also: `packages/cli/src/tui/commands/registry.ts` — `getAll()` now deduplicates gateway commands
   that share a name with local commands. Local commands take precedence.
 
 ### Bug #194 — False clipboard claim
+
 - Location: `apps/gateway/src/commands/command-executor.service.ts`
 - Fix: Removed the `\n\n(URL copied to clipboard)` suffix from the provider login message.
 
 ### Bug #199 — Hardcoded version "0.0.0"
+
 - Location: `packages/cli/src/cli.ts` + `packages/cli/src/tui/app.tsx`
 - Fix: `cli.ts` reads version from `../package.json` via `createRequire`. Passes `version: CLI_VERSION`
   to TuiApp in both render calls. TuiApp has new optional `version` prop (defaults to '0.0.0'),
   passes it to TopBar instead of hardcoded `"0.0.0"`.
 
 ## Quality Gates
+
 - CLI typecheck: PASSED
 - CLI lint: PASSED
 - Prettier format:check: PASSED
diff --git a/docs/scratchpads/p8-001-sso-providers.md b/docs/scratchpads/p8-001-sso-providers.md
new file mode 100644
index 0000000..f903753
--- /dev/null
+++ b/docs/scratchpads/p8-001-sso-providers.md
@@ -0,0 +1,62 @@
+# P8-001 — WorkOS + Keycloak SSO Providers
+
+**Branch:** feat/p8-001-sso-providers
+**Started:** 2026-03-18
+**Mode:** Delivery
+
+## Objective
+
+Add WorkOS and Keycloak as optional SSO providers to the BetterAuth configuration, following the existing Authentik pattern.
+
+## Scope
+
+| Surface                                  | Change                                                                  |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `packages/auth/src/auth.ts`              | Refactor provider array, add WorkOS + Keycloak conditional registration |
+| `apps/web/src/lib/auth-client.ts`        | Add `genericOAuthClient()` plugin                                       |
+| `apps/web/src/app/(auth)/login/page.tsx` | WorkOS + Keycloak SSO buttons gated by `NEXT_PUBLIC_*` env vars         |
+| `.env.example`                           | Document WorkOS + Keycloak env vars                                     |
+| `packages/auth/src/auth.test.ts`         | Unit tests verifying env-var gating                                     |
+
+## Plan
+
+1. ✅ Refactor `createAuth` to build `oauthProviders[]` conditionally
+2. ✅ Add WorkOS provider (explicit URLs, no discovery)
+3. ✅ Add Keycloak provider (discoveryUrl pattern)
+4. ✅ Add `genericOAuthClient()` to auth-client.ts
+5. ✅ Add SSO buttons to login page gated by `NEXT_PUBLIC_WORKOS_ENABLED` / `NEXT_PUBLIC_KEYCLOAK_ENABLED`
+6. ✅ Update `.env.example`
+7. ⏳ Write `auth.test.ts` with env-var gating tests
+8. ⏳ Quality gates: typecheck + lint + format:check + test
+9. ⏳ Commit + push + PR
+
+## Decisions
+
+- **WorkOS**: Uses explicit `authorizationUrl`, `tokenUrl`, `userInfoUrl` (no discovery endpoint available)
+- **Keycloak**: Uses `discoveryUrl` pattern (`{URL}/realms/{REALM}/.well-known/openid-configuration`)
+- **UI gating**: Login page uses `NEXT_PUBLIC_WORKOS_ENABLED` / `NEXT_PUBLIC_KEYCLOAK_ENABLED` feature flags (safer than exposing secret env var names client-side)
+- **Refactor**: Authentik moved into same `oauthProviders[]` array pattern — cleaner, more extensible
+- **Feature flag design**: `NEXT_PUBLIC_*` flags are opt-in alongside credentials (prevents accidental button render when creds not set)
+
+## Assumptions
+
+- `ASSUMPTION:` WorkOS OIDC discovery URL is not publicly documented; using direct URL pattern from WorkOS SSO docs.
+- `ASSUMPTION:` `NEXT_PUBLIC_WORKOS_ENABLED=true` must be explicitly set — this is intentional (credential presence alone doesn't enable the button since NEXT_PUBLIC vars are baked at build time).
+
+## Tests
+
+- `auth.test.ts`: Mocks betterAuth stack, verifies WorkOS included/excluded based on env var
+- `auth.test.ts`: Verifies Keycloak discoveryUrl constructed correctly
+
+## Quality Gate Results
+
+| Gate                | Status |
+| ------------------- | ------ |
+| typecheck           | ⏳     |
+| lint                | ⏳     |
+| format:check        | ⏳     |
+| test (@mosaic/auth) | ⏳     |
+
+## Verification Evidence
+
+⏳ Pending

From 307bb427d68fcf7f3374b0d6775626ff092e8764 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Wed, 18 Mar 2026 21:18:48 -0500
Subject: [PATCH 3/4] chore: add P8-001 scratchpad

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/scratchpads/p8-001-sso-providers.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/scratchpads/p8-001-sso-providers.md b/docs/scratchpads/p8-001-sso-providers.md
index f903753..92ed1b3 100644
--- a/docs/scratchpads/p8-001-sso-providers.md
+++ b/docs/scratchpads/p8-001-sso-providers.md
@@ -50,13 +50,16 @@ Add WorkOS and Keycloak as optional SSO providers to the BetterAuth configuratio
 
 ## Quality Gate Results
 
-| Gate                | Status |
-| ------------------- | ------ |
-| typecheck           | ⏳     |
-| lint                | ⏳     |
-| format:check        | ⏳     |
-| test (@mosaic/auth) | ⏳     |
+| Gate                | Status                                       |
+| ------------------- | -------------------------------------------- |
+| typecheck           | ✅ 32/32 cached green                        |
+| lint                | ✅ 18/18 cached green                        |
+| format:check        | ✅ All matched files use Prettier code style |
+| test (@mosaic/auth) | ✅ 8/8 tests passed                          |
 
 ## Verification Evidence
 
-⏳ Pending
+- `pnpm typecheck` — FULL TURBO, 32 tasks successful
+- `pnpm lint` — FULL TURBO, 18 tasks successful
+- `pnpm format:check` — All matched files use Prettier code style!
+- `pnpm --filter=@mosaic/auth test` — 8 tests passed, 0 failed

From 77ba13b41b4b33a092ec4f3c6b5051d0a00f4839 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Thu, 19 Mar 2026 20:30:00 -0500
Subject: [PATCH 4/4] feat(auth): add WorkOS and Keycloak SSO providers

---
 .env.example                                  |   4 +-
 apps/web/src/app/(auth)/login/page.tsx        |  48 ++------
 .../src/app/auth/provider/[provider]/page.tsx |  77 ++++++++++++
 apps/web/src/lib/sso-providers.test.ts        |  48 ++++++++
 apps/web/src/lib/sso-providers.ts             |  53 +++++++++
 docs/SSO-PROVIDERS.md                         | 111 ++++++++++++++++++
 packages/auth/src/auth.test.ts                |  88 ++++++++++----
 packages/auth/src/auth.ts                     | 108 +++++++++++++----
 8 files changed, 454 insertions(+), 83 deletions(-)
 create mode 100644 apps/web/src/app/auth/provider/[provider]/page.tsx
 create mode 100644 apps/web/src/lib/sso-providers.test.ts
 create mode 100644 apps/web/src/lib/sso-providers.ts
 create mode 100644 docs/SSO-PROVIDERS.md

diff --git a/.env.example b/.env.example
index 7132b24..0c31214 100644
--- a/.env.example
+++ b/.env.example
@@ -131,11 +131,13 @@ OTEL_SERVICE_NAME=mosaic-gateway
 # AUTHENTIK_CLIENT_SECRET=
 
 # --- WorkOS (optional — set WORKOS_CLIENT_ID to enable) ---
+# WORKOS_ISSUER=https://your-company.authkit.app
 # WORKOS_CLIENT_ID=client_...
 # WORKOS_CLIENT_SECRET=sk_live_...
-# WORKOS_REDIRECT_URI=http://localhost:3000/api/auth/callback/workos
 
 # --- Keycloak (optional — set KEYCLOAK_CLIENT_ID to enable) ---
+# KEYCLOAK_ISSUER=https://auth.example.com/realms/master
+# Legacy alternative if you prefer to compose the issuer from separate vars:
 # KEYCLOAK_URL=https://auth.example.com
 # KEYCLOAK_REALM=master
 # KEYCLOAK_CLIENT_ID=mosaic
diff --git a/apps/web/src/app/(auth)/login/page.tsx b/apps/web/src/app/(auth)/login/page.tsx
index 836e062..9dfd8d4 100644
--- a/apps/web/src/app/(auth)/login/page.tsx
+++ b/apps/web/src/app/(auth)/login/page.tsx
@@ -1,18 +1,17 @@
 'use client';
 
-import { useState } from 'react';
-import { useRouter } from 'next/navigation';
 import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useState } from 'react';
 import { signIn } from '@/lib/auth-client';
-
-const workosEnabled = process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
-const keycloakEnabled = process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
-const hasSsoProviders = workosEnabled || keycloakEnabled;
+import { getEnabledSsoProviders } from '@/lib/sso-providers';
 
 export default function LoginPage(): React.ReactElement {
   const router = useRouter();
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
+  const ssoProviders = getEnabledSsoProviders();
+  const hasSsoProviders = ssoProviders.length > 0;
 
   async function handleSubmit(e: React.FormEvent<HTMLFormElement>): Promise<void> {
     e.preventDefault();
@@ -34,16 +33,6 @@ export default function LoginPage(): React.ReactElement {
     router.push('/chat');
   }
 
-  async function handleSsoSignIn(providerId: string): Promise<void> {
-    setError(null);
-    setLoading(true);
-    const result = await signIn.oauth2({ providerId, callbackURL: '/chat' });
-    if (result?.error) {
-      setError(result.error.message ?? 'SSO sign in failed');
-      setLoading(false);
-    }
-  }
-
   return (
     <div>
       <h1 className="text-2xl font-semibold">Sign in</h1>
@@ -60,26 +49,15 @@ export default function LoginPage(): React.ReactElement {
 
       {hasSsoProviders && (
         <div className="mt-6 space-y-3">
-          {workosEnabled && (
-            <button
-              type="button"
-              disabled={loading}
-              onClick={() => handleSsoSignIn('workos')}
-              className="flex w-full items-center justify-center gap-2 rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:bg-surface-hover focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+          {ssoProviders.map((provider) => (
+            <Link
+              key={provider.id}
+              href={provider.href}
+              className="flex w-full items-center justify-center gap-2 rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:bg-surface-hover focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card"
             >
-              Continue with WorkOS
-            </button>
-          )}
-          {keycloakEnabled && (
-            <button
-              type="button"
-              disabled={loading}
-              onClick={() => handleSsoSignIn('keycloak')}
-              className="flex w-full items-center justify-center gap-2 rounded-lg border border-surface-border bg-surface-elevated px-4 py-2.5 text-sm font-medium text-text-primary transition-colors hover:bg-surface-hover focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
-            >
-              Continue with Keycloak
-            </button>
-          )}
+              {provider.buttonLabel}
+            </Link>
+          ))}
           <div className="relative flex items-center">
             <div className="flex-1 border-t border-surface-border" />
             <span className="mx-3 text-xs text-text-muted">or</span>
diff --git a/apps/web/src/app/auth/provider/[provider]/page.tsx b/apps/web/src/app/auth/provider/[provider]/page.tsx
new file mode 100644
index 0000000..b4eebce
--- /dev/null
+++ b/apps/web/src/app/auth/provider/[provider]/page.tsx
@@ -0,0 +1,77 @@
+'use client';
+
+import Link from 'next/link';
+import { useEffect, useState } from 'react';
+import { useParams, useSearchParams } from 'next/navigation';
+import { signIn } from '@/lib/auth-client';
+import { getSsoProvider } from '@/lib/sso-providers';
+
+export default function AuthProviderRedirectPage(): React.ReactElement {
+  const params = useParams<{ provider: string }>();
+  const searchParams = useSearchParams();
+  const providerId = typeof params.provider === 'string' ? params.provider : '';
+  const provider = getSsoProvider(providerId);
+  const callbackURL = searchParams.get('callbackURL') ?? '/chat';
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const currentProvider = provider;
+
+    if (!currentProvider) {
+      setError('Unknown SSO provider.');
+      return;
+    }
+
+    if (!currentProvider.enabled) {
+      setError(`${currentProvider.buttonLabel} is not enabled in this deployment.`);
+      return;
+    }
+
+    const activeProvider = currentProvider;
+    let cancelled = false;
+
+    async function redirectToProvider(): Promise<void> {
+      const result = await signIn.oauth2({
+        providerId: activeProvider.id,
+        callbackURL,
+      });
+
+      if (!cancelled && result?.error) {
+        setError(result.error.message ?? `${activeProvider.buttonLabel} sign in failed.`);
+      }
+    }
+
+    void redirectToProvider();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [callbackURL, provider]);
+
+  return (
+    <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
+      <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
+      <p className="mt-2 text-sm text-text-secondary">
+        {provider
+          ? `Redirecting you to ${provider.buttonLabel.replace('Continue with ', '')}...`
+          : 'Preparing your sign-in request...'}
+      </p>
+
+      {error ? (
+        <div className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error">
+          <p>{error}</p>
+          <Link
+            href="/login"
+            className="mt-3 inline-block font-medium text-blue-400 hover:text-blue-300"
+          >
+            Return to login
+          </Link>
+        </div>
+      ) : (
+        <div className="mt-6 rounded-lg border border-surface-border bg-surface-elevated px-4 py-3 text-sm text-text-secondary">
+          If the redirect does not start automatically, return to the login page and try again.
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/web/src/lib/sso-providers.test.ts b/apps/web/src/lib/sso-providers.test.ts
new file mode 100644
index 0000000..076d32b
--- /dev/null
+++ b/apps/web/src/lib/sso-providers.test.ts
@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getEnabledSsoProviders, getSsoProvider } from './sso-providers';
+
+describe('sso-providers', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns the enabled providers in login button order', () => {
+    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
+    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'true');
+
+    expect(getEnabledSsoProviders()).toEqual([
+      {
+        id: 'workos',
+        buttonLabel: 'Continue with WorkOS',
+        description: 'Enterprise SSO via WorkOS',
+        enabled: true,
+        href: '/auth/provider/workos',
+      },
+      {
+        id: 'keycloak',
+        buttonLabel: 'Continue with Keycloak',
+        description: 'Enterprise SSO via Keycloak',
+        enabled: true,
+        href: '/auth/provider/keycloak',
+      },
+    ]);
+  });
+
+  it('marks disabled providers without exposing them in the enabled list', () => {
+    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
+    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'false');
+
+    expect(getEnabledSsoProviders().map((provider) => provider.id)).toEqual(['workos']);
+    expect(getSsoProvider('keycloak')).toEqual({
+      id: 'keycloak',
+      buttonLabel: 'Continue with Keycloak',
+      description: 'Enterprise SSO via Keycloak',
+      enabled: false,
+      href: '/auth/provider/keycloak',
+    });
+  });
+
+  it('returns null for unknown providers', () => {
+    expect(getSsoProvider('authentik')).toBeNull();
+  });
+});
diff --git a/apps/web/src/lib/sso-providers.ts b/apps/web/src/lib/sso-providers.ts
new file mode 100644
index 0000000..a9f4202
--- /dev/null
+++ b/apps/web/src/lib/sso-providers.ts
@@ -0,0 +1,53 @@
+export type SsoProviderId = 'workos' | 'keycloak';
+
+export interface SsoProvider {
+  id: SsoProviderId;
+  buttonLabel: string;
+  description: string;
+  enabled: boolean;
+  href: string;
+}
+
+const PROVIDER_METADATA: Record<SsoProviderId, Omit<SsoProvider, 'enabled' | 'href'>> = {
+  workos: {
+    id: 'workos',
+    buttonLabel: 'Continue with WorkOS',
+    description: 'Enterprise SSO via WorkOS',
+  },
+  keycloak: {
+    id: 'keycloak',
+    buttonLabel: 'Continue with Keycloak',
+    description: 'Enterprise SSO via Keycloak',
+  },
+};
+
+export function getEnabledSsoProviders(): SsoProvider[] {
+  return (Object.keys(PROVIDER_METADATA) as SsoProviderId[])
+    .map((providerId) => getSsoProvider(providerId))
+    .filter((provider): provider is SsoProvider => provider?.enabled === true);
+}
+
+export function getSsoProvider(providerId: string): SsoProvider | null {
+  if (!isSsoProviderId(providerId)) {
+    return null;
+  }
+
+  return {
+    ...PROVIDER_METADATA[providerId],
+    enabled: isSsoProviderEnabled(providerId),
+    href: `/auth/provider/${providerId}`,
+  };
+}
+
+function isSsoProviderId(value: string): value is SsoProviderId {
+  return value === 'workos' || value === 'keycloak';
+}
+
+function isSsoProviderEnabled(providerId: SsoProviderId): boolean {
+  switch (providerId) {
+    case 'workos':
+      return process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
+    case 'keycloak':
+      return process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
+  }
+}
diff --git a/docs/SSO-PROVIDERS.md b/docs/SSO-PROVIDERS.md
new file mode 100644
index 0000000..14c8cc5
--- /dev/null
+++ b/docs/SSO-PROVIDERS.md
@@ -0,0 +1,111 @@
+# SSO Providers
+
+Mosaic Stack supports optional enterprise single sign-on through Better Auth's generic OAuth flow. The gateway mounts Better Auth under `/api/auth`, so every provider callback terminates at:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/{providerId}
+```
+
+For the providers in this document:
+
+- Authentik: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/authentik`
+- WorkOS: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos`
+- Keycloak: `{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak`
+
+## Required environment variables
+
+### Authentik
+
+```bash
+AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic
+AUTHENTIK_CLIENT_ID=...
+AUTHENTIK_CLIENT_SECRET=...
+```
+
+### WorkOS
+
+```bash
+WORKOS_ISSUER=https://your-company.authkit.app
+WORKOS_CLIENT_ID=client_...
+WORKOS_CLIENT_SECRET=...
+NEXT_PUBLIC_WORKOS_ENABLED=true
+```
+
+`WORKOS_ISSUER` should be the WorkOS AuthKit issuer or custom auth domain, not the raw REST API hostname. Mosaic derives the OIDC discovery URL from that issuer.
+
+### Keycloak
+
+```bash
+KEYCLOAK_ISSUER=https://auth.example.com/realms/master
+KEYCLOAK_CLIENT_ID=mosaic
+KEYCLOAK_CLIENT_SECRET=...
+NEXT_PUBLIC_KEYCLOAK_ENABLED=true
+```
+
+If you prefer, you can keep the issuer split as:
+
+```bash
+KEYCLOAK_URL=https://auth.example.com
+KEYCLOAK_REALM=master
+```
+
+The auth package will derive `KEYCLOAK_ISSUER` from those two values.
+
+## WorkOS setup
+
+1. In WorkOS, create or select the application that will back Mosaic login.
+2. Configure an AuthKit domain or custom authentication domain for the application.
+3. Add the redirect URI:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/workos
+```
+
+4. Copy the application's `client_id` and `client_secret` into `WORKOS_CLIENT_ID` and `WORKOS_CLIENT_SECRET`.
+5. Set `WORKOS_ISSUER` to the AuthKit domain from step 2.
+6. Create the WorkOS organization and attach the enterprise SSO connection you want Mosaic to use.
+7. Set `NEXT_PUBLIC_WORKOS_ENABLED=true` in the web deployment so the login button is rendered.
+
+## Keycloak setup
+
+1. Start from an existing Keycloak realm or create a dedicated realm for Mosaic.
+2. Create a confidential OIDC client named `mosaic` or your preferred client ID.
+3. Set the valid redirect URI to:
+
+```text
+{BETTER_AUTH_URL}/api/auth/oauth2/callback/keycloak
+```
+
+4. Set the web origin to the public Mosaic web URL.
+5. Copy the client secret into `KEYCLOAK_CLIENT_SECRET`.
+6. Set either `KEYCLOAK_ISSUER` directly or `KEYCLOAK_URL` + `KEYCLOAK_REALM`.
+7. Set `NEXT_PUBLIC_KEYCLOAK_ENABLED=true` in the web deployment so the login button is rendered.
+
+### Local Keycloak smoke test
+
+If you want to test locally with Docker:
+
+```bash
+docker run --rm --name mosaic-keycloak \
+  -p 8080:8080 \
+  -e KEYCLOAK_ADMIN=admin \
+  -e KEYCLOAK_ADMIN_PASSWORD=admin \
+  quay.io/keycloak/keycloak:26.1 start-dev
+```
+
+Then configure:
+
+```bash
+KEYCLOAK_ISSUER=http://localhost:8080/realms/master
+KEYCLOAK_CLIENT_ID=mosaic
+KEYCLOAK_CLIENT_SECRET=...
+NEXT_PUBLIC_KEYCLOAK_ENABLED=true
+```
+
+## Web flow
+
+The web login page renders provider buttons from `NEXT_PUBLIC_*_ENABLED` flags. Each button links to `/auth/provider/{providerId}`, and that page initiates Better Auth's `signIn.oauth2` flow before handing off to the provider.
+
+## Failure mode
+
+Provider config is optional, but partial config is rejected at startup. If any provider-specific env var is present without the full required set, `@mosaic/auth` throws a bootstrap error with the missing keys instead of silently registering a broken provider.
diff --git a/packages/auth/src/auth.test.ts b/packages/auth/src/auth.test.ts
index 31b76a8..f752e91 100644
--- a/packages/auth/src/auth.test.ts
+++ b/packages/auth/src/auth.test.ts
@@ -6,14 +6,15 @@ describe('buildOAuthProviders', () => {
 
   beforeEach(() => {
     process.env = { ...originalEnv };
-    // Clear all SSO-related env vars before each test
     delete process.env['AUTHENTIK_CLIENT_ID'];
     delete process.env['AUTHENTIK_CLIENT_SECRET'];
     delete process.env['AUTHENTIK_ISSUER'];
     delete process.env['WORKOS_CLIENT_ID'];
     delete process.env['WORKOS_CLIENT_SECRET'];
+    delete process.env['WORKOS_ISSUER'];
     delete process.env['KEYCLOAK_CLIENT_ID'];
     delete process.env['KEYCLOAK_CLIENT_SECRET'];
+    delete process.env['KEYCLOAK_ISSUER'];
     delete process.env['KEYCLOAK_URL'];
     delete process.env['KEYCLOAK_REALM'];
   });
@@ -28,22 +29,32 @@ describe('buildOAuthProviders', () => {
   });
 
   describe('WorkOS', () => {
-    it('includes workos provider when WORKOS_CLIENT_ID is set', () => {
+    it('includes workos provider when all required env vars are set', () => {
       process.env['WORKOS_CLIENT_ID'] = 'client_test123';
       process.env['WORKOS_CLIENT_SECRET'] = 'sk_live_test';
+      process.env['WORKOS_ISSUER'] = 'https://example.authkit.app/';
 
       const providers = buildOAuthProviders();
       const workos = providers.find((p) => p.providerId === 'workos');
 
       expect(workos).toBeDefined();
       expect(workos?.clientId).toBe('client_test123');
-      expect(workos?.authorizationUrl).toBe('https://api.workos.com/sso/authorize');
-      expect(workos?.tokenUrl).toBe('https://api.workos.com/sso/token');
-      expect(workos?.userInfoUrl).toBe('https://api.workos.com/sso/profile');
+      expect(workos?.issuer).toBe('https://example.authkit.app');
+      expect(workos?.discoveryUrl).toBe(
+        'https://example.authkit.app/.well-known/openid-configuration',
+      );
       expect(workos?.scopes).toEqual(['openid', 'email', 'profile']);
     });
 
-    it('excludes workos provider when WORKOS_CLIENT_ID is not set', () => {
+    it('throws when WorkOS is partially configured', () => {
+      process.env['WORKOS_CLIENT_ID'] = 'client_test123';
+
+      expect(() => buildOAuthProviders()).toThrow(
+        '@mosaic/auth: WorkOS SSO requires WORKOS_ISSUER, WORKOS_CLIENT_ID, WORKOS_CLIENT_SECRET.',
+      );
+    });
+
+    it('excludes workos provider when WorkOS is not configured', () => {
       const providers = buildOAuthProviders();
       const workos = providers.find((p) => p.providerId === 'workos');
       expect(workos).toBeUndefined();
@@ -51,47 +62,78 @@ describe('buildOAuthProviders', () => {
   });
 
   describe('Keycloak', () => {
-    it('includes keycloak provider when KEYCLOAK_CLIENT_ID is set', () => {
+    it('includes keycloak provider when KEYCLOAK_ISSUER is set', () => {
       process.env['KEYCLOAK_CLIENT_ID'] = 'mosaic';
       process.env['KEYCLOAK_CLIENT_SECRET'] = 'secret123';
-      process.env['KEYCLOAK_URL'] = 'https://auth.example.com';
+      process.env['KEYCLOAK_ISSUER'] = 'https://auth.example.com/realms/myrealm/';
+
+      const providers = buildOAuthProviders();
+      const keycloakProvider = providers.find((p) => p.providerId === 'keycloak');
+
+      expect(keycloakProvider).toBeDefined();
+      expect(keycloakProvider?.clientId).toBe('mosaic');
+      expect(keycloakProvider?.discoveryUrl).toBe(
+        'https://auth.example.com/realms/myrealm/.well-known/openid-configuration',
+      );
+      expect(keycloakProvider?.scopes).toEqual(['openid', 'email', 'profile']);
+    });
+
+    it('supports deriving the Keycloak issuer from KEYCLOAK_URL and KEYCLOAK_REALM', () => {
+      process.env['KEYCLOAK_CLIENT_ID'] = 'mosaic';
+      process.env['KEYCLOAK_CLIENT_SECRET'] = 'secret123';
+      process.env['KEYCLOAK_URL'] = 'https://auth.example.com/';
       process.env['KEYCLOAK_REALM'] = 'myrealm';
 
       const providers = buildOAuthProviders();
-      const keycloak = providers.find((p) => p.providerId === 'keycloak');
+      const keycloakProvider = providers.find((p) => p.providerId === 'keycloak');
 
-      expect(keycloak).toBeDefined();
-      expect(keycloak?.clientId).toBe('mosaic');
-      expect(keycloak?.discoveryUrl).toBe(
+      expect(keycloakProvider?.discoveryUrl).toBe(
         'https://auth.example.com/realms/myrealm/.well-known/openid-configuration',
       );
-      expect(keycloak?.scopes).toEqual(['openid', 'email', 'profile']);
     });
 
-    it('excludes keycloak provider when KEYCLOAK_CLIENT_ID is not set', () => {
+    it('throws when Keycloak is partially configured', () => {
+      process.env['KEYCLOAK_CLIENT_ID'] = 'mosaic';
+      process.env['KEYCLOAK_CLIENT_SECRET'] = 'secret123';
+
+      expect(() => buildOAuthProviders()).toThrow(
+        '@mosaic/auth: Keycloak SSO requires KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET, KEYCLOAK_ISSUER.',
+      );
+    });
+
+    it('excludes keycloak provider when Keycloak is not configured', () => {
       const providers = buildOAuthProviders();
-      const keycloak = providers.find((p) => p.providerId === 'keycloak');
-      expect(keycloak).toBeUndefined();
+      const keycloakProvider = providers.find((p) => p.providerId === 'keycloak');
+      expect(keycloakProvider).toBeUndefined();
     });
   });
 
   describe('Authentik', () => {
-    it('includes authentik provider when AUTHENTIK_CLIENT_ID is set', () => {
+    it('includes authentik provider when all required env vars are set', () => {
       process.env['AUTHENTIK_CLIENT_ID'] = 'authentik-client';
       process.env['AUTHENTIK_CLIENT_SECRET'] = 'authentik-secret';
-      process.env['AUTHENTIK_ISSUER'] = 'https://auth.example.com/application/o/mosaic';
+      process.env['AUTHENTIK_ISSUER'] = 'https://auth.example.com/application/o/mosaic/';
 
       const providers = buildOAuthProviders();
       const authentik = providers.find((p) => p.providerId === 'authentik');
 
       expect(authentik).toBeDefined();
       expect(authentik?.clientId).toBe('authentik-client');
+      expect(authentik?.issuer).toBe('https://auth.example.com/application/o/mosaic');
       expect(authentik?.discoveryUrl).toBe(
         'https://auth.example.com/application/o/mosaic/.well-known/openid-configuration',
       );
     });
 
-    it('excludes authentik provider when AUTHENTIK_CLIENT_ID is not set', () => {
+    it('throws when Authentik is partially configured', () => {
+      process.env['AUTHENTIK_CLIENT_ID'] = 'authentik-client';
+
+      expect(() => buildOAuthProviders()).toThrow(
+        '@mosaic/auth: Authentik SSO requires AUTHENTIK_ISSUER, AUTHENTIK_CLIENT_ID, AUTHENTIK_CLIENT_SECRET.',
+      );
+    });
+
+    it('excludes authentik provider when Authentik is not configured', () => {
       const providers = buildOAuthProviders();
       const authentik = providers.find((p) => p.providerId === 'authentik');
       expect(authentik).toBeUndefined();
@@ -100,10 +142,14 @@ describe('buildOAuthProviders', () => {
 
   it('registers all three providers when all env vars are set', () => {
     process.env['AUTHENTIK_CLIENT_ID'] = 'a-id';
+    process.env['AUTHENTIK_CLIENT_SECRET'] = 'a-secret';
+    process.env['AUTHENTIK_ISSUER'] = 'https://auth.example.com/application/o/mosaic';
     process.env['WORKOS_CLIENT_ID'] = 'w-id';
+    process.env['WORKOS_CLIENT_SECRET'] = 'w-secret';
+    process.env['WORKOS_ISSUER'] = 'https://example.authkit.app';
     process.env['KEYCLOAK_CLIENT_ID'] = 'k-id';
-    process.env['KEYCLOAK_URL'] = 'https://kc.example.com';
-    process.env['KEYCLOAK_REALM'] = 'test';
+    process.env['KEYCLOAK_CLIENT_SECRET'] = 'k-secret';
+    process.env['KEYCLOAK_ISSUER'] = 'https://kc.example.com/realms/test';
 
     const providers = buildOAuthProviders();
     expect(providers).toHaveLength(3);
diff --git a/packages/auth/src/auth.ts b/packages/auth/src/auth.ts
index 65ae69d..f425564 100644
--- a/packages/auth/src/auth.ts
+++ b/packages/auth/src/auth.ts
@@ -1,7 +1,7 @@
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
-import { admin, genericOAuth } from 'better-auth/plugins';
-import type { GenericOAuthConfig } from 'better-auth/plugins';
+import { admin } from 'better-auth/plugins';
+import { genericOAuth, keycloak, type GenericOAuthConfig } from 'better-auth/plugins/generic-oauth';
 import type { Db } from '@mosaic/db';
 
 export interface AuthConfig {
@@ -14,52 +14,108 @@ export interface AuthConfig {
 export function buildOAuthProviders(): GenericOAuthConfig[] {
   const providers: GenericOAuthConfig[] = [];
 
+  const authentikIssuer = normalizeIssuer(process.env['AUTHENTIK_ISSUER']);
   const authentikClientId = process.env['AUTHENTIK_CLIENT_ID'];
-  if (authentikClientId) {
-    const authentikIssuer = process.env['AUTHENTIK_ISSUER'];
+  const authentikClientSecret = process.env['AUTHENTIK_CLIENT_SECRET'];
+  assertOptionalProviderConfig('Authentik SSO', {
+    required: ['AUTHENTIK_ISSUER', 'AUTHENTIK_CLIENT_ID', 'AUTHENTIK_CLIENT_SECRET'],
+    values: [authentikIssuer, authentikClientId, authentikClientSecret],
+  });
+
+  if (authentikIssuer && authentikClientId && authentikClientSecret) {
     providers.push({
       providerId: 'authentik',
       clientId: authentikClientId,
-      clientSecret: process.env['AUTHENTIK_CLIENT_SECRET'] ?? '',
-      discoveryUrl: authentikIssuer
-        ? `${authentikIssuer}/.well-known/openid-configuration`
-        : undefined,
-      authorizationUrl: authentikIssuer ? `${authentikIssuer}/application/o/authorize/` : undefined,
-      tokenUrl: authentikIssuer ? `${authentikIssuer}/application/o/token/` : undefined,
-      userInfoUrl: authentikIssuer ? `${authentikIssuer}/application/o/userinfo/` : undefined,
+      clientSecret: authentikClientSecret,
+      issuer: authentikIssuer,
+      discoveryUrl: buildDiscoveryUrl(authentikIssuer),
       scopes: ['openid', 'email', 'profile'],
+      requireIssuerValidation: true,
     });
   }
 
+  const workosIssuer = normalizeIssuer(process.env['WORKOS_ISSUER']);
   const workosClientId = process.env['WORKOS_CLIENT_ID'];
-  if (workosClientId) {
+  const workosClientSecret = process.env['WORKOS_CLIENT_SECRET'];
+  assertOptionalProviderConfig('WorkOS SSO', {
+    required: ['WORKOS_ISSUER', 'WORKOS_CLIENT_ID', 'WORKOS_CLIENT_SECRET'],
+    values: [workosIssuer, workosClientId, workosClientSecret],
+  });
+
+  if (workosIssuer && workosClientId && workosClientSecret) {
     providers.push({
       providerId: 'workos',
       clientId: workosClientId,
-      clientSecret: process.env['WORKOS_CLIENT_SECRET'] ?? '',
-      authorizationUrl: 'https://api.workos.com/sso/authorize',
-      tokenUrl: 'https://api.workos.com/sso/token',
-      userInfoUrl: 'https://api.workos.com/sso/profile',
+      clientSecret: workosClientSecret,
+      issuer: workosIssuer,
+      discoveryUrl: buildDiscoveryUrl(workosIssuer),
       scopes: ['openid', 'email', 'profile'],
+      requireIssuerValidation: true,
     });
   }
 
+  const keycloakIssuer = resolveKeycloakIssuer();
   const keycloakClientId = process.env['KEYCLOAK_CLIENT_ID'];
-  if (keycloakClientId) {
-    const keycloakUrl = process.env['KEYCLOAK_URL'] ?? '';
-    const keycloakRealm = process.env['KEYCLOAK_REALM'] ?? '';
-    providers.push({
-      providerId: 'keycloak',
-      clientId: keycloakClientId,
-      clientSecret: process.env['KEYCLOAK_CLIENT_SECRET'] ?? '',
-      discoveryUrl: `${keycloakUrl}/realms/${keycloakRealm}/.well-known/openid-configuration`,
-      scopes: ['openid', 'email', 'profile'],
-    });
+  const keycloakClientSecret = process.env['KEYCLOAK_CLIENT_SECRET'];
+  assertOptionalProviderConfig('Keycloak SSO', {
+    required: ['KEYCLOAK_CLIENT_ID', 'KEYCLOAK_CLIENT_SECRET', 'KEYCLOAK_ISSUER'],
+    values: [keycloakClientId, keycloakClientSecret, keycloakIssuer],
+  });
+
+  if (keycloakIssuer && keycloakClientId && keycloakClientSecret) {
+    providers.push(
+      keycloak({
+        clientId: keycloakClientId,
+        clientSecret: keycloakClientSecret,
+        issuer: keycloakIssuer,
+        scopes: ['openid', 'email', 'profile'],
+      }),
+    );
   }
 
   return providers;
 }
 
+function resolveKeycloakIssuer(): string | undefined {
+  const issuer = normalizeIssuer(process.env['KEYCLOAK_ISSUER']);
+  if (issuer) {
+    return issuer;
+  }
+
+  const baseUrl = normalizeIssuer(process.env['KEYCLOAK_URL']);
+  const realm = process.env['KEYCLOAK_REALM']?.trim();
+
+  if (!baseUrl || !realm) {
+    return undefined;
+  }
+
+  return `${baseUrl}/realms/${realm}`;
+}
+
+function buildDiscoveryUrl(issuer: string): string {
+  return `${issuer}/.well-known/openid-configuration`;
+}
+
+function normalizeIssuer(value: string | undefined): string | undefined {
+  return value?.trim().replace(/\/+$/, '') || undefined;
+}
+
+function assertOptionalProviderConfig(
+  providerName: string,
+  config: { required: string[]; values: Array<string | undefined> },
+): void {
+  const hasAnyValue = config.values.some((value) => Boolean(value?.trim()));
+  const hasAllValues = config.values.every((value) => Boolean(value?.trim()));
+
+  if (!hasAnyValue || hasAllValues) {
+    return;
+  }
+
+  throw new Error(
+    `@mosaic/auth: ${providerName} requires ${config.required.join(', ')}. Set them in your config or via the listed environment variables.`,
+  );
+}
+
 export function createAuth(config: AuthConfig) {
   const { db, baseURL, secret } = config;