feat(sso): add InResponseTo validation (#6557)

Author: Paola3stefania

docs/content/docs/plugins/sso.mdx

@@ -707,6 +707,115 @@ mapping: {
 }
 ```
 
+## SAML Security
+
+The SSO plugin includes optional security features to protect against common SAML vulnerabilities.
+
+### AuthnRequest / InResponseTo Validation
+
+You can enable InResponseTo validation for SP-initiated SAML flows. When enabled, the plugin tracks AuthnRequest IDs and validates the `InResponseTo` attribute in SAML responses. This prevents:
+
+- **Unsolicited responses**: Responses not triggered by a legitimate login request
+- **Replay attacks**: Reusing old SAML responses
+- **Cross-provider injection**: Responses meant for a different provider
+
+<Callout type="info">
+This feature is **opt-in** to ensure backward compatibility. Enable it explicitly for enhanced security.
+</Callout>
+
+#### Enabling Validation (Single Instance)
+
+For single-instance deployments, enable validation with the built-in in-memory store:
+
+```ts title="auth.ts"
+import { betterAuth } from "better-auth";
+import { sso } from "@better-auth/sso";
+
+const auth = betterAuth({
+    plugins: [
+        sso({
+            saml: {
+                // Enable InResponseTo validation
+                enableInResponseToValidation: true,
+                // Optionally reject IdP-initiated SSO (stricter security)
+                allowIdpInitiated: false,
+                // Custom TTL for AuthnRequest validity (default: 5 minutes)
+                requestTTL: 10 * 60 * 1000, // 10 minutes
+            },
+        }),
+    ],
+});
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enableInResponseToValidation` | `boolean` | `false` | Enable InResponseTo validation for SP-initiated flows. |
+| `allowIdpInitiated` | `boolean` | `true` | Allow IdP-initiated SSO (responses without InResponseTo). Set to `false` for stricter security. Only applies when validation is enabled. |
+| `requestTTL` | `number` | `300000` (5 min) | Time-to-live for AuthnRequest records in milliseconds. Requests older than this will be rejected. |
+| `authnRequestStore` | `AuthnRequestStore` | In-memory | Custom store implementation. Providing a custom store automatically enables validation. |
+
+#### Multi-Instance Deployments (Production)
+
+<Callout type="warning">
+For multi-instance deployments (load-balanced servers, serverless, etc.), you **must** provide a shared store like Redis. The default in-memory store only works for single-instance deployments.
+</Callout>
+
+Providing a custom `authnRequestStore` automatically enables InResponseTo validation:
+
+```ts title="auth.ts"
+import { betterAuth } from "better-auth";
+import { sso, type AuthnRequestStore } from "@better-auth/sso";
+
+// Example Redis-backed store
+const redisAuthnRequestStore: AuthnRequestStore = {
+    async save(record) {
+        const ttl = Math.ceil((record.expiresAt - Date.now()) / 1000);
+        await redis.set(
+            `authn:${record.id}`,
+            JSON.stringify(record),
+            "EX",
+            ttl
+        );
+    },
+    async get(id) {
+        const data = await redis.get(`authn:${id}`);
+        if (!data) return null;
+        const record = JSON.parse(data);
+        if (record.expiresAt < Date.now()) {
+            await redis.del(`authn:${id}`);
+            return null;
+        }
+        return record;
+    },
+    async delete(id) {
+        await redis.del(`authn:${id}`);
+    },
+};
+
+const auth = betterAuth({
+    plugins: [
+        sso({
+            saml: {
+                // Providing a store automatically enables validation
+                authnRequestStore: redisAuthnRequestStore,
+                // Optionally configure other options
+                allowIdpInitiated: false,
+            },
+        }),
+    ],
+});
+```
+
+#### Error Handling
+
+When InResponseTo validation fails, users are redirected with an error query parameter:
+
+- `?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID` — The request ID was not found or has expired
+- `?error=invalid_saml_response&error_description=Provider+mismatch` — The response was meant for a different provider
+- `?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed` — IdP-initiated SSO is disabled
+
 ## Domain verification
 
 Domain verification allows your application to automatically trust a new SSO provider
@@ -965,6 +1074,32 @@ If you want to allow account linking for specific trusted providers, enable the
             }
         },
     },
+    saml: {
+        description: "SAML security options for AuthnRequest/InResponseTo validation.",
+        type: "object",
+        properties: {
+            enableInResponseToValidation: {
+                description: "Enable InResponseTo validation for SP-initiated SAML flows. Opt-in for backward compatibility.",
+                type: "boolean",
+                default: false,
+            },
+            allowIdpInitiated: {
+                description: "Allow IdP-initiated SSO (unsolicited SAML responses). Set to false for stricter security. Only applies when validation is enabled.",
+                type: "boolean",
+                default: true,
+            },
+            requestTTL: {
+                description: "TTL for AuthnRequest records in milliseconds. Only applies when validation is enabled.",
+                type: "number",
+                default: 300000,
+            },
+            authnRequestStore: {
+                description: "Custom AuthnRequest store for multi-instance deployments (e.g., Redis). Providing a store automatically enables validation.",
+                type: "AuthnRequestStore",
+                required: false,
+            },
+        },
+    },
     modelName: {
         description: "The model name for the SSO provider table",
         type: "string",

packages/sso/src/authn-request-store.ts

@@ -0,0 +1,76 @@
+/**
+ * AuthnRequest Store
+ *
+ * Tracks SAML AuthnRequest IDs to enable InResponseTo validation.
+ * This prevents:
+ * - Unsolicited SAML responses
+ * - Cross-provider response injection
+ * - Replay attacks
+ * - Expired login completions
+ */
+
+export interface AuthnRequestRecord {
+	id: string;
+	providerId: string;
+	createdAt: number;
+	expiresAt: number;
+}
+
+export interface AuthnRequestStore {
+	save(record: AuthnRequestRecord): Promise<void>;
+	get(id: string): Promise<AuthnRequestRecord | null>;
+	delete(id: string): Promise<void>;
+}
+
+/**
+ * Default TTL for AuthnRequest records (5 minutes).
+ * This should be sufficient for most IdPs while protecting against stale requests.
+ */
+export const DEFAULT_AUTHN_REQUEST_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * In-memory implementation of AuthnRequestStore.
+ * ⚠️ Only suitable for testing or single-instance non-serverless deployments.
+ * For production, rely on the default behavior (uses verification table)
+ * or provide a custom Redis-backed store.
+ */
+export function createInMemoryAuthnRequestStore(): AuthnRequestStore {
+	const store = new Map<string, AuthnRequestRecord>();
+
+	const cleanup = () => {
+		const now = Date.now();
+		for (const [id, record] of store.entries()) {
+			if (record.expiresAt < now) {
+				store.delete(id);
+			}
+		}
+	};
+
+	const cleanupInterval = setInterval(cleanup, 60 * 1000);
+
+	if (typeof cleanupInterval.unref === "function") {
+		cleanupInterval.unref();
+	}
+
+	return {
+		async save(record: AuthnRequestRecord): Promise<void> {
+			store.set(record.id, record);
+		},
+
+		async get(id: string): Promise<AuthnRequestRecord | null> {
+			const record = store.get(id);
+			if (!record) {
+				return null;
+			}
+			if (record.expiresAt < Date.now()) {
+				store.delete(id);
+				return null;
+			}
+			return record;
+		},
+
+		async delete(id: string): Promise<void> {
+			store.delete(id);
+		},
+	};
+}

packages/sso/src/authn-request.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+	createInMemoryAuthnRequestStore,
+	DEFAULT_AUTHN_REQUEST_TTL_MS,
+} from "./authn-request-store";
+
+describe("AuthnRequest Store", () => {
+	describe("In-Memory Store", () => {
+		it("should save and retrieve an AuthnRequest record", async () => {
+			const store = createInMemoryAuthnRequestStore();
+
+			const record = {
+				id: "_test-request-id-1",
+				providerId: "saml-provider-1",
+				createdAt: Date.now(),
+				expiresAt: Date.now() + DEFAULT_AUTHN_REQUEST_TTL_MS,
+			};
+
+			await store.save(record);
+			const retrieved = await store.get(record.id);
+
+			expect(retrieved).toEqual(record);
+		});
+
+		it("should return null for non-existent request ID", async () => {
+			const store = createInMemoryAuthnRequestStore();
+
+			const retrieved = await store.get("_non-existent-id");
+
+			expect(retrieved).toBeNull();
+		});
+
+		it("should return null for expired request ID", async () => {
+			const store = createInMemoryAuthnRequestStore();
+
+			const record = {
+				id: "_expired-request-id",
+				providerId: "saml-provider-1",
+				createdAt: Date.now() - 10000,
+				expiresAt: Date.now() - 1000, // Already expired
+			};
+
+			await store.save(record);
+			const retrieved = await store.get(record.id);
+
+			expect(retrieved).toBeNull();
+		});
+
+		it("should delete a request ID", async () => {
+			const store = createInMemoryAuthnRequestStore();
+
+			const record = {
+				id: "_delete-me",
+				providerId: "saml-provider-1",
+				createdAt: Date.now(),
+				expiresAt: Date.now() + DEFAULT_AUTHN_REQUEST_TTL_MS,
+			};
+
+			await store.save(record);
+			await store.delete(record.id);
+
+			const retrieved = await store.get(record.id);
+			expect(retrieved).toBeNull();
+		});
+
+		it("should handle multiple providers with different request IDs", async () => {
+			const store = createInMemoryAuthnRequestStore();
+
+			const record1 = {
+				id: "_request-provider-1",
+				providerId: "saml-provider-1",
+				createdAt: Date.now(),
+				expiresAt: Date.now() + DEFAULT_AUTHN_REQUEST_TTL_MS,
+			};
+
+			const record2 = {
+				id: "_request-provider-2",
+				providerId: "saml-provider-2",
+				createdAt: Date.now(),
+				expiresAt: Date.now() + DEFAULT_AUTHN_REQUEST_TTL_MS,
+			};
+
+			await store.save(record1);
+			await store.save(record2);
+
+			const retrieved1 = await store.get(record1.id);
+			const retrieved2 = await store.get(record2.id);
+
+			expect(retrieved1?.providerId).toBe("saml-provider-1");
+			expect(retrieved2?.providerId).toBe("saml-provider-2");
+		});
+	});
+
+	describe("DEFAULT_AUTHN_REQUEST_TTL_MS", () => {
+		it("should be 5 minutes in milliseconds", () => {
+			expect(DEFAULT_AUTHN_REQUEST_TTL_MS).toBe(5 * 60 * 1000);
+		});
+	});
+});

packages/sso/src/index.ts

@@ -1,6 +1,14 @@
 import type { BetterAuthPlugin } from "better-auth";
 import { XMLValidator } from "fast-xml-parser";
 import * as saml from "samlify";
+import type {
+	AuthnRequestRecord,
+	AuthnRequestStore,
+} from "./authn-request-store";
+import {
+	createInMemoryAuthnRequestStore,
+	DEFAULT_AUTHN_REQUEST_TTL_MS,
+} from "./authn-request-store";
 import {
 	requestDomainVerification,
 	verifyDomain,
@@ -16,6 +24,8 @@ import {
 import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "./types";
 
 export type { SAMLConfig, OIDCConfig, SSOOptions, SSOProvider };
+export type { AuthnRequestStore, AuthnRequestRecord };
+export { createInMemoryAuthnRequestStore, DEFAULT_AUTHN_REQUEST_TTL_MS };
 
 const fastValidator = {
 	async validate(xml: string) {
@@ -71,19 +81,21 @@ export function sso<O extends SSOOptions>(
 };
 
 export function sso<O extends SSOOptions>(options?: O | undefined): any {
+	const optionsWithStore = options as O;
+
 	let endpoints = {
 		spMetadata: spMetadata(),
-		registerSSOProvider: registerSSOProvider(options as O),
-		signInSSO: signInSSO(options as O),
-		callbackSSO: callbackSSO(options as O),
-		callbackSSOSAML: callbackSSOSAML(options as O),
-		acsEndpoint: acsEndpoint(options as O),
+		registerSSOProvider: registerSSOProvider(optionsWithStore),
+		signInSSO: signInSSO(optionsWithStore),
+		callbackSSO: callbackSSO(optionsWithStore),
+		callbackSSOSAML: callbackSSOSAML(optionsWithStore),
+		acsEndpoint: acsEndpoint(optionsWithStore),
 	};
 
 	if (options?.domainVerification?.enabled) {
 		const domainVerificationEndpoints = {
-			requestDomainVerification: requestDomainVerification(options as O),
-			verifyDomain: verifyDomain(options as O),
+			requestDomainVerification: requestDomainVerification(optionsWithStore),
+			verifyDomain: verifyDomain(optionsWithStore),
 		};
 
 		endpoints = {