@checkstack/auth-saml-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# @checkstack/auth-saml-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- 10aa9fb: Add SAML 2.0 SSO support
+
+  - Added new `auth-saml-backend` plugin for SAML 2.0 Single Sign-On authentication
+  - Supports SP-initiated SSO with configurable IdP metadata (URL or manual configuration)
+  - Uses samlify library for SAML protocol handling
+  - Configurable attribute mapping for user email/name extraction
+  - Automatic user creation and updates via S2S Identity API
+  - Added SAML redirect handling in LoginPage for seamless SSO flow
+
+- d94121b: Add group-to-role mapping for SAML and LDAP authentication
+
+  **Features:**
+
+  - SAML and LDAP users can now be automatically assigned Checkstack roles based on their directory group memberships
+  - Configure group mappings in the authentication strategy settings with dynamic role dropdowns
+  - Managed role sync: roles configured in mappings are fully synchronized (added when user gains group, removed when user leaves group)
+  - Unmanaged roles (manually assigned, not in any mapping) are preserved during sync
+  - Optional default role for all users from a directory
+
+  **Bug Fix:**
+
+  - Fixed `x-options-resolver` not working for fields inside arrays with `.default([])` in DynamicForm schemas
+
+### Patch Changes
+
+- Updated dependencies [d94121b]
+  - @checkstack/backend-api@0.3.3
+  - @checkstack/auth-backend@0.4.0
+  - @checkstack/auth-common@0.5.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@checkstack/auth-saml-backend",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/auth-backend": "workspace:*",
+    "@checkstack/auth-common": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "better-auth": "^1.4.9",
+    "samlify": "^2.8.11",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/test-utils-backend": "workspace:*",
+    "typescript": "^5.7.2"
+  },
+  "plugin": {
+    "id": "auth-saml-backend",
+    "name": "@checkstack/auth-saml-backend",
+    "type": "backend",
+    "displayName": "SAML Authentication (Backend)"
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,33 @@
+/**
+ * Helper to extract attribute value from SAML assertion
+ * Handles both single values and arrays (takes first element)
+ */
+export const extractAttribute = ({
+  attributes,
+  attributeName,
+}: {
+  attributes: Record<string, unknown>;
+  attributeName: string;
+}): string | undefined => {
+  const value = attributes[attributeName];
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.length > 0) return String(value[0]);
+  return undefined;
+};
+
+/**
+ * Helper to extract groups from SAML assertion (multi-valued attribute)
+ * Returns all groups as an array of strings
+ */
+export const extractGroups = ({
+  attributes,
+  groupAttribute,
+}: {
+  attributes: Record<string, unknown>;
+  groupAttribute: string;
+}): string[] => {
+  const value = attributes[groupAttribute];
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.map(String);
+  return [];
+};

