feat(sso): SAML/OIDC single sign-on

.server-changes/sso.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+SAML/OIDC single sign-on: SSO login with optional per-domain enforcement, JIT provisioning, and periodic re-validation against the IdP.

apps/webapp/app/components/navigation/OrganizationSettingsSideMenu.tsx

@@ -1,10 +1,9 @@
-import { ArrowLeftIcon } from "@heroicons/react/24/solid";
+import { ArrowLeftIcon, LinkIcon } from "@heroicons/react/24/solid";
 import { BellIcon } from "~/assets/icons/BellIcon";
 import { CreditCardIcon } from "~/assets/icons/CreditCardIcon";
 import { PadlockIcon } from "~/assets/icons/PadlockIcon";
 import { UsageIcon } from "~/assets/icons/UsageIcon";
 import { RolesIcon } from "~/assets/icons/RolesIcon";
-import { ShieldLockIcon } from "~/assets/icons/ShieldLockIcon";
 import { SlackIcon } from "~/assets/icons/SlackIcon";
 import { SlidersIcon } from "~/assets/icons/SlidersIcon";
 import { UserGroupIcon } from "~/assets/icons/UserGroupIcon";
@@ -17,6 +16,7 @@ import {
   organizationRolesPath,
   organizationSettingsPath,
   organizationSlackIntegrationPath,
+  organizationSsoPath,
   organizationTeamPath,
   organizationVercelIntegrationPath,
   rootPath,
@@ -48,10 +48,12 @@ export function OrganizationSettingsSideMenu({
   organization,
   buildInfo,
   isUsingPlugin,
+  isSsoUsingPlugin,
 }: {
   organization: MatchedOrganization;
   buildInfo: BuildInfo;
   isUsingPlugin: boolean;
+  isSsoUsingPlugin: boolean;
 }) {
   const { isManagedCloud } = useFeatures();
   const featureFlags = useFeatureFlags();
@@ -128,7 +130,7 @@ export function OrganizationSettingsSideMenu({
           {featureFlags.hasPrivateConnections && (
             <SideMenuItem
               name="Private Connections"
-              icon={PadlockIcon}
+              icon={LinkIcon}
               activeIconColor="text-text-bright"
               inactiveIconColor="text-text-dimmed"
               to={v3PrivateConnectionsPath(organization)}
@@ -145,6 +147,21 @@ export function OrganizationSettingsSideMenu({
               data-action="roles"
             />
           )}
+          {isManagedCloud && isSsoUsingPlugin && (
+            <SideMenuItem
+              name="SSO"
+              icon={PadlockIcon}
+              activeIconColor="text-text-bright"
+              inactiveIconColor="text-text-dimmed"
+              to={organizationSsoPath(organization)}
+              data-action="sso"
+              badge={
+                currentPlan?.v3Subscription?.plan?.code === "enterprise" ? undefined : (
+                  <Badge variant="extra-small">Enterprise</Badge>
+                )
+              }
+            />
+          )}
           <SideMenuItem
             name="Settings"
             icon={SlidersIcon}

apps/webapp/app/entry.client.tsx

@@ -3,8 +3,10 @@ import { hydrateRoot } from "react-dom/client";
 import { clientBeforeFirstRender } from "./clientBeforeFirstRender";
 import { LocaleContextProvider } from "./components/primitives/LocaleProvider";
 import { OperatingSystemContextProvider } from "./components/primitives/OperatingSystemProvider";
+import { installSsoSessionGuard } from "./utils/ssoSessionGuard";
 
 clientBeforeFirstRender();
+installSsoSessionGuard();
 
 hydrateRoot(
   document,

apps/webapp/app/env.server.ts

@@ -1867,6 +1867,32 @@ const EnvironmentSchema = z
 
     // Force RBAC to not use the plugin
     RBAC_FORCE_FALLBACK: BoolEnv.default(false),
+
+    // Force SSO to not use the plugin (contributors without the cloud
+    // plugin installed can opt in to a clean OSS-only experience).
+    SSO_FORCE_FALLBACK: BoolEnv.default(false),
+    // Emit a console.log when the SSO fallback is selected because no
+    // plugin is installed. Default off so OSS deployments stay quiet.
+    SSO_LOG_FALLBACK: BoolEnv.default(false),
+    // Master deploy gate for the whole SSO feature. Default OFF so the
+    // image can ship dark and be flipped on only once the SSO plugin's
+    // backing services are available. When false, the SSO controller is
+    // forced to the OSS fallback — login link hidden, SSO login disabled,
+    // settings inert, and session re-validation skipped.
+    SSO_ENABLED: BoolEnv.default(false),
+    // How often (seconds) a live SSO session is re-validated against the
+    // identity provider. The check is single-flight per user, so this is
+    // the minimum interval between plugin round-trips, not a per-request
+    // cost. Defaults to 5 minutes: every active SSO user drives one
+    // billing→IdP round-trip per window, so a seconds-scale default
+    // exhausts vendor rate limits at trivial user counts (masked by
+    // fail-open, so it degrades silently).
+    SSO_SESSION_REVALIDATION_INTERVAL_SECONDS: z.coerce.number().int().positive().default(300),
+    // Hard timeout (ms) on the re-validation round-trip. If the SSO plugin
+    // doesn't answer within this window the check fails OPEN (session kept)
+    // and emits a `sso.revalidation.timeout` warn log — alert on an
+    // elevated rate of those to catch a slow/unhealthy SSO dependency.
+    SSO_SESSION_REVALIDATION_TIMEOUT_MS: z.coerce.number().int().positive().default(2000),
   })
   .and(GithubAppEnvSchema)
   .and(S2EnvSchema)

apps/webapp/app/hooks/useEventSource.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState } from "react";
+import { probeSsoSession } from "~/utils/ssoSessionGuard";
 
 type EventSourceOptions = {
   init?: EventSourceInit;
@@ -28,13 +29,21 @@ export function useEventSource(
 
     const eventSource = new EventSource(url, init);
     eventSource.addEventListener(event ?? "message", handler);
+    eventSource.addEventListener("error", errorHandler);
 
     function handler(event: MessageEvent) {
       setData(event.data || "UNKNOWN_EVENT_DATA");
     }
 
+    // EventSource can't surface response headers, so on a stream error probe
+    // an authenticated endpoint; a revoked session redirects via the guard.
+    function errorHandler() {
+      probeSsoSession();
+    }
+
     return () => {
       eventSource.removeEventListener(event ?? "message", handler);
+      eventSource.removeEventListener("error", errorHandler);
       eventSource.close();
     };
   }, [url, event, init, disabled]);

apps/webapp/app/models/orgMember.server.ts

@@ -0,0 +1,134 @@
+import { Prisma, prisma } from "~/db.server";
+import { logger } from "~/services/logger.server";
+import { rbac } from "~/services/rbac.server";
+
+export type EnsureOrgMemberParams = {
+  userId: string;
+  organizationId: string;
+  // null = use the seeded MEMBER role from the existing enum. A non-null
+  // value is an RBAC role id; when an RBAC plugin is installed it gets
+  // attached after the OrgMember row is created.
+  roleId: string | null;
+  source: "sso_jit" | "invite" | "manual";
+};
+
+export type EnsureOrgMemberResult = { created: boolean; orgMemberId: string };
+
+// Completes a JIT role assignment for an ALREADY-existing membership whose
+// RBAC role never got applied. This is a no-op when a role is already
+// assigned, so it can never demote a deliberately-set role — it only fills
+// in the gap left by an interrupted provision (see `ensureOrgMember`). Always
+// best-effort: a valid membership already exists, so a failure here is logged
+// and swallowed rather than thrown.
+async function healMissingRoleAssignment(params: {
+  userId: string;
+  organizationId: string;
+  roleId: string;
+  source: EnsureOrgMemberParams["source"];
+}): Promise<void> {
+  const { userId, organizationId, roleId, source } = params;
+
+  const currentRole = await rbac.getUserRole({ userId, organizationId });
+  if (currentRole !== null) return;
+
+  const result = await rbac.setUserRole({ userId, organizationId, roleId });
+  if (!result.ok) {
+    logger.warn("ensureOrgMember.setUserRole failed while healing unassigned membership", {
+      source,
+      userId,
+      organizationId,
+      roleId,
+      error: result.error,
+    });
+  }
+}
+
+// Idempotent OrgMember upsert. If the (userId, organizationId) row
+// already exists this is a no-op (returns `{ created: false }`); we do
+// NOT touch the existing role to avoid demoting a user that JIT happens
+// to fire for again.
+//
+// Seat-limit enforcement lives at the call sites — every existing
+// OrgMember insert in the codebase does its own seat check before
+// calling in. This helper deliberately does none (SSO JIT and
+// invite-accept are exempt by policy).
+export async function ensureOrgMember(
+  params: EnsureOrgMemberParams
+): Promise<EnsureOrgMemberResult> {
+  const { userId, organizationId, roleId, source } = params;
+
+  const existing = await prisma.orgMember.findFirst({
+    where: { userId, organizationId },
+    select: { id: true },
+  });
+  if (existing) {
+    // Existing membership is normally a pure no-op: we don't re-touch the
+    // role, since a user JIT fires for again may have been deliberately
+    // promoted and must not be demoted back to the JIT default.
+    //
+    // The one exception is self-healing a half-provisioned row. The create +
+    // setUserRole + compensating delete below are not transactional (the RBAC
+    // plugin writes on its own connection, so a single DB transaction isn't
+    // possible). If setUserRole failed AND that compensating delete also
+    // failed, the placeholder MEMBER row is orphaned — and this findFirst
+    // would short-circuit every future login, stranding the user on the
+    // placeholder role forever. So when a JIT role is requested but the RBAC
+    // layer shows no role assigned, complete the assignment now. It's gated on
+    // "no role assigned", so it can never demote a real one.
+    if (roleId !== null) {
+      await healMissingRoleAssignment({ userId, organizationId, roleId, source });
+    }
+    return { created: false, orgMemberId: existing.id };
+  }
+
+  // Two concurrent JIT/invite flows can both miss the findFirst above and
+  // race to create the same (userId, organizationId) row; the unique
+  // constraint makes one lose with P2002. Treat that as the idempotent
+  // "already a member" case rather than letting it break sign-in.
+  let member: { id: string };
+  try {
+    member = await prisma.orgMember.create({
+      data: {
+        userId,
+        organizationId,
+        role: "MEMBER",
+      },
+      select: { id: true },
+    });
+  } catch (error) {
+    if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002") {
+      const existingAfterConflict = await prisma.orgMember.findFirst({
+        where: { userId, organizationId },
+        select: { id: true },
+      });
+      if (existingAfterConflict) {
+        return { created: false, orgMemberId: existingAfterConflict.id };
+      }
+    }
+    throw error;
+  }
+
+  if (roleId !== null) {
+    const result = await rbac.setUserRole({ userId, organizationId, roleId });
+    if (!result.ok) {
+      // The membership was just created with the legacy `MEMBER` enum role as
+      // a placeholder; the intended RBAC role failed to apply. Leaving the row
+      // in place would grant the user `MEMBER` access — potentially broader
+      // than the configured (e.g. restrictive) JIT default role they were
+      // supposed to get. Roll back so we never half-provision into an
+      // unintended privilege level, then throw so the caller can decide
+      // whether to skip provisioning or fail the flow.
+      logger.warn("ensureOrgMember.setUserRole failed; rolling back membership", {
+        source,
+        userId,
+        organizationId,
+        roleId,
+        error: result.error,
+      });
+      await prisma.orgMember.delete({ where: { id: member.id } });
+      throw new Error(`ensureOrgMember: failed to apply role ${roleId}: ${result.error}`);
+    }
+  }
+
+  return { created: true, orgMemberId: member.id };
+}

apps/webapp/app/models/user.server.ts

@@ -30,7 +30,18 @@ type FindOrCreateGoogle = {
   authenticationExtraParams: Record<string, unknown>;
 };
 
-type FindOrCreateUser = FindOrCreateMagicLink | FindOrCreateGithub | FindOrCreateGoogle;
+type FindOrCreateSso = {
+  authenticationMethod: "SSO";
+  email: User["email"];
+  firstName: string | null;
+  lastName: string | null;
+};
+
+type FindOrCreateUser =
+  | FindOrCreateMagicLink
+  | FindOrCreateGithub
+  | FindOrCreateGoogle
+  | FindOrCreateSso;
 
 type LoggedInUser = {
   user: User;
@@ -48,6 +59,9 @@ export async function findOrCreateUser(input: FindOrCreateUser): Promise<LoggedI
     case "GOOGLE": {
       return findOrCreateGoogleUser(input);
     }
+    case "SSO": {
+      return findOrCreateSsoUser(input);
+    }
   }
 }
 
@@ -303,6 +317,47 @@ export async function findOrCreateGoogleUser({
   };
 }
 
+// Find an existing user by email (lowercased) or create a new one with the
+// SSO authentication method. Mirrors the magic-link upsert shape; the
+// callback route is responsible for normalising email before calling.
+// Plugin writes (linking the IdP identity row) happen via the SSO plugin
+// after this returns.
+export async function findOrCreateSsoUser({
+  email,
+  firstName,
+  lastName,
+}: FindOrCreateSso): Promise<LoggedInUser> {
+  // Validate the canonical value we actually look up and persist below —
+  // validating raw `email` would let case/whitespace variants slip past
+  // (or misapply) the allow-list policy.
+  const normalised = email.toLowerCase().trim();
+  assertEmailAllowed(normalised);
+
+  const existingUser = await prisma.user.findFirst({ where: { email: normalised } });
+
+  const fullName = [firstName, lastName].filter(Boolean).join(" ").trim() || null;
+
+  const user = await prisma.user.upsert({
+    where: { email: normalised },
+    update: {
+      // Existing magic-link / OAuth users keep their original
+      // authenticationMethod; we only refresh name/displayName when the
+      // user has nothing set yet so we don't clobber a customised display
+      // name on every SSO login.
+      ...(existingUser?.name ? {} : { name: fullName }),
+      ...(existingUser?.displayName ? {} : { displayName: fullName }),
+    },
+    create: {
+      email: normalised,
+      name: fullName,
+      displayName: fullName,
+      authenticationMethod: "SSO",
+    },
+  });
+
+  return { user, isNewUser: !existingUser };
+}
+
 export type UserWithDashboardPreferences = User & {
   dashboardPreferences: DashboardPreferences;
 };