@better-auth/sso 1.4.17 → 1.5.0-beta.10

package/src/routes/sso.ts

@@ -11,6 +11,7 @@ import {
 import {
 	APIError,
 	createAuthEndpoint,
+	getSessionFromCtx,
 	sessionMiddleware,
 } from "better-auth/api";
 import { setSessionCookie } from "better-auth/cookies";
@@ -52,8 +53,9 @@ import {
 	validateSAMLAlgorithms,
 	validateSingleAssertion,
 } from "../saml";
+import { generateRelayState, parseRelayState } from "../saml-state";
 import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "../types";
-import { safeJsonParse, validateEmailDomain } from "../utils";
+import { domainMatches, safeJsonParse, validateEmailDomain } from "../utils";
 
 export interface TimestampValidationOptions {
 	clockSkew?: number;
@@ -165,6 +167,8 @@ const spMetadataQuerySchema = z.object({
 	format: z.enum(["xml", "json"]).default("xml"),
 });
 
+type RelayState = Awaited<ReturnType<typeof parseRelayState>>;
+
 export const spMetadata = () => {
 	return createAuthEndpoint(
 		"/sso/saml2/sp/metadata",
@@ -225,6 +229,7 @@ export const spMetadata = () => {
 							},
 						],
 						wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
+						authnRequestsSigned: parsedSamlConfig.authnRequestsSigned || false,
 						nameIDFormat: parsedSamlConfig.identifierFormat
 							? [parsedSamlConfig.identifierFormat]
 							: undefined,
@@ -247,7 +252,8 @@ const ssoProviderBodySchema = z.object({
 		description: "The issuer of the provider",
 	}),
 	domain: z.string({}).meta({
-		description: "The domain of the provider. This is used for email matching",
+		description:
+			"The domain(s) of the provider. For enterprise multi-domain SSO where a single IdP serves multiple email domains, use comma-separated values (e.g., 'company.com,subsidiary.com,acquired-company.com')",
 	}),
 	oidcConfig: z
 		.object({
@@ -385,6 +391,7 @@ const ssoProviderBodySchema = z.object({
 				encPrivateKeyPass: z.string().optional(),
 			}),
 			wantAssertionsSigned: z.boolean().optional(),
+			authnRequestsSigned: z.boolean().optional(),
 			signatureAlgorithm: z.string().optional(),
 			digestAlgorithm: z.string().optional(),
 			identifierFormat: z.string().optional(),
@@ -830,6 +837,7 @@ export const registerSSOProvider = <O extends SSOOptions>(options: O) => {
 								idpMetadata: body.samlConfig.idpMetadata,
 								spMetadata: body.samlConfig.spMetadata,
 								wantAssertionsSigned: body.samlConfig.wantAssertionsSigned,
+								authnRequestsSigned: body.samlConfig.authnRequestsSigned,
 								signatureAlgorithm: body.samlConfig.signatureAlgorithm,
 								digestAlgorithm: body.samlConfig.digestAlgorithm,
 								identifierFormat: body.samlConfig.identifierFormat,
@@ -1121,38 +1129,58 @@ export const signInSSO = (options?: SSOOptions) => {
 			}
 			// Try to find provider in database
 			if (!provider) {
-				provider = await ctx.context.adapter
-					.findOne<SSOProvider<SSOOptions>>({
-						model: "ssoProvider",
-						where: [
-							{
-								field: providerId
-									? "providerId"
-									: orgId
-										? "organizationId"
-										: "domain",
-								value: providerId || orgId || domain!,
-							},
-						],
-					})
-					.then((res) => {
-						if (!res) {
-							return null;
-						}
-						return {
-							...res,
-							oidcConfig: res.oidcConfig
-								? safeJsonParse<OIDCConfig>(
-										res.oidcConfig as unknown as string,
-									) || undefined
-								: undefined,
-							samlConfig: res.samlConfig
-								? safeJsonParse<SAMLConfig>(
-										res.samlConfig as unknown as string,
-									) || undefined
-								: undefined,
-						};
-					});
+				const parseProvider = (res: SSOProvider<SSOOptions> | null) => {
+					if (!res) return null;
+					return {
+						...res,
+						oidcConfig: res.oidcConfig
+							? safeJsonParse<OIDCConfig>(
+									res.oidcConfig as unknown as string,
+								) || undefined
+							: undefined,
+						samlConfig: res.samlConfig
+							? safeJsonParse<SAMLConfig>(
+									res.samlConfig as unknown as string,
+								) || undefined
+							: undefined,
+					};
+				};
+
+				if (providerId || orgId) {
+					// Exact match for providerId or orgId
+					provider = parseProvider(
+						await ctx.context.adapter.findOne<SSOProvider<SSOOptions>>({
+							model: "ssoProvider",
+							where: [
+								{
+									field: providerId ? "providerId" : "organizationId",
+									value: providerId || orgId!,
+								},
+							],
+						}),
+					);
+				} else if (domain) {
+					// For domain lookup, support comma-separated domains
+					// First try exact match (fast path)
+					provider = parseProvider(
+						await ctx.context.adapter.findOne<SSOProvider<SSOOptions>>({
+							model: "ssoProvider",
+							where: [{ field: "domain", value: domain }],
+						}),
+					);
+					// If not found, search all providers for comma-separated domain match
+					if (!provider) {
+						const allProviders = await ctx.context.adapter.findMany<
+							SSOProvider<SSOOptions>
+						>({
+							model: "ssoProvider",
+						});
+						const matchingProvider = allProviders.find((p) =>
+							domainMatches(domain, p.domain),
+						);
+						provider = parseProvider(matchingProvider ?? null);
+					}
+				}
 			}
 
 			if (!provider) {
@@ -1241,6 +1269,17 @@ export const signInSSO = (options?: SSOOptions) => {
 					});
 				}
 
+				if (
+					parsedSamlConfig.authnRequestsSigned &&
+					!parsedSamlConfig.spMetadata?.privateKey &&
+					!parsedSamlConfig.privateKey
+				) {
+					ctx.context.logger.warn(
+						"authnRequestsSigned is enabled but no privateKey provided - AuthnRequests will not be signed",
+						{ providerId: provider.providerId },
+					);
+				}
+
 				let metadata = parsedSamlConfig.spMetadata.metadata;
 
 				if (!metadata) {
@@ -1260,6 +1299,8 @@ export const signInSSO = (options?: SSOOptions) => {
 								],
 								wantMessageSigned:
 									parsedSamlConfig.wantAssertionsSigned || false,
+								authnRequestsSigned:
+									parsedSamlConfig.authnRequestsSigned || false,
 								nameIDFormat: parsedSamlConfig.identifierFormat
 									? [parsedSamlConfig.identifierFormat]
 									: undefined,
@@ -1270,6 +1311,10 @@ export const signInSSO = (options?: SSOOptions) => {
 				const sp = saml.ServiceProvider({
 					metadata: metadata,
 					allowCreate: true,
+					privateKey:
+						parsedSamlConfig.spMetadata?.privateKey ||
+						parsedSamlConfig.privateKey,
+					privateKeyPass: parsedSamlConfig.spMetadata?.privateKeyPass,
 				});
 
 				const idp = saml.IdentityProvider({
@@ -1293,6 +1338,12 @@ export const signInSSO = (options?: SSOOptions) => {
 					});
 				}
 
+				const { state: relayState } = await generateRelayState(
+					ctx,
+					undefined,
+					false,
+				);
+
 				const shouldSaveRequest =
 					loginRequest.id && options?.saml?.enableInResponseToValidation;
 				if (shouldSaveRequest) {
@@ -1311,9 +1362,7 @@ export const signInSSO = (options?: SSOOptions) => {
 				}
 
 				return ctx.json({
-					url: `${loginRequest.context}&RelayState=${encodeURIComponent(
-						body.callbackURL,
-					)}`,
+					url: `${loginRequest.context}&RelayState=${encodeURIComponent(relayState)}`,
 					redirect: true,
 				});
 			}
@@ -1683,12 +1732,71 @@ const callbackSSOSAMLBodySchema = z.object({
 	RelayState: z.string().optional(),
 });
 
+/**
+ * Validates and returns a safe redirect URL.
+ * - Prevents open redirect attacks by validating against trusted origins
+ * - Prevents redirect loops by checking if URL points to callback route
+ * - Falls back to appOrigin if URL is invalid or unsafe
+ */
+const getSafeRedirectUrl = (
+	url: string | undefined,
+	callbackPath: string,
+	appOrigin: string,
+	isTrustedOrigin: (
+		url: string,
+		settings?: { allowRelativePaths: boolean },
+	) => boolean,
+): string => {
+	if (!url) {
+		return appOrigin;
+	}
+
+	if (url.startsWith("/") && !url.startsWith("//")) {
+		try {
+			const absoluteUrl = new URL(url, appOrigin);
+			if (absoluteUrl.origin !== appOrigin) {
+				return appOrigin;
+			}
+			const callbackPathname = new URL(callbackPath).pathname;
+			if (absoluteUrl.pathname === callbackPathname) {
+				return appOrigin;
+			}
+		} catch {
+			return appOrigin;
+		}
+		return url;
+	}
+
+	if (!isTrustedOrigin(url, { allowRelativePaths: false })) {
+		return appOrigin;
+	}
+
+	try {
+		const callbackPathname = new URL(callbackPath).pathname;
+		const urlPathname = new URL(url).pathname;
+		if (urlPathname === callbackPathname) {
+			return appOrigin;
+		}
+	} catch {
+		if (url === callbackPath || url.startsWith(`${callbackPath}?`)) {
+			return appOrigin;
+		}
+	}
+
+	return url;
+};
+
 export const callbackSSOSAML = (options?: SSOOptions) => {
 	return createAuthEndpoint(
 		"/sso/saml2/callback/:providerId",
 		{
-			method: "POST",
-			body: callbackSSOSAMLBodySchema,
+			method: ["GET", "POST"],
+			body: callbackSSOSAMLBodySchema.optional(),
+			query: z
+				.object({
+					RelayState: z.string().optional(),
+				})
+				.optional(),
 			metadata: {
 				...HIDE_METADATA,
 				allowedMediaTypes: [
@@ -1699,7 +1807,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					operationId: "handleSAMLCallback",
 					summary: "Callback URL for SAML provider",
 					description:
-						"This endpoint is used as the callback URL for SAML providers.",
+						"This endpoint is used as the callback URL for SAML providers. Supports both GET and POST methods for IdP-initiated and SP-initiated flows.",
 					responses: {
 						"302": {
 							description: "Redirects to the callback URL",
@@ -1715,8 +1823,41 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 			},
 		},
 		async (ctx) => {
-			const { SAMLResponse, RelayState } = ctx.body;
 			const { providerId } = ctx.params;
+			const appOrigin = new URL(ctx.context.baseURL).origin;
+			const errorURL =
+				ctx.context.options.onAPIError?.errorURL || `${appOrigin}/error`;
+			const currentCallbackPath = `${ctx.context.baseURL}/sso/saml2/callback/${providerId}`;
+
+			// Determine if this is a GET request by checking both method AND body presence
+			// When called via auth.api.*, ctx.method may not be reliable, so we also check for body
+			const isGetRequest = ctx.method === "GET" && !ctx.body?.SAMLResponse;
+
+			if (isGetRequest) {
+				const session = await getSessionFromCtx(ctx);
+
+				if (!session?.session) {
+					throw ctx.redirect(`${errorURL}?error=invalid_request`);
+				}
+
+				const relayState = ctx.query?.RelayState as string | undefined;
+				const safeRedirectUrl = getSafeRedirectUrl(
+					relayState,
+					currentCallbackPath,
+					appOrigin,
+					(url, settings) => ctx.context.isTrustedOrigin(url, settings),
+				);
+
+				throw ctx.redirect(safeRedirectUrl);
+			}
+
+			if (!ctx.body?.SAMLResponse) {
+				throw new APIError("BAD_REQUEST", {
+					message: "SAMLResponse is required for POST requests",
+				});
+			}
+
+			const { SAMLResponse } = ctx.body;
 
 			const maxResponseSize =
 				options?.saml?.maxResponseSize ?? DEFAULT_MAX_SAML_RESPONSE_SIZE;
@@ -1726,6 +1867,14 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 				});
 			}
 
+			let relayState: RelayState | null = null;
+			if (ctx.body.RelayState) {
+				try {
+					relayState = await parseRelayState(ctx);
+				} catch {
+					relayState = null;
+				}
+			}
 			let provider: SSOProvider<SSOOptions> | null = null;
 			if (options?.defaultSSO?.length) {
 				const matchingDefault = options.defaultSSO.find(
@@ -1846,7 +1995,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 				parsedResponse = await sp.parseLoginResponse(idp, "post", {
 					body: {
 						SAMLResponse,
-						RelayState: RelayState || undefined,
+						RelayState: ctx.body.RelayState || undefined,
 					},
 				});
 
@@ -1909,7 +2058,9 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 							{ inResponseTo, providerId: provider.providerId },
 						);
 						const redirectUrl =
-							RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+							relayState?.callbackURL ||
+							parsedSamlConfig.callbackUrl ||
+							ctx.context.baseURL;
 						throw ctx.redirect(
 							`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`,
 						);
@@ -1929,7 +2080,9 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
 						);
 						const redirectUrl =
-							RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+							relayState?.callbackURL ||
+							parsedSamlConfig.callbackUrl ||
+							ctx.context.baseURL;
 						throw ctx.redirect(
 							`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`,
 						);
@@ -1944,7 +2097,9 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 						{ providerId: provider.providerId },
 					);
 					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+						relayState?.callbackURL ||
+						parsedSamlConfig.callbackUrl ||
+						ctx.context.baseURL;
 					throw ctx.redirect(
 						`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`,
 					);
@@ -1997,7 +2152,9 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 						},
 					);
 					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+						relayState?.callbackURL ||
+						parsedSamlConfig.callbackUrl ||
+						ctx.context.baseURL;
 					throw ctx.redirect(
 						`${redirectUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`,
 					);
@@ -2032,7 +2189,9 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					]),
 				),
 				id: attributes[mapping.id || "nameID"] || extract.nameID,
-				email: attributes[mapping.email || "email"] || extract.nameID,
+				email: (
+					attributes[mapping.email || "email"] || extract.nameID
+				).toLowerCase(),
 				name:
 					[
 						attributes[mapping.firstName || "givenName"],
@@ -2071,7 +2230,9 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					validateEmailDomain(userInfo.email as string, provider.domain));
 
 			const callbackUrl =
-				RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+				relayState?.callbackURL ||
+				parsedSamlConfig.callbackUrl ||
+				ctx.context.baseURL;
 
 			const result = await handleOAuthUserInfo(ctx, {
 				userInfo: {
@@ -2122,7 +2283,14 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 			});
 
 			await setSessionCookie(ctx, { session, user });
-			throw ctx.redirect(callbackUrl);
+
+			const safeRedirectUrl = getSafeRedirectUrl(
+				relayState?.callbackURL || parsedSamlConfig.callbackUrl,
+				currentCallbackPath,
+				appOrigin,
+				(url, settings) => ctx.context.isTrustedOrigin(url, settings),
+			);
+			throw ctx.redirect(safeRedirectUrl);
 		},
 	);
 };
@@ -2483,7 +2651,9 @@ export const acsEndpoint = (options?: SSOOptions) => {
 					]),
 				),
 				id: attributes[mapping.id || "nameID"] || extract.nameID,