package/src/index.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { configString, configBoolean } from "@checkstack/backend-api";
+import { extractAttribute, extractGroups } from "./helpers";
+
+// Re-create the config schema for testing
+const samlConfigV1 = z.object({
+  idpMetadataUrl: configString({}).url().optional(),
+  idpMetadata: configString({}).optional(),
+  idpEntityId: configString({}).optional(),
+  idpSingleSignOnUrl: configString({}).url().optional(),
+  idpCertificate: configString({ "x-secret": true }).optional(),
+  spEntityId: configString({}).default("checkstack"),
+  spPrivateKey: configString({ "x-secret": true }).optional(),
+  spCertificate: configString({}).optional(),
+  attributeMapping: z
+    .object({
+      email: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+        )
+        .describe("SAML attribute for email address"),
+      name: configString({})
+        .default("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name")
+        .describe("SAML attribute for display name"),
+      firstName: configString({}).optional(),
+      lastName: configString({}).optional(),
+    })
+    .default({
+      email:
+        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+      name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+    }),
+  wantAssertionsSigned: configBoolean({}).default(true),
+  signAuthnRequest: configBoolean({}).default(false),
+});
+
+describe("SAML Configuration Schema", () => {
+  describe("validation", () => {
+    it("should accept valid config with metadata URL", () => {
+      const config = {
+        idpMetadataUrl: "https://idp.example.com/metadata",
+        spEntityId: "my-app",
+      };
+
+      const result = samlConfigV1.safeParse(config);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.idpMetadataUrl).toBe(
+          "https://idp.example.com/metadata",
+        );
+        expect(result.data.spEntityId).toBe("my-app");
+      }
+    });
+
+    it("should accept valid config with manual IdP settings", () => {
+      const config = {
+        idpSingleSignOnUrl: "https://idp.example.com/sso",
+        idpCertificate:
+          "-----BEGIN CERTIFICATE-----\\nMIIC...\\n-----END CERTIFICATE-----",
+        idpEntityId: "https://idp.example.com",
+        spEntityId: "my-app",
+      };
+
+      const result = samlConfigV1.safeParse(config);
+      expect(result.success).toBe(true);
+    });
+
+    it("should apply default values", () => {
+      const config = {};
+
+      const result = samlConfigV1.safeParse(config);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.spEntityId).toBe("checkstack");
+        expect(result.data.wantAssertionsSigned).toBe(true);
+        expect(result.data.signAuthnRequest).toBe(false);
+        expect(result.data.attributeMapping.email).toBe(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+        );
+        expect(result.data.attributeMapping.name).toBe(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+        );
+      }
+    });
+
+    it("should reject invalid IdP metadata URL", () => {
+      const config = {
+        idpMetadataUrl: "not-a-valid-url",
+      };
+
+      const result = samlConfigV1.safeParse(config);
+      expect(result.success).toBe(false);
+    });
+
+    it("should reject invalid IdP SSO URL", () => {
+      const config = {
+        idpSingleSignOnUrl: "not-a-valid-url",
+      };
+
+      const result = samlConfigV1.safeParse(config);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe("attribute mapping", () => {
+    it("should accept custom attribute mappings", () => {
+      const config = {
+        attributeMapping: {
+          email: "mail",
+          name: "displayName",
+          firstName: "givenName",
+          lastName: "sn",
+        },
+      };
+
+      const result = samlConfigV1.safeParse(config);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.attributeMapping.email).toBe("mail");
+        expect(result.data.attributeMapping.name).toBe("displayName");
+        expect(result.data.attributeMapping.firstName).toBe("givenName");
+        expect(result.data.attributeMapping.lastName).toBe("sn");
+      }
+    });
+  });
+});
+
+describe("extractAttribute helper", () => {
+  it("should extract string values", () => {
+    const attributes = { email: "user@example.com" };
+    const result = extractAttribute({
+      attributes,
+      attributeName: "email",
+    });
+    expect(result).toBe("user@example.com");
+  });
+
+  it("should extract first element from arrays", () => {
+    const attributes = { email: ["user@example.com", "other@example.com"] };
+    const result = extractAttribute({
+      attributes,
+      attributeName: "email",
+    });
+    expect(result).toBe("user@example.com");
+  });
+
+  it("should return undefined for missing attributes", () => {
+    const attributes = {};
+    const result = extractAttribute({
+      attributes,
+      attributeName: "email",
+    });
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined for empty arrays", () => {
+    const attributes = { email: [] };
+    const result = extractAttribute({
+      attributes,
+      attributeName: "email",
+    });
+    expect(result).toBeUndefined();
+  });
+
+  it("should convert non-string values to string", () => {
+    const attributes = { id: [12345] };
+    const result = extractAttribute({
+      attributes,
+      attributeName: "id",
+    });
+    expect(result).toBe("12345");
+  });
+});
+
+describe("extractGroups helper", () => {
+  it("should extract single group as array", () => {
+    const attributes = {
+      "http://schemas.xmlsoap.org/claims/Group": "Developers",
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "http://schemas.xmlsoap.org/claims/Group",
+    });
+    expect(result).toEqual(["Developers"]);
+  });
+
+  it("should extract multiple groups from array", () => {
+    const attributes = {
+      "http://schemas.xmlsoap.org/claims/Group": [
+        "Developers",
+        "Admins",
+        "Users",
+      ],
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "http://schemas.xmlsoap.org/claims/Group",
+    });
+    expect(result).toEqual(["Developers", "Admins", "Users"]);
+  });
+
+  it("should return empty array for missing group attribute", () => {
+    const attributes = {
+      email: "user@example.com",
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "http://schemas.xmlsoap.org/claims/Group",
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("should return empty array for empty group array", () => {
+    const attributes = {
+      "http://schemas.xmlsoap.org/claims/Group": [],
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "http://schemas.xmlsoap.org/claims/Group",
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("should convert non-string group values to strings", () => {
+    const attributes = {
+      groups: [123, "Developers", true],
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "groups",
+    });
+    expect(result).toEqual(["123", "Developers", "true"]);
+  });
+
+  it("should handle undefined/null values gracefully", () => {
+    const attributes = {
+      groups: undefined,
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "groups",
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("should handle complex group DNs from AD/LDAP", () => {
+    const attributes = {
+      memberOf: [
+        "CN=Developers,OU=Groups,DC=example,DC=com",
+        "CN=All-Users,OU=Groups,DC=example,DC=com",
+      ],
+    };
+    const result = extractGroups({
+      attributes,
+      groupAttribute: "memberOf",
+    });
+    expect(result).toEqual([
+      "CN=Developers,OU=Groups,DC=example,DC=com",
+      "CN=All-Users,OU=Groups,DC=example,DC=com",
+    ]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,595 @@
+import {
+  createBackendPlugin,
+  type AuthStrategy,
+  configString,
+  coreServices,
+  configBoolean,
+} from "@checkstack/backend-api";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  betterAuthExtensionPoint,
+  redirectToAuthError,
+} from "@checkstack/auth-backend";
+import { AuthApi } from "@checkstack/auth-common";
+import { z } from "zod";
+import { hashPassword } from "better-auth/crypto";
+import * as samlify from "samlify";
+import { extractAttribute, extractGroups } from "./helpers";
+
+// SAML Configuration Schema V1
+const _samlConfigV1 = z.object({
+  // Identity Provider configuration
+  idpMetadataUrl: configString({})
+    .url()
+    .optional()
+    .describe(
+      "URL to fetch IdP metadata XML (optional if providing metadata directly)",
+    ),
+  idpMetadata: configString({})
+    .optional()
+    .describe("IdP metadata XML content (used if URL is not provided)"),
+  idpEntityId: configString({})
+    .optional()
+    .describe("IdP Entity ID (extracted from metadata if not provided)"),
+  idpSingleSignOnUrl: configString({})
+    .url()
+    .optional()
+    .describe("IdP SSO URL (extracted from metadata if not provided)"),
+  idpCertificate: configString({ "x-secret": true })
+    .optional()
+    .describe("IdP X.509 certificate for signature validation (PEM format)"),
+
+  // Service Provider configuration
+  spEntityId: configString({})
+    .default("checkstack")
+    .describe("Service Provider Entity ID (your application identifier)"),
+  spPrivateKey: configString({ "x-secret": true })
+    .optional()
+    .describe("SP private key for signing requests (PEM format)"),
+  spCertificate: configString({})
+    .optional()
+    .describe("SP public certificate (PEM format)"),
+
+  // Attribute mapping
+  attributeMapping: z
+    .object({
+      email: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+        )
+        .describe("SAML attribute for email address"),
+      name: configString({})
+        .default("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name")
+        .describe("SAML attribute for display name"),
+      firstName: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+        )
+        .describe("SAML attribute for first name")
+        .optional(),
+      lastName: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
+        )
+        .describe("SAML attribute for last name")
+        .optional(),
+    })
+    .default({
+      email:
+        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+      name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+    })
+    .describe("Map SAML attributes to user fields"),
+
+  // Security options
+  wantAssertionsSigned: configBoolean({})
+    .default(true)
+    .describe("Require signed SAML assertions"),
+  signAuthnRequest: configBoolean({})
+    .default(false)
+    .describe("Sign authentication requests sent to IdP"),
+});
+
+// SAML Configuration Schema V2 - Adds group-to-role mapping
+const samlConfigV2 = z.object({
+  // Identity Provider configuration
+  idpMetadataUrl: configString({})
+    .url()
+    .optional()
+    .describe(
+      "URL to fetch IdP metadata XML (optional if providing metadata directly)",
+    ),
+  idpMetadata: configString({})
+    .optional()
+    .describe("IdP metadata XML content (used if URL is not provided)"),
+  idpEntityId: configString({})
+    .optional()
+    .describe("IdP Entity ID (extracted from metadata if not provided)"),
+  idpSingleSignOnUrl: configString({})
+    .url()
+    .optional()
+    .describe("IdP SSO URL (extracted from metadata if not provided)"),
+  idpCertificate: configString({ "x-secret": true })
+    .optional()
+    .describe("IdP X.509 certificate for signature validation (PEM format)"),
+
+  // Service Provider configuration
+  spEntityId: configString({})
+    .default("checkstack")
+    .describe("Service Provider Entity ID (your application identifier)"),
+  spPrivateKey: configString({ "x-secret": true })
+    .optional()
+    .describe("SP private key for signing requests (PEM format)"),
+  spCertificate: configString({})
+    .optional()
+    .describe("SP public certificate (PEM format)"),
+
+  // Attribute mapping
+  attributeMapping: z
+    .object({
+      email: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+        )
+        .describe("SAML attribute for email address"),
+      name: configString({})
+        .default("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name")
+        .describe("SAML attribute for display name"),
+      firstName: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+        )
+        .describe("SAML attribute for first name")
+        .optional(),
+      lastName: configString({})
+        .default(
+          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
+        )
+        .describe("SAML attribute for last name")
+        .optional(),
+    })
+    .default({
+      email:
+        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+      name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+    })
+    .describe("Map SAML attributes to user fields"),
+
+  // Group to Role Mapping
+  groupMapping: z
+    .object({
+      enabled: configBoolean({})
+        .default(false)
+        .describe("Enable group-to-role mapping"),
+      groupAttribute: configString({})
+        .default("http://schemas.xmlsoap.org/claims/Group")
+        .describe("SAML attribute containing group memberships"),
+      mappings: z
+        .array(
+          z.object({
+            directoryGroup: configString({}).describe(
+              "Directory group name or DN",
+            ),
+            checkstackRole: configString({
+              "x-options-resolver": "roleOptions",
+            }).describe("Checkstack role ID to assign"),
+          }),
+        )
+        .default([])
+        .describe("Map directory groups to Checkstack roles"),
+      defaultRole: configString({
+        "x-options-resolver": "roleOptions",
+      })
+        .optional()
+        .describe("Default role assigned to all SAML users (optional)"),
+    })
+    .default({
+      enabled: false,
+      groupAttribute: "http://schemas.xmlsoap.org/claims/Group",
+      mappings: [],
+    })
+    .describe("Map SAML groups to Checkstack roles"),
+
+  // Security options
+  wantAssertionsSigned: configBoolean({})
+    .default(true)
+    .describe("Require signed SAML assertions"),
+  signAuthnRequest: configBoolean({})
+    .default(false)
+    .describe("Sign authentication requests sent to IdP"),
+});
+
+type SamlConfig = z.infer<typeof samlConfigV2>;
+
+// SAML Strategy Definition
+const samlStrategy: AuthStrategy<SamlConfig> = {
+  id: "saml",
+  displayName: "SAML SSO",
+  description: "Enterprise Single Sign-On via SAML 2.0",
+  icon: "KeyRound",
+  configVersion: 2,
+  configSchema: samlConfigV2,
+  migrations: [
+    {
+      description: "Add group-to-role mapping configuration",
+      fromVersion: 1,
+      toVersion: 2,
+      migrate: (oldConfig: z.infer<typeof _samlConfigV1>) => ({
+        ...oldConfig,
+        groupMapping: {
+          enabled: false,
+          groupAttribute: "http://schemas.xmlsoap.org/claims/Group",
+          mappings: [],
+        },
+      }),
+    },
+  ],
+  requiresManualRegistration: false,
+  adminInstructions: `
+## SAML SSO Configuration
+
+Configure SAML 2.0 Single Sign-On to allow users to authenticate via your organization's Identity Provider:
+
+### Option 1: Using IdP Metadata URL (Recommended)
+1. Copy your IdP's metadata URL from your identity provider (Okta, Azure AD, OneLogin, ADFS)
+2. Paste it in the **IdP Metadata URL** field
+3. Set your **SP Entity ID** (a unique identifier for this application)
+
+### Option 2: Manual Configuration
+1. Enter the **IdP SSO URL** from your identity provider
+2. Paste the **IdP Certificate** (X.509 format, PEM encoded)
+3. Set the **IdP Entity ID** if different from the SSO URL
+
+### Service Provider Setup
+Configure your IdP with these values:
+- **SP Entity ID**: Your configured entity ID (default: \`checkstack\`)
+- **ACS URL**: \`https://yourdomain.com/api/auth-saml/saml/acs\`
+- **SP Metadata**: \`https://yourdomain.com/api/auth-saml/saml/metadata\`
+
+### Attribute Mapping
+Map SAML attributes from your IdP to user fields:
+- **Email**: Usually \`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\`
+- **Name**: Usually \`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name\`
+
+### Group to Role Mapping
+Map SAML groups to Checkstack roles for automatic role assignment:
+1. Enable **Group to Role Mapping**
+2. Set the **Group Attribute** (the SAML claim containing group memberships)
+3. Add mappings from directory groups to Checkstack roles
+4. Optionally set a **Default Role** for all SAML users
+
+> **Tip**: Most IdPs use standard claim URIs. Consult your IdP documentation for specific attribute names.
+`.trim(),
+};
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    // Register the SAML strategy
+    const extensionPoint = env.getExtensionPoint(betterAuthExtensionPoint);
+    extensionPoint.addStrategy(samlStrategy);
+
+    // Register init logic for SAML endpoints
+    env.registerInit({
+      deps: {
+        rpc: coreServices.rpc,
+        logger: coreServices.logger,
+        config: coreServices.config,
+        rpcClient: coreServices.rpcClient,
+      },
+      init: async ({ rpc, logger, config, rpcClient }) => {
+        logger.debug("[auth-saml-backend] Initializing SAML authentication...");
+
+        // Create auth client once for reuse
+        const authClient = rpcClient.forPlugin(AuthApi);
+
+        // Helper to create SP/IdP instances from current config
+        // Note: Instances are created fresh per request to ensure config changes
+        // propagate immediately across all horizontally scaled instances
+        const getSamlInstances = async (): Promise<{
+          sp: samlify.ServiceProviderInstance;
+          idp: samlify.IdentityProviderInstance;
+        }> => {
+          const samlConfig = await config.get("saml", samlConfigV2, 2);
+
+          if (!samlConfig) {
+            throw new Error("SAML configuration not found");
+          }
+
+          // Determine IdP metadata source
+          let idpMetadata: string | undefined = samlConfig.idpMetadata;
+
+          if (!idpMetadata && samlConfig.idpMetadataUrl) {
+            // Fetch metadata from URL
+            try {
+              const response = await fetch(samlConfig.idpMetadataUrl);
+              if (!response.ok) {
+                throw new Error(
+                  `Failed to fetch IdP metadata: ${response.status}`,
+                );
+              }
+              idpMetadata = await response.text();
+            } catch (error) {
+              logger.error("Failed to fetch IdP metadata:", error);
+              throw new Error("Failed to fetch IdP metadata from URL");
+            }
+          }
+
+          // Build the base URL from environment or request context
+          const baseUrl =
+            process.env.PUBLIC_URL ||
+            process.env.BASE_URL ||
+            "http://localhost:3000";
+          const acsUrl = `${baseUrl}/api/auth-saml/saml/acs`;
+
+          // Create Service Provider
+          const spConfig: Parameters<typeof samlify.ServiceProvider>[0] = {
+            entityID: samlConfig.spEntityId,
+            assertionConsumerService: [
+              {
+                Binding: samlify.Constants.namespace.binding.post,
+                Location: acsUrl,
+              },
+            ],
+            wantAssertionsSigned: samlConfig.wantAssertionsSigned,
+            authnRequestsSigned: samlConfig.signAuthnRequest,
+          };
+
+          if (samlConfig.spPrivateKey) {
+            spConfig.privateKey = samlConfig.spPrivateKey;
+          }
+          if (samlConfig.spCertificate) {
+            spConfig.signingCert = samlConfig.spCertificate;
+          }
+
+          const sp = samlify.ServiceProvider(spConfig);
+
+          // Create Identity Provider
+          let idp: samlify.IdentityProviderInstance;
+          if (idpMetadata) {
+            idp = samlify.IdentityProvider({
+              metadata: idpMetadata,
+            });
+          } else if (
+            samlConfig.idpSingleSignOnUrl &&
+            samlConfig.idpCertificate
+          ) {
+            idp = samlify.IdentityProvider({
+              entityID: samlConfig.idpEntityId || samlConfig.idpSingleSignOnUrl,
+              singleSignOnService: [
+                {
+                  Binding: samlify.Constants.namespace.binding.redirect,
+                  Location: samlConfig.idpSingleSignOnUrl,
+                },
+              ],
+              signingCert: samlConfig.idpCertificate,
+            });
+          } else {
+            throw new Error(
+              "IdP configuration incomplete: provide metadata URL/XML or manual SSO URL + certificate",
+            );
+          }
+
+          return { sp, idp };
+        };
+
+        // Helper function to sync user via RPC
+        const syncUser = async ({
+          nameId,
+          attributes,
+        }: {
+          nameId: string;
+          attributes: Record<string, unknown>;
+        }): Promise<{ userId: string; email: string; name: string }> => {
+          const samlConfig = await config.get("saml", samlConfigV2, 2);
+          if (!samlConfig) {
+            throw new Error("SAML configuration not found");
+          }
+
+          // Extract user info from SAML attributes
+          const mapping = samlConfig.attributeMapping;
+          const email =
+            extractAttribute({ attributes, attributeName: mapping.email }) ||
+            nameId;
+
+          // Build name from available attributes
+          let name: string;
+          const extractedName = extractAttribute({
+            attributes,
+            attributeName: mapping.name,
+          });
+          if (extractedName) {
+            name = extractedName;
+          } else if (mapping.firstName && mapping.lastName) {
+            const firstName = extractAttribute({
+              attributes,
+              attributeName: mapping.firstName,
+            });
+            const lastName = extractAttribute({
+              attributes,
+              attributeName: mapping.lastName,
+            });
+            name =
+              firstName && lastName
+                ? `${firstName} ${lastName}`
+                : email.split("@")[0];
+          } else {
+            name = email.split("@")[0];
+          }
+
+          // Extract groups and map to roles if enabled
+          let syncRoles: string[] | undefined;
+          let managedRoleIds: string[] | undefined;
+          if (samlConfig.groupMapping?.enabled) {
+            const groups = extractGroups({
+              attributes,
+              groupAttribute: samlConfig.groupMapping.groupAttribute,
+            });
+
+            // Map groups to roles
+            const mappedRoles = samlConfig.groupMapping.mappings
+              .filter((m) => groups.includes(m.directoryGroup))
+              .map((m) => m.checkstackRole);
+
+            // Add default role if configured
+            if (samlConfig.groupMapping.defaultRole) {
+              mappedRoles.push(samlConfig.groupMapping.defaultRole);
+            }
+
+            // Deduplicate roles
+            syncRoles = [...new Set(mappedRoles)];
+
+            // Collect all managed role IDs (all roles in mappings + default)
+            // These are roles controlled by directory - will be removed if user leaves groups
+            const allManagedRoles = samlConfig.groupMapping.mappings.map(
+              (m) => m.checkstackRole,
+            );
+            if (samlConfig.groupMapping.defaultRole) {
+              allManagedRoles.push(samlConfig.groupMapping.defaultRole);
+            }
+            managedRoleIds = [...new Set(allManagedRoles)];
+
+            if (syncRoles.length > 0) {
+              logger.debug(
+                `SAML user ${email} will be assigned roles: ${syncRoles.join(", ")}`,
+              );
+            }
+          }
+
+          // Use RPC to upsert user - always create/update SAML users
+          const hashedPassword = await hashPassword(crypto.randomUUID());
+
+          const { userId, created } = await authClient.upsertExternalUser({
+            email,
+            name,
+            providerId: "saml",
+            accountId: nameId,
+            password: hashedPassword,
+            autoUpdateUser: true,
+            syncRoles,
+            managedRoleIds,
+          });
+
+          if (created) {
+            logger.info(`Created new user from SAML: ${email}`);
+          } else {
+            logger.debug(`Updated SAML user: ${email}`);
+          }
+
+          return { userId, email, name };
+        };
+
+        // SSO initiation endpoint: /saml/login
+        rpc.registerHttpHandler(async () => {
+          try {
+            const { sp, idp } = await getSamlInstances();
+
+            // Create login request
+            const { context } = sp.createLoginRequest(idp, "redirect");
+
+            // Redirect to IdP
+            return new Response(undefined, {
+              status: 302,
+              headers: {
+                Location: context,
+              },
+            });
+          } catch (error) {
+            logger.error("SAML login initiation failed:", error);
+            return redirectToAuthError(
+              error instanceof Error
+                ? error.message
+                : "Failed to initiate SAML login",
+            );
+          }
+        }, "saml/login");
+
+        // Assertion Consumer Service: /saml/acs
+        rpc.registerHttpHandler(async (req: Request) => {
+          try {
+            const { sp, idp } = await getSamlInstances();
+
+            // Parse the POST body
+            const formData = await req.formData();
+            const samlResponse = formData.get("SAMLResponse");
+
+            if (!samlResponse || typeof samlResponse !== "string") {
+              return redirectToAuthError("Missing SAML response");
+            }
+
+            // Parse and validate the SAML response
+            const parseResult = await sp.parseLoginResponse(idp, "post", {
+              body: { SAMLResponse: samlResponse },
+            });
+
+            if (!parseResult.extract) {
+              return redirectToAuthError("Failed to parse SAML assertion");
+            }
+
+            const { nameID, attributes } = parseResult.extract;
+
+            if (!nameID) {
+              return redirectToAuthError("Missing NameID in SAML assertion");
+            }
+
+            // Sync user to database
+            const { userId, email } = await syncUser({
+              nameId: nameID,
+              attributes: attributes ?? {},
+            });
+
+            // Create session via RPC
+            const sessionToken = crypto.randomUUID();
+            const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days
+
+            await authClient.createSession({
+              userId,
+              token: sessionToken,
+              expiresAt,
+            });
+
+            logger.info(`Created session for SAML user: ${email}`);
+
+            // Redirect to home with session cookie
+            return new Response(undefined, {
+              status: 302,
+              headers: {
+                Location: "/",
+                "Set-Cookie": `better-auth.session_token=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${
+                  7 * 24 * 60 * 60
+                }`,
+              },
+            });
+          } catch (error) {
+            logger.error("SAML ACS error:", error);
+            const message =
+              error instanceof Error
+                ? error.message
+                : "SAML authentication failed";
+            return redirectToAuthError(message);
+          }
+        }, "saml/acs");
+
+        // SP Metadata endpoint: /saml/metadata
+        rpc.registerHttpHandler(async () => {
+          try {
+            const { sp } = await getSamlInstances();
+            const metadata = sp.getMetadata();
+
+            return new Response(metadata, {
+              status: 200,
+              headers: {
+                "Content-Type": "application/xml",
+              },
+            });
+          } catch (error) {
+            logger.error("Failed to generate SP metadata:", error);
+            return new Response("Failed to generate metadata", { status: 500 });
+          }
+        }, "saml/metadata");
+
+        logger.debug("✅ SAML authentication initialized");
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Auth SAML backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "auth-saml",
+});

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}