feat(auth): @better-auth/sso — per-env external IdP (OIDC/SAML) relying party

os-zhuang · claude · os-zhuang · commit 367bbf4fd7b7 · 2026-06-25T16:21:02.000+08:00
ADR-0024 V1: the OPEN per-env SSO mechanism. Lets an environment federate
login to a customer's own OIDC/SAML IdP (Okta / Entra / Google), registered
at runtime in the env (cloud-free for self-host).

- platform-objects: new `sys_sso_provider` object mirroring @better-auth/sso
  @1.6.20's BaseSSOProvider (issuer, oidc_config/saml_config JSON blobs,
  user_id, provider_id, organization_id, domain); managedBy: better-auth;
  mutations via /api/v1/auth/sso/{register,delete-provider}.
- plugin-auth: AUTH_SSO_PROVIDER_SCHEMA + buildSsoPluginSchema() (camelCase→
  snake_case, per the buildOauthProviderPluginSchema template); auth-manager
  wires sso({ schema }) gated by enabled.sso (OS_SSO_ENABLED, mirrors
  OS_OIDC_PROVIDER_ENABLED).
- package.json: add @better-auth/sso ^1.6.20.

Follow-ups: provisionUser default-role, ssoClient() + admin UI (PR-2).

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/platform-objects/src/identity/index.ts b/packages/platform-objects/src/identity/index.ts
@@ -35,3 +35,6 @@ export { SysOauthAccessToken } from './sys-oauth-access-token.object.js';
 export { SysOauthRefreshToken } from './sys-oauth-refresh-token.object.js';
 export { SysOauthConsent } from './sys-oauth-consent.object.js';
 export { SysJwks } from './sys-jwks.object.js';
