feat: SAML SSO client SDK, dashboard, demo, and e2e tests

.github/workflows/e2e-api-tests-local-emulator.yaml

@@ -140,6 +140,16 @@ jobs:
           wait-for: 30s
           log-output-if: true
 
+      - name: Start mock-saml-idp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mock-saml-idp --log-order=stream &
+          wait-on: |
+            http://localhost:8142/idp
+          tail: true
+          wait-for: 30s
+          log-output-if: true
+
       - name: Start run-email-queue in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:

.github/workflows/e2e-custom-base-port-api-tests.yaml

@@ -136,6 +136,15 @@ jobs:
           tail: true
           wait-for: 30s
           log-output-if: true
+      - name: Start mock-saml-idp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mock-saml-idp --log-order=stream &
+          wait-on: |
+            http://localhost:6742/idp
+          tail: true
+          wait-for: 30s
+          log-output-if: true
       - name: Start run-email-queue in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:

apps/backend/src/app/api/latest/auth/saml/acs/[connection_id]/route.tsx

@@ -143,6 +143,10 @@ export const POST = createSmartRouteHandler({
     }
     const prisma = await getPrismaClientForTenancy(tenancy);
 
+    if (!tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
+
     if (!has(tenancy.config.auth.saml.connections, params.connection_id)) {
       throw new StatusError(StatusError.NotFound, `SAML connection ${params.connection_id} not found`);
     }

apps/backend/src/app/api/latest/auth/saml/discover/route.tsx

@@ -3,6 +3,7 @@ import type { SamlConnectionConfig } from "@/saml/saml";
 import { getSoleTenancyFromProjectBranch, DEFAULT_BRANCH_ID } from "@/lib/tenancies";
 import { typedEntries } from "@stackframe/stack-shared/dist/utils/objects";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
 import { emailSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 
@@ -46,6 +47,9 @@ export const GET = createSmartRouteHandler({
     if (!tenancy) {
       throw new StatusError(StatusError.NotFound, `Project ${query.project_id} not found`);
     }
+    if (!tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
     // Inject `id` into each connection so it satisfies SamlConnectionConfig —
     // the config schema stores id as the record key, not a value field.
     // Skip connections with sign-in disabled — discover is the entry point

apps/backend/src/app/api/latest/auth/saml/login/[connection_id]/route.tsx

@@ -101,6 +101,10 @@ export const GET = createSmartRouteHandler({
       throwCheckApiKeySetError(keyCheck.error, tenancy.project.id, new KnownErrors.InvalidPublishableClientKey(tenancy.project.id));
     }
 
+    if (!tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
+
     if (!has(tenancy.config.auth.saml.connections, params.connection_id)) {
       throw new StatusError(StatusError.NotFound, `SAML connection ${params.connection_id} not found`);
     }

apps/backend/src/app/api/latest/auth/saml/metadata/[connection_id]/route.tsx

@@ -1,6 +1,7 @@
 import { getSoleTenancyFromProjectBranch, DEFAULT_BRANCH_ID } from "@/lib/tenancies";
 import { getSpMetadataXml } from "@/saml/saml";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
 import { yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
@@ -45,6 +46,9 @@ export const GET = createSmartRouteHandler({
     if (!tenancy) {
       throw new StatusError(StatusError.NotFound, `Project ${query.project_id} not found`);
     }
+    if (!tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
     if (!has(tenancy.config.auth.saml.connections, params.connection_id)) {
       throw new StatusError(StatusError.NotFound, `SAML connection ${params.connection_id} not found in project ${query.project_id}`);
     }

apps/backend/src/app/api/latest/saml-connections/[connection_id]/route.tsx

@@ -5,6 +5,7 @@
  */
 import { adaptSchema, adminAuthTypeSchema, yupBoolean, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import { has } from "@stackframe/stack-shared/dist/utils/objects";
 
@@ -41,6 +42,9 @@ export const GET = createSmartRouteHandler({
     }).defined(),
   }),
   async handler({ auth, params }) {
+    if (!auth.tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
     if (!has(auth.tenancy.config.auth.saml.connections, params.connection_id)) {
       throw new StatusError(StatusError.NotFound, `SAML connection ${params.connection_id} not found`);
     }

apps/backend/src/app/api/latest/saml-connections/route.tsx

@@ -12,6 +12,7 @@
  */
 import { overrideEnvironmentConfigOverride, resetEnvironmentConfigOverrideKeys } from "@/lib/config";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
 import { adaptSchema, adminAuthTypeSchema, yupArray, yupBoolean, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import { has } from "@stackframe/stack-shared/dist/utils/objects";
@@ -48,6 +49,9 @@ export const GET = createSmartRouteHandler({
     }).defined(),
   }),
   async handler({ auth }) {
+    if (!auth.tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
     const connections = auth.tenancy.config.auth.saml.connections;
     type Conn = (typeof auth.tenancy.config.auth.saml.connections)[string];
     return {
@@ -99,6 +103,9 @@ export const POST = createSmartRouteHandler({
     body: samlConnectionResponseShape,
   }),
   async handler({ auth, body }) {
+    if (!auth.tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
     const exists = has(auth.tenancy.config.auth.saml.connections, body.id);
     const prefix = `auth.saml.connections.${body.id}`;
     const overlay: Record<string, unknown> = {};
@@ -184,6 +191,9 @@ export const DELETE = createSmartRouteHandler({
     }).defined(),
   }),
   async handler({ auth, body }) {
+    if (!auth.tenancy.config.apps.installed["saml-sso"]?.enabled) {
+      throw new KnownErrors.SamlSsoNotEnabled();
+    }
     if (!has(auth.tenancy.config.auth.saml.connections, body.id)) {
       throw new StatusError(StatusError.NotFound, `SAML connection ${body.id} not found`);
     }

apps/backend/src/lib/seed-dummy-data.ts

@@ -1988,6 +1988,9 @@ async function seedSamlConnections(projectId: string): Promise<void> {
   // dot-keys — config normalization with onDotIntoNonObject="ignore"
   // drops dot-keys that try to navigate into a record entry that
   // doesn't yet exist (same convention as auth.oauth.providers).
+  // No need to set `apps.installed.saml-sso.enabled` here — the dummy
+  // project's branch config (above) installs every entry in ALL_APPS,
+  // including alpha-stage apps, when excludeAlphaApps isn't set.
   const overlay: Parameters<typeof overrideEnvironmentConfigOverride>[0]["environmentConfigOverrideOverride"] = {};
   for (const f of fetched) {
     overlay[`auth.saml.connections.${f.slug}`] = {

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/sso/page-client.tsx

@@ -0,0 +1,233 @@
+"use client";
+
+import { SmartFormDialog } from "@/components/form-dialog";
+import { ActionDialog, Alert, Button, Card, CardContent, CardHeader, Typography } from "@/components/ui";
+import { useUpdateConfig } from "@/lib/config-update";
+import { getPublicEnvVar } from "@/lib/env";
+import React, { useState } from "react";
+import * as yup from "yup";
+import { AppEnabledGuard } from "../app-enabled-guard";
+import { PageLayout } from "../page-layout";
+import { useAdminApp } from "../use-admin-app";
+
+function getBrowserApiBase(): string {
+  const url = getPublicEnvVar("NEXT_PUBLIC_BROWSER_STACK_API_URL") ?? getPublicEnvVar("NEXT_PUBLIC_STACK_API_URL") ?? "";
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * Dashboard for managing SAML SSO connections on the current project.
+ *
+ * Connection config is stored at tenancy.config.auth.saml.connections —
+ * the same JSON-config the seed script and admin /saml-connections
+ * endpoints write. This page reads via project.useConfig() and writes
+ * via useUpdateConfig() with key paths.
+ *
+ * V1 scope: single-page list with create + delete dialogs. The
+ * paste-IdP-metadata helper that auto-fills idpEntityId/idpSsoUrl/
+ * idpCertificate from a single XML blob is a planned follow-up — for
+ * now connection fields are entered manually.
+ */
+export default function PageClient() {
+  return (
+    <AppEnabledGuard appId="saml-sso">
+      <PageContent />
+    </AppEnabledGuard>
+  );
+}
+
+function PageContent() {
+  const stackAdminApp = useAdminApp();
+  const project = stackAdminApp.useProject();
+  const config = project.useConfig();
+  const connections = config.auth.saml.connections;
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [deleteId, setDeleteId] = useState<string | null>(null);
+
+  const connectionEntries = Object.entries(connections);
+  const apiBase = getBrowserApiBase();
+
+  return (
+    <PageLayout
+      title="SAML SSO"
+      description="Manage SAML 2.0 connections so corporate IdP users can sign in to your project."
+      actions={<Button onClick={() => setCreateOpen(true)}>Add SAML connection</Button>}
+    >
+      {connectionEntries.length === 0 && (
+        <Alert>
+          No SAML connections configured yet. Click <strong>Add SAML connection</strong> to wire
+          up your first IdP.
+        </Alert>
+      )}
+
+      <div className="grid gap-4">
+        {connectionEntries.map(([id, conn]) => (
+          <Card key={id}>
+            <CardHeader>
+              <div className="flex items-center justify-between">
+                <div>
+                  <Typography type="h4">{conn.displayName}</Typography>
+                  <Typography type="p" variant="secondary" className="text-sm">
+                    Connection ID: <code>{id}</code>
+                    {conn.domain && (
+                      <>
+                        {" "}· Email domain: <code>{conn.domain}</code>
+                      </>
+                    )}
+                  </Typography>
+                </div>
+                <div className="flex gap-2">
+                  <Button variant="destructive" size="sm" onClick={() => setDeleteId(id)}>
+                    Delete
+                  </Button>
+                </div>
+              </div>
+            </CardHeader>
+            <CardContent>
+              <div className="grid gap-2 text-sm">
+                <DetailRow label="IdP Entity ID" value={conn.idpEntityId} />
+                <DetailRow label="IdP SSO URL" value={conn.idpSsoUrl} />
+                <DetailRow
+                  label="IdP signing cert"
+                  value={conn.idpCertificate ? `<${conn.idpCertificate.length}-char certificate>` : null}
+                />
+                <DetailRow label="Sign-in enabled" value={conn.allowSignIn ? "yes" : "no"} />
+              </div>
+              <div className="mt-3 grid gap-1 text-sm border-t pt-3">
+                <Typography type="p" variant="secondary" className="text-xs">
+                  Paste these into your IdP&apos;s admin console:
+                </Typography>
+                <DetailRow
+                  label="SP metadata URL"
+                  value={`${apiBase}/api/v1/auth/saml/metadata/${id}?project_id=${project.id}`}
+                  mono
+                />
+                <DetailRow
+                  label="ACS URL"
+                  value={`${apiBase}/api/v1/auth/saml/acs/${id}`}
+                  mono
+                />
+              </div>
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+
+      <CreateDialog open={createOpen} onOpenChange={setCreateOpen} />
+      <DeleteDialog
+        connectionId={deleteId}
+        onClose={() => setDeleteId(null)}
+        // Guard against stale deleteId after a config refresh removed the
+        // entry — index types claim non-undefined but the key may be gone.
+        displayName={deleteId && Object.hasOwn(connections, deleteId) ? connections[deleteId].displayName : null}
+      />
+    </PageLayout>
+  );
+}
+
+function DetailRow({ label, value, mono }: { label: string, value: string | null | undefined, mono?: boolean }) {
+  return (
+    <div className="flex gap-2">
+      <span className="font-medium min-w-[140px]">{label}:</span>
+      <span className={mono ? "font-mono break-all" : "break-all"}>
+        {value ? value : <em className="text-gray-500">not set</em>}
+      </span>
+    </div>
+  );
+}
+
+function CreateDialog({ open, onOpenChange }: { open: boolean, onOpenChange: (open: boolean) => void }) {
+  const stackAdminApp = useAdminApp();
+  const updateConfig = useUpdateConfig();
+
+  const formSchema = yup.object({
+    id: yup.string()
+      .matches(/^[a-z0-9_-]+$/, "ID can only contain lowercase letters, digits, underscores, and dashes")
+      .nonEmpty().label("Connection ID"),
+    displayName: yup.string().nonEmpty().label("Display name"),
+    domain: yup.string().optional().label("Email domain (for discovery)"),
+    idpEntityId: yup.string().nonEmpty().label("IdP Entity ID"),
+    // Skip yup's url() — it rejects http://localhost which breaks dev/test setups.
+    // The backend SAML wrapper validates the URL on use.
+    idpSsoUrl: yup.string().nonEmpty().label("IdP SSO URL"),
+    idpCertificate: yup.string().nonEmpty().label("IdP signing certificate (X.509, base64)"),
+    allowSignIn: yup.boolean().default(true).label("Enable sign-in"),
+  });
+
+  return (
+    <SmartFormDialog
+      open={open}
+      onOpenChange={onOpenChange}
+      title="Add a SAML connection"
+      formSchema={formSchema}
+      okButton={{ label: "Create" }}
+      cancelButton
+      onSubmit={async (values) => {
+        // Set the whole connection entry as a single value. Deep dot-keys
+        // (e.g. `auth.saml.connections.X.displayName`) get dropped during
+        // config normalization when the parent record entry doesn't yet
+        // exist — same convention as auth.oauth.providers in the
+        // auth-methods page.
+        // Normalize domain on write — discovery does case-insensitive
+        // matching but does not trim, so trailing whitespace from a
+        // pasted value would silently break lookups.
+        const normalizedDomain = values.domain?.trim().toLowerCase() || undefined;
+        await updateConfig({
+          adminApp: stackAdminApp,
+          configUpdate: {
+            [`auth.saml.connections.${values.id}`]: {
+              displayName: values.displayName,
+              allowSignIn: values.allowSignIn,
+              domain: normalizedDomain,
+              idpEntityId: values.idpEntityId,
+              idpSsoUrl: values.idpSsoUrl,
+              idpCertificate: (values.idpCertificate ?? "").replace(/-----BEGIN CERTIFICATE-----|-----END CERTIFICATE-----|\s+/g, ""),
+            },
+          } as Parameters<typeof updateConfig>[0]["configUpdate"],
+          // SAML connection fields (cert, IdP URLs) are environment-level
+          // (not pushable) — same as OAuth client secrets.
+          pushable: false,
+        });
+      }}
+    />
+  );
+}
+
+function DeleteDialog({ connectionId, displayName, onClose }: {
+  connectionId: string | null,
+  displayName: string | null,
+  onClose: () => void,
+}) {
+  const stackAdminApp = useAdminApp();
+  const updateConfig = useUpdateConfig();
+
+  return (
+    <ActionDialog
+      open={connectionId != null}
+      onOpenChange={(open) => { if (!open) onClose(); }}
+      title="Delete SAML connection?"
+      danger
+      okButton={{
+        label: "Delete connection",
+        onClick: async () => {
+          if (!connectionId) return;
+          await updateConfig({
+            adminApp: stackAdminApp,
+            configUpdate: { [`auth.saml.connections.${connectionId}`]: null } as Parameters<typeof updateConfig>[0]["configUpdate"],
+            // SAML connection fields (cert, IdP URLs) are environment-level
+            // (not pushable) — same as OAuth client secrets.
+            pushable: false,
+          });
+          onClose();
+        },
+      }}
+      cancelButton
+    >
+      <Typography>
+        Delete <strong>{displayName ?? "this connection"}</strong>? Existing user accounts linked
+        via this connection will remain in the database but will no longer be able to sign in.
+      </Typography>
+    </ActionDialog>
+  );
+}