feat(auth): add WorkOS and Keycloak SSO providers (rebased) (#220)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/auth/src/auth.ts

@@ -1,8 +1,9 @@
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
 import { admin } from 'better-auth/plugins';
-import { genericOAuth, keycloak, type GenericOAuthConfig } from 'better-auth/plugins/generic-oauth';
+import { genericOAuth, type GenericOAuthConfig } from 'better-auth/plugins/generic-oauth';
 import type { Db } from '@mosaic/db';
+import { buildGenericOidcProviderConfigs } from './sso.js';
 
 export interface AuthConfig {
   db: Db;
@@ -10,118 +11,21 @@ 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 authentikIssuer = normalizeIssuer(process.env['AUTHENTIK_ISSUER']);
-  const authentikClientId = process.env['AUTHENTIK_CLIENT_ID'];
-  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: 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'];
-  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: workosClientSecret,
-      issuer: workosIssuer,
-      discoveryUrl: buildDiscoveryUrl(workosIssuer),
-      scopes: ['openid', 'email', 'profile'],
-      requireIssuerValidation: true,
-    });
-  }
-
-  const keycloakIssuer = resolveKeycloakIssuer();
-  const keycloakClientId = process.env['KEYCLOAK_CLIENT_ID'];
-  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.`,
-  );
+  return buildGenericOidcProviderConfigs() as GenericOAuthConfig[];
 }
 
 export function createAuth(config: AuthConfig) {
   const { db, baseURL, secret } = config;
-
-  const oauthProviders = buildOAuthProviders();
+  const oidcConfigs = buildOAuthProviders();
   const plugins =
-    oauthProviders.length > 0 ? [genericOAuth({ config: oauthProviders })] : undefined;
+    oidcConfigs.length > 0
+      ? [
+          genericOAuth({
+            config: oidcConfigs,
+          }),
+        ]
+      : undefined;
 
   const corsOrigin = process.env['GATEWAY_CORS_ORIGIN'] ?? 'http://localhost:3000';
   const trustedOrigins = corsOrigin.split(',').map((o) => o.trim());

packages/auth/src/index.ts

@@ -1 +1,12 @@
 export { createAuth, type Auth, type AuthConfig } from './auth.js';
+export {
+  buildGenericOidcProviderConfigs,
+  buildSsoDiscovery,
+  listSsoStartupWarnings,
+  type GenericOidcProviderConfig,
+  type SsoLoginMode,
+  type SsoProtocol,
+  type SsoProviderDiscovery,
+  type SsoTeamSyncConfig,
+  type SupportedSsoProviderId,
+} from './sso.js';

packages/auth/src/sso.spec.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildGenericOidcProviderConfigs,
+  buildSsoDiscovery,
+  listSsoStartupWarnings,
+} from './sso.js';
+
+describe('SSO provider config helpers', () => {
+  it('builds OIDC configs for Authentik, WorkOS, and Keycloak when fully configured', () => {
+    const configs = buildGenericOidcProviderConfigs({
+      AUTHENTIK_CLIENT_ID: 'authentik-client',
+      AUTHENTIK_CLIENT_SECRET: 'authentik-secret',
+      AUTHENTIK_ISSUER: 'https://authentik.example.com',
+      WORKOS_CLIENT_ID: 'workos-client',
+      WORKOS_CLIENT_SECRET: 'workos-secret',
+      WORKOS_ISSUER: 'https://auth.workos.com/sso/client_123',
+      KEYCLOAK_CLIENT_ID: 'keycloak-client',
+      KEYCLOAK_CLIENT_SECRET: 'keycloak-secret',
+      KEYCLOAK_ISSUER: 'https://sso.example.com/realms/mosaic',
+    });
+
+    expect(configs.map((config) => config.providerId)).toEqual(['authentik', 'workos', 'keycloak']);
+    expect(configs.find((config) => config.providerId === 'workos')).toMatchObject({
+      discoveryUrl: 'https://auth.workos.com/sso/client_123/.well-known/openid-configuration',
+      pkce: true,
+      requireIssuerValidation: true,
+    });
+    expect(configs.find((config) => config.providerId === 'keycloak')).toMatchObject({
+      discoveryUrl: 'https://sso.example.com/realms/mosaic/.well-known/openid-configuration',
+      pkce: true,
+    });
+  });
+
+  it('exposes Keycloak SAML fallback when OIDC is not configured', () => {
+    const providers = buildSsoDiscovery({
+      KEYCLOAK_SAML_LOGIN_URL: 'https://sso.example.com/realms/mosaic/protocol/saml',
+    });
+
+    expect(providers.find((provider) => provider.id === 'keycloak')).toMatchObject({
+      configured: true,
+      loginMode: 'saml',
+      samlFallback: {
+        configured: true,
+        loginUrl: 'https://sso.example.com/realms/mosaic/protocol/saml',
+      },
+    });
+  });
+
+  it('reports partial provider configuration as startup warnings', () => {
+    const warnings = listSsoStartupWarnings({
+      WORKOS_CLIENT_ID: 'workos-client',
+      KEYCLOAK_CLIENT_ID: 'keycloak-client',
+    });
+
+    expect(warnings).toContain(
+      'workos OIDC is partially configured. Missing: WORKOS_CLIENT_SECRET, WORKOS_ISSUER',
+    );
+    expect(warnings).toContain(
+      'keycloak OIDC is partially configured. Missing: KEYCLOAK_CLIENT_SECRET, KEYCLOAK_ISSUER',
+    );
+  });
+});

packages/auth/src/sso.ts

@@ -0,0 +1,241 @@
+export type SupportedSsoProviderId = 'authentik' | 'workos' | 'keycloak';
+export type SsoProtocol = 'oidc' | 'saml';
+export type SsoLoginMode = 'oidc' | 'saml' | null;
+
+type EnvMap = Record<string, string | undefined>;
+
+export interface GenericOidcProviderConfig {
+  providerId: SupportedSsoProviderId;
+  clientId: string;
+  clientSecret: string;
+  discoveryUrl?: string;
+  issuer?: string;
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  userInfoUrl?: string;
+  scopes: string[];
+  pkce?: boolean;
+  requireIssuerValidation?: boolean;
+}
+
+export interface SsoTeamSyncConfig {
+  enabled: boolean;
+  claim: string | null;
+}
+
+export interface SsoProviderDiscovery {
+  id: SupportedSsoProviderId;
+  name: string;
+  protocols: SsoProtocol[];
+  configured: boolean;
+  loginMode: SsoLoginMode;
+  callbackPath: string | null;
+  teamSync: SsoTeamSyncConfig;
+  samlFallback: {
+    configured: boolean;
+    loginUrl: string | null;
+  };
+  warnings: string[];
+}
+
+const DEFAULT_SCOPES = ['openid', 'email', 'profile'];
+
+function readEnv(env: EnvMap, key: string): string | undefined {
+  const value = env[key]?.trim();
+  return value ? value : undefined;
+}
+
+function toDiscoveryUrl(issuer: string): string {
+  return `${issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+}
+
+function getTeamSyncClaim(env: EnvMap, envKey: string, fallbackClaim?: string): SsoTeamSyncConfig {
+  const claim = readEnv(env, envKey) ?? fallbackClaim ?? null;
+  return {
+    enabled: claim !== null,
+    claim,
+  };
+}
+
+function buildAuthentikConfig(env: EnvMap): GenericOidcProviderConfig | null {
+  const issuer = readEnv(env, 'AUTHENTIK_ISSUER');
+  const clientId = readEnv(env, 'AUTHENTIK_CLIENT_ID');
+  const clientSecret = readEnv(env, 'AUTHENTIK_CLIENT_SECRET');
+
+  const fields = [issuer, clientId, clientSecret];
+  const presentCount = fields.filter(Boolean).length;
+  if (presentCount > 0 && presentCount < fields.length) {
+    throw new Error(
+      '@mosaic/auth: Authentik SSO requires AUTHENTIK_ISSUER, AUTHENTIK_CLIENT_ID, AUTHENTIK_CLIENT_SECRET.',
+    );
+  }
+  if (!issuer || !clientId || !clientSecret) {
+    return null;
+  }
+
+  const baseIssuer = issuer.replace(/\/$/, '');
+
+  return {
+    providerId: 'authentik',
+    issuer: baseIssuer,
+    clientId,
+    clientSecret,
+    discoveryUrl: toDiscoveryUrl(baseIssuer),
+    authorizationUrl: `${baseIssuer}/application/o/authorize/`,
+    tokenUrl: `${baseIssuer}/application/o/token/`,
+    userInfoUrl: `${baseIssuer}/application/o/userinfo/`,
+    scopes: DEFAULT_SCOPES,
+  };
+}
+
+function buildWorkosConfig(env: EnvMap): GenericOidcProviderConfig | null {
+  const issuer = readEnv(env, 'WORKOS_ISSUER');
+  const clientId = readEnv(env, 'WORKOS_CLIENT_ID');
+  const clientSecret = readEnv(env, 'WORKOS_CLIENT_SECRET');
+
+  const fields = [issuer, clientId, clientSecret];
+  const presentCount = fields.filter(Boolean).length;
+  if (presentCount > 0 && presentCount < fields.length) {
+    throw new Error(
+      '@mosaic/auth: WorkOS SSO requires WORKOS_ISSUER, WORKOS_CLIENT_ID, WORKOS_CLIENT_SECRET.',
+    );
+  }
+  if (!issuer || !clientId || !clientSecret) {
+    return null;
+  }
+
+  const normalizedIssuer = issuer.replace(/\/$/, '');
+
+  return {
+    providerId: 'workos',
+    issuer: normalizedIssuer,
+    clientId,
+    clientSecret,
+    discoveryUrl: toDiscoveryUrl(normalizedIssuer),
+    scopes: DEFAULT_SCOPES,
+    pkce: true,
+    requireIssuerValidation: true,
+  };
+}
+
+function buildKeycloakConfig(env: EnvMap): GenericOidcProviderConfig | null {
+  const explicitIssuer = readEnv(env, 'KEYCLOAK_ISSUER');
+  const keycloakUrl = readEnv(env, 'KEYCLOAK_URL');
+  const keycloakRealm = readEnv(env, 'KEYCLOAK_REALM');
+  const clientId = readEnv(env, 'KEYCLOAK_CLIENT_ID');
+  const clientSecret = readEnv(env, 'KEYCLOAK_CLIENT_SECRET');
+
+  // Derive issuer from KEYCLOAK_URL + KEYCLOAK_REALM if KEYCLOAK_ISSUER not set
+  const issuer =
+    explicitIssuer ??
+    (keycloakUrl && keycloakRealm
+      ? `${keycloakUrl.replace(/\/$/, '')}/realms/${keycloakRealm}`
+      : undefined);
+
+  const anySet = !!(issuer || clientId || clientSecret);
+  if (anySet && (!issuer || !clientId || !clientSecret)) {
+    throw new Error(
+      '@mosaic/auth: Keycloak SSO requires KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET, KEYCLOAK_ISSUER.',
+    );
+  }
+  if (!issuer || !clientId || !clientSecret) {
+    return null;
+  }
+
+  const normalizedIssuer = issuer.replace(/\/$/, '');
+
+  return {
+    providerId: 'keycloak',
+    issuer: normalizedIssuer,
+    clientId,
+    clientSecret,
+    discoveryUrl: toDiscoveryUrl(normalizedIssuer),
+    scopes: DEFAULT_SCOPES,
+    pkce: true,
+    requireIssuerValidation: true,
+  };
+}
+
+function collectWarnings(env: EnvMap, provider: SupportedSsoProviderId): string[] {
+  const prefix = provider.toUpperCase();
+  const oidcFields = [
+    `${prefix}_CLIENT_ID`,
+    `${prefix}_CLIENT_SECRET`,
+    `${prefix}_ISSUER`,
+  ] as const;
+  const presentOidcFields = oidcFields.filter((field) => readEnv(env, field));
+  const warnings: string[] = [];
+
+  if (presentOidcFields.length > 0 && presentOidcFields.length < oidcFields.length) {
+    const missing = oidcFields.filter((field) => !readEnv(env, field));
+    warnings.push(`${provider} OIDC is partially configured. Missing: ${missing.join(', ')}`);
+  }
+
+  return warnings;
+}
+
+export function buildGenericOidcProviderConfigs(
+  env: EnvMap = process.env,
+): GenericOidcProviderConfig[] {
+  return [buildAuthentikConfig(env), buildWorkosConfig(env), buildKeycloakConfig(env)].filter(
+    (config): config is GenericOidcProviderConfig => config !== null,
+  );
+}
+
+export function listSsoStartupWarnings(env: EnvMap = process.env): string[] {
+  return ['authentik', 'workos', 'keycloak'].flatMap((provider) =>
+    collectWarnings(env, provider as SupportedSsoProviderId),
+  );
+}
+
+export function buildSsoDiscovery(env: EnvMap = process.env): SsoProviderDiscovery[] {
+  const oidcConfigs = new Map(
+    buildGenericOidcProviderConfigs(env).map((config) => [config.providerId, config]),
+  );
+  const keycloakSamlLoginUrl = readEnv(env, 'KEYCLOAK_SAML_LOGIN_URL') ?? null;
+
+  return [
+    {
+      id: 'authentik',
+      name: 'Authentik',
+      protocols: ['oidc'],
+      configured: oidcConfigs.has('authentik'),
+      loginMode: oidcConfigs.has('authentik') ? 'oidc' : null,
+      callbackPath: oidcConfigs.has('authentik') ? '/api/auth/oauth2/callback/authentik' : null,
+      teamSync: getTeamSyncClaim(env, 'AUTHENTIK_TEAM_SYNC_CLAIM', 'groups'),
+      samlFallback: {
+        configured: false,
+        loginUrl: null,
+      },
+      warnings: collectWarnings(env, 'authentik'),
+    },
+    {
+      id: 'workos',
+      name: 'WorkOS',
+      protocols: ['oidc'],
+      configured: oidcConfigs.has('workos'),
+      loginMode: oidcConfigs.has('workos') ? 'oidc' : null,
+      callbackPath: oidcConfigs.has('workos') ? '/api/auth/oauth2/callback/workos' : null,
+      teamSync: getTeamSyncClaim(env, 'WORKOS_TEAM_SYNC_CLAIM', 'organization_id'),
+      samlFallback: {
+        configured: false,
+        loginUrl: null,
+      },
+      warnings: collectWarnings(env, 'workos'),
+    },
+    {
+      id: 'keycloak',
+      name: 'Keycloak',
+      protocols: ['oidc', 'saml'],
+      configured: oidcConfigs.has('keycloak') || keycloakSamlLoginUrl !== null,
+      loginMode: oidcConfigs.has('keycloak') ? 'oidc' : keycloakSamlLoginUrl ? 'saml' : null,
+      callbackPath: oidcConfigs.has('keycloak') ? '/api/auth/oauth2/callback/keycloak' : null,
+      teamSync: getTeamSyncClaim(env, 'KEYCLOAK_TEAM_SYNC_CLAIM', 'groups'),
+      samlFallback: {
+        configured: keycloakSamlLoginUrl !== null,
+        loginUrl: keycloakSamlLoginUrl,
+      },
+      warnings: collectWarnings(env, 'keycloak'),
+    },
+  ];
+}