+
+// ── External SSO (relying-party, @better-auth/sso) ─────────────────
+export { SysSsoProvider } from './sys-sso-provider.object.js';
diff --git a/packages/platform-objects/src/identity/sys-sso-provider.object.ts b/packages/platform-objects/src/identity/sys-sso-provider.object.ts
@@ -0,0 +1,177 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_sso_provider — Registered external SSO identity provider (OIDC / SAML)
+ *
+ * Backed by `@better-auth/sso`'s `ssoProvider` model. Each row is an external
+ * IdP that THIS environment federates LOGIN to (the relying-party / client
+ * side) — e.g. the customer's Okta / Entra / Google Workspace. This is the
+ * per-environment SSO **mechanism** (ADR-0024): OPEN, configured in the env,
+ * and cloud-free for self-host.
+ *
+ * better-auth stores the protocol detail as a JSON blob in `oidc_config`
+ * (OIDC: clientId, clientSecret, endpoints, scopes, mapping, pkce, …) or
+ * `saml_config` (SAML: entryPoint, cert, identifierFormat, mapping, …) — not
+ * as separate columns. Field set mirrors `@better-auth/sso@1.6.20`'s
+ * `BaseSSOProvider`: issuer, oidcConfig, samlConfig, userId, providerId,
+ * organizationId, domain.
+ *
+ * All mutations route through better-auth's `/api/v1/auth/sso/*` endpoints
+ * (register / delete-provider) so config validation and secret handling run;
+ * the generic data layer is read-only (see `enable.apiMethods`).
+ *
+ * @namespace sys
+ */
+export const SysSsoProvider = ObjectSchema.create({
+  name: 'sys_sso_provider',
+  label: 'SSO Provider',
+  pluralLabel: 'SSO Providers',
+  icon: 'shield-check',
+  isSystem: true,
+  managedBy: 'better-auth',
+  // ADR-0010 §3.7 — managed by better-auth; tenants may not edit schema.
+  protection: {
+    lock: 'full',
+    reason: 'Identity table managed by better-auth (@better-auth/sso) — see ADR-0024.',
+    docsUrl: 'https://docs.objectstack.ai/adr/0010-metadata-protection',
+  },
+  description: 'External SSO identity providers (OIDC / SAML) this environment federates login to',
+  displayNameField: 'provider_id',
+  titleFormat: '{provider_id}',
+  compactLayout: ['provider_id', 'issuer', 'domain'],
+
+  // All mutations go through @better-auth/sso's endpoints under
+  // /api/v1/auth/sso/* (register / delete-provider) rather than the generic
+  // data layer, so server-side config validation + secret handling run.
+  actions: [
+    {
+      name: 'register_sso_provider',
+      label: 'Register SSO Provider',
+      icon: 'plus-circle',
+      variant: 'primary',
+      mode: 'create',
+      locations: ['list_toolbar'],
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/auth/sso/register',
+      refreshAfter: true,
+      params: [
+        { name: 'providerId', label: 'Provider ID', type: 'text', required: true, helpText: 'Stable identifier, e.g. "okta" or "acme-entra".' },
+        { name: 'issuer', label: 'Issuer URL', type: 'text', required: true, helpText: 'IdP issuer / discovery base, e.g. https://acme.okta.com.' },
+        { name: 'domain', label: 'Email Domain', type: 'text', required: true, helpText: 'Users with this email domain are routed to this IdP.' },
+        { name: 'clientId', label: 'Client ID', type: 'text', required: true },
+        { name: 'clientSecret', label: 'Client Secret', type: 'text', required: true },
+      ],
+    },
+    {
+      name: 'delete_sso_provider',
+      label: 'Delete SSO Provider',
+      icon: 'trash-2',
+      variant: 'danger',
+      mode: 'delete',
+      locations: ['list_item', 'record_header'],
+      type: 'api',
+      method: 'POST',
+      target: '/api/v1/auth/sso/delete-provider',
+      confirmText: 'Delete this SSO provider? Users from its domain will no longer be able to sign in through it.',
+      successMessage: 'SSO provider deleted',
+      refreshAfter: true,
+      params: [
+        { name: 'providerId', field: 'provider_id', defaultFromRow: true, required: true },
+      ],
+    },
+  ],
+
+  listViews: {
+    all: {
+      type: 'grid',
+      name: 'all',
+      label: 'All',
+      data: { provider: 'object', object: 'sys_sso_provider' },
+      columns: ['provider_id', 'issuer', 'domain', 'created_at'],
+      sort: [{ field: 'provider_id', order: 'asc' }],
+      pagination: { pageSize: 50 },
+    },
+  },
+
+  fields: {
+    id: Field.text({ label: 'ID', required: true, readonly: true, group: 'System' }),
+
+    provider_id: Field.text({
+      label: 'Provider ID',
+      required: true,
+      searchable: true,
+      maxLength: 255,
+      description: 'Stable provider identifier (unique within the environment)',
+      group: 'Identity',
+    }),
+
+    issuer: Field.text({
+      label: 'Issuer',
+      required: true,
+      maxLength: 2048,
+      description: 'IdP issuer URL',
+      group: 'Identity',
+    }),
+
+    domain: Field.text({
+      label: 'Email Domain',
+      required: true,
+      maxLength: 255,
+      description: 'Email domain routed to this IdP (e.g. acme.com)',
+      group: 'Identity',
+    }),
+
+    oidc_config: Field.textarea({
+      label: 'OIDC Config',
+      required: false,
+      description: 'JSON: clientId, clientSecret, endpoints, scopes, mapping, pkce (managed by better-auth)',
+      group: 'Protocol',
+    }),
+
+    saml_config: Field.textarea({
+      label: 'SAML Config',
+      required: false,
+      description: 'JSON: entryPoint, cert, identifierFormat, mapping (managed by better-auth)',
+      group: 'Protocol',
+    }),
+
+    user_id: Field.lookup('sys_user', {
+      label: 'Registered By',
+      required: false,
+      description: 'User who registered this provider',
+      group: 'System',
+    }),
+
+    organization_id: Field.text({
+      label: 'Organization',
+      required: false,
+      maxLength: 255,
+      description: 'Organization scope (when org-scoped SSO is used)',
+      group: 'System',
+    }),
+
+    created_at: Field.datetime({ label: 'Created At', defaultValue: 'NOW()', readonly: true, group: 'System' }),
+    updated_at: Field.datetime({ label: 'Updated At', defaultValue: 'NOW()', readonly: true, group: 'System' }),
+  },
+
+  indexes: [
+    { fields: ['provider_id'], unique: true },
+    { fields: ['domain'] },
+    { fields: ['user_id'] },
+  ],
+
+  enable: {
+    trackHistory: true,
+    searchable: true,
+    apiEnabled: true,
+    // Mutations go through /api/v1/auth/sso/* (register / delete-provider);
+    // the generic data layer is read-only so sysadmins cannot bypass
+    // server-side validation / secret handling.
+    apiMethods: ['get', 'list'],
+    trash: false,
+    mru: false,
+  },
+});
diff --git a/packages/plugins/plugin-auth/package.json b/packages/plugins/plugin-auth/package.json
@@ -20,6 +20,7 @@
   "dependencies": {
     "@better-auth/core": "^1.6.20",
     "@better-auth/oauth-provider": "^1.6.20",
+    "@better-auth/sso": "^1.6.20",
     "@noble/hashes": "^2.2.0",
     "@objectstack/core": "workspace:*",
     "@objectstack/platform-objects": "workspace:*",
diff --git a/packages/plugins/plugin-auth/src/auth-manager.ts b/packages/plugins/plugin-auth/src/auth-manager.ts
@@ -23,6 +23,7 @@ import {
   buildOrganizationPluginSchema,
   buildTwoFactorPluginSchema,
   buildOauthProviderPluginSchema,
+  buildSsoPluginSchema,
   buildDeviceAuthorizationPluginSchema,
   buildJwtPluginSchema,
   buildAdminPluginSchema,
@@ -625,6 +626,8 @@ export class AuthManager {
     // override per-environment without touching the application bundle.
     const oidcEnv = (globalThis as any)?.process?.env?.OS_OIDC_PROVIDER_ENABLED;
     const oidcFromEnv = oidcEnv != null ? String(oidcEnv).toLowerCase() === 'true' : undefined;
+    const ssoEnv = (globalThis as any)?.process?.env?.OS_SSO_ENABLED;
+    const ssoFromEnv = ssoEnv != null ? String(ssoEnv).toLowerCase() === 'true' : undefined;
     const twoFactorFromEnv = readBooleanEnv('OS_AUTH_TWO_FACTOR');
     const enabled = {
       organization: pluginConfig.organization ?? true,
@@ -634,6 +637,7 @@ export class AuthManager {
       oidcProvider: oidcFromEnv ?? pluginConfig.oidcProvider ?? false,
       deviceAuthorization: pluginConfig.deviceAuthorization ?? false,
       admin: pluginConfig.admin ?? false,
+      sso: ssoFromEnv ?? (pluginConfig as any).sso ?? false,
     };
 
     // bearer() — ALWAYS enabled.
@@ -926,6 +930,24 @@ export class AuthManager {
       }));
     }
 
+    // External SSO (OIDC / SAML) relying-party — lets this environment federate
+    // login to a customer's own IdP (Okta / Entra / Google …). Per-env, runtime-
+    // registered providers live in `sys_sso_provider` (ADR-0024: the OPEN SSO
+    // mechanism — cloud-free for self-host). Endpoints mount under
+    // /api/v1/auth/sso/{register,providers,delete-provider,callback,…}.
+    //
+    // Toggle with `OS_SSO_ENABLED` (mirrors `OS_OIDC_PROVIDER_ENABLED`).
+    if (enabled.sso) {
+      const { sso } = await import('@better-auth/sso');
+      plugins.push(sso({
+        schema: buildSsoPluginSchema(),
+        // provisionUser / organizationProvisioning are the hook for assigning a
+        // default env role on first federated login (ADR-0024 V1 minimal
+        // decisions). JIT user creation works out of the box via account
+        // linking; wire role defaults here in the follow-up.
+      }));
+    }
+
     // Device Authorization Grant (RFC 8628) — for CLI / TV-style devices.
     // Exposes the standard `/device/{code,token,approve,deny}` endpoints
     // and persists pending requests in `sys_device_code`.
diff --git a/packages/plugins/plugin-auth/src/auth-schema-config.ts b/packages/plugins/plugin-auth/src/auth-schema-config.ts
@@ -650,6 +650,50 @@ export function buildOauthProviderPluginSchema() {
  */
 export const buildOidcProviderPluginSchema = buildOauthProviderPluginSchema;
 
+// ---------------------------------------------------------------------------
+// SSO plugin – ssoProvider table (@better-auth/sso)
+// ---------------------------------------------------------------------------
+
+/**
+ * `@better-auth/sso` plugin `ssoProvider` model mapping.
+ *
+ * Each row is an external OIDC/SAML IdP this environment federates login to
+ * (the relying-party side — ADR-0024's OPEN per-env SSO mechanism). The
+ * protocol detail lives in JSON blobs (`oidcConfig` / `samlConfig`); the model
+ * itself is thin. Mirrors @better-auth/sso@1.6.20's `BaseSSOProvider`.
+ *
+ * | camelCase (better-auth) | snake_case (ObjectStack) |
+ * |:------------------------|:-------------------------|
+ * | providerId              | provider_id              |
+ * | oidcConfig              | oidc_config              |
+ * | samlConfig              | saml_config              |
+ * | userId                  | user_id                  |
+ * | organizationId          | organization_id          |
+ * | issuer / domain         | (same name — no remap) |
+ */
+export const AUTH_SSO_PROVIDER_SCHEMA = {
+  modelName: 'sys_sso_provider',
+  fields: {
+    providerId: 'provider_id',
+    oidcConfig: 'oidc_config',
+    samlConfig: 'saml_config',
+    userId: 'user_id',
+    organizationId: 'organization_id',
+  },
+} as const;
+
+/**
+ * Builds the `schema` option for `@better-auth/sso`'s `sso()` plugin, pointing
+ * its single `ssoProvider` model at ObjectStack's `sys_sso_provider` table.
+ *
+ * @returns An object suitable for `sso({ schema: … })`
+ */
+export function buildSsoPluginSchema() {
+  return {
+    ssoProvider: AUTH_SSO_PROVIDER_SCHEMA,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Helper: build device-authorization plugin schema option
 // ---------------------------------------------------------------------------