-				email: attributes[mapping.email || "email"] || extract.nameID,
+				email: (
+					attributes[mapping.email || "email"] || extract.nameID
+				).toLowerCase(),
 				name:
 					[
 						attributes[mapping.firstName || "givenName"],

package/src/saml-state.ts

@@ -0,0 +1,78 @@
+import type { GenericEndpointContext, StateData } from "better-auth";
+import { generateGenericState, parseGenericState } from "better-auth";
+import { generateRandomString } from "better-auth/crypto";
+import { APIError } from "better-call";
+
+export async function generateRelayState(
+	c: GenericEndpointContext,
+	link:
+		| {
+				email: string;
+				userId: string;
+		  }
+		| undefined,
+	additionalData: Record<string, any> | false | undefined,
+) {
+	const callbackURL = c.body.callbackURL;
+	if (!callbackURL) {
+		throw new APIError("BAD_REQUEST", {
+			message: "callbackURL is required",
+		});
+	}
+
+	const codeVerifier = generateRandomString(128);
+	const stateData: StateData = {
+		...(additionalData ? additionalData : {}),
+		callbackURL,
+		codeVerifier,
+		errorURL: c.body.errorCallbackURL,
+		newUserURL: c.body.newUserCallbackURL,
+		link,
+		/**
+		 * This is the actual expiry time of the state
+		 */
+		expiresAt: Date.now() + 10 * 60 * 1000,
+		requestSignUp: c.body.requestSignUp,
+	};
+
+	try {
+		return generateGenericState(c, stateData, {
+			cookieName: "relay_state",
+		});
+	} catch (error) {
+		c.context.logger.error(
+			"Failed to create verification for relay state",
+			error,
+		);
+		throw new APIError("INTERNAL_SERVER_ERROR", {
+			message: "State error: Unable to create verification for relay state",
+			cause: error,
+		});
+	}
+}
+
+export async function parseRelayState(c: GenericEndpointContext) {
+	const state = c.body.RelayState;
+	const errorURL =
+		c.context.options.onAPIError?.errorURL || `${c.context.baseURL}/error`;
+
+	let parsedData: StateData;
+
+	try {
+		parsedData = await parseGenericState(c, state, {
+			cookieName: "relay_state",
+		});
+	} catch (error) {
+		c.context.logger.error("Failed to parse relay state", error);
+		throw new APIError("BAD_REQUEST", {
+			message: "State error: failed to validate relay state",
+			cause: error,
+		});
+	}
+
+	if (!parsedData.errorURL) {
+		parsedData.errorURL = errorURL;
+	}
+
+	return parsedData;
+}