@better-auth/sso 1.4.17 → 1.4.19

package/src/routes/sso.ts

@@ -1,3 +1,4 @@
+import { base64 } from "@better-auth/utils/base64";
 import { BetterFetchError, betterFetch } from "@better-fetch/fetch";
 import type { User, Verification } from "better-auth";
 import {
@@ -11,6 +12,7 @@ import {
 import {
 	APIError,
 	createAuthEndpoint,
+	getSessionFromCtx,
 	sessionMiddleware,
 } from "better-auth/api";
 import { setSessionCookie } from "better-auth/cookies";
@@ -23,6 +25,7 @@ import type { BindingContext } from "samlify/types/src/entity";
 import type { IdentityProvider } from "samlify/types/src/entity-idp";
 import type { FlowResult } from "samlify/types/src/flow";
 import z from "zod/v4";
+import { getVerificationIdentifier } from "./domain-verification";
 
 interface AuthnRequestRecord {
 	id: string;
@@ -52,8 +55,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 +169,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",
@@ -224,6 +230,7 @@ export const spMetadata = () => {
 									`${ctx.context.baseURL}/sso/saml2/sp/acs/${provider.id}`,
 							},
 						],
+						authnRequestsSigned: parsedSamlConfig.authnRequestsSigned || false,
 						wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
 						nameIDFormat: parsedSamlConfig.identifierFormat
 							? [parsedSamlConfig.identifierFormat]
@@ -247,7 +254,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({
@@ -855,9 +863,7 @@ export const registerSSOProvider = <O extends SSOOptions>(options: O) => {
 				await ctx.context.adapter.create<Verification>({
 					model: "verification",
 					data: {
-						identifier: options.domainVerification?.tokenPrefix
-							? `${options.domainVerification?.tokenPrefix}-${provider.providerId}`
-							: `better-auth-token-${provider.providerId}`,
+						identifier: getVerificationIdentifier(options, provider.providerId),
 						createdAt: new Date(),
 						updatedAt: new Date(),
 						value: domainVerificationToken as string,
@@ -1121,38 +1127,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) {
@@ -1258,6 +1284,8 @@ export const signInSSO = (options?: SSOOptions) => {
 											`${ctx.context.baseURL}/sso/saml2/sp/acs/${provider.providerId}`,
 									},
 								],
+								authnRequestsSigned:
+									parsedSamlConfig.authnRequestsSigned || false,
 								wantMessageSigned:
 									parsedSamlConfig.wantAssertionsSigned || false,
 								nameIDFormat: parsedSamlConfig.identifierFormat
@@ -1269,16 +1297,41 @@ export const signInSSO = (options?: SSOOptions) => {
 
 				const sp = saml.ServiceProvider({
 					metadata: metadata,
+					privateKey:
+						parsedSamlConfig.spMetadata?.privateKey ||
+						parsedSamlConfig.privateKey,
+					privateKeyPass: parsedSamlConfig.spMetadata?.privateKeyPass,
 					allowCreate: true,
 				});
 
-				const idp = saml.IdentityProvider({
-					metadata: parsedSamlConfig.idpMetadata?.metadata,
-					entityID: parsedSamlConfig.idpMetadata?.entityID,
-					encryptCert: parsedSamlConfig.idpMetadata?.cert,
-					singleSignOnService:
-						parsedSamlConfig.idpMetadata?.singleSignOnService,
-				});
+				const idpData = parsedSamlConfig.idpMetadata;
+				let idp: IdentityProvider;
+				if (!idpData?.metadata) {
+					idp = saml.IdentityProvider({
+						entityID: idpData?.entityID || parsedSamlConfig.issuer,
+						singleSignOnService: idpData?.singleSignOnService || [
+							{
+								Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+								Location: parsedSamlConfig.entryPoint,
+							},
+						],
+						signingCert: idpData?.cert || parsedSamlConfig.cert,
+						wantAuthnRequestsSigned:
+							parsedSamlConfig.authnRequestsSigned || false,
+						isAssertionEncrypted: idpData?.isAssertionEncrypted || false,
+						encPrivateKey: idpData?.encPrivateKey,
+						encPrivateKeyPass: idpData?.encPrivateKeyPass,
+					});
+				} else {
+					idp = saml.IdentityProvider({
+						metadata: idpData.metadata,
+						privateKey: idpData.privateKey,
+						privateKeyPass: idpData.privateKeyPass,
+						isAssertionEncrypted: idpData.isAssertionEncrypted,
+						encPrivateKey: idpData.encPrivateKey,
+						encPrivateKeyPass: idpData.encPrivateKeyPass,
+					});
+				}
 				const loginRequest = sp.createLoginRequest(
 					idp,
 					"redirect",
@@ -1293,6 +1346,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 +1370,7 @@ export const signInSSO = (options?: SSOOptions) => {
 				}
 
 				return ctx.json({
-					url: `${loginRequest.context}&RelayState=${encodeURIComponent(
-						body.callbackURL,
-					)}`,
+					url: `${loginRequest.context}&RelayState=${encodeURIComponent(relayState)}`,
 					redirect: true,
 				});
 			}
@@ -1418,7 +1475,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 				throw ctx.redirect(
 					`${
 						errorURL || callbackURL
-					}/error?error=invalid_provider&error_description=provider not found`,
+					}?error=invalid_provider&error_description=provider not found`,
 				);
 			}
 
@@ -1437,7 +1494,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 				throw ctx.redirect(
 					`${
 						errorURL || callbackURL
-					}/error?error=invalid_provider&error_description=provider not found`,
+					}?error=invalid_provider&error_description=provider not found`,
 				);
 			}
 
@@ -1464,7 +1521,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 				throw ctx.redirect(
 					`${
 						errorURL || callbackURL
-					}/error?error=invalid_provider&error_description=token_endpoint_not_found`,
+					}?error=invalid_provider&error_description=token_endpoint_not_found`,
 				);
 			}
 
@@ -1495,7 +1552,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 				throw ctx.redirect(
 					`${
 						errorURL || callbackURL
-					}/error?error=invalid_provider&error_description=token_response_not_found`,
+					}?error=invalid_provider&error_description=token_response_not_found`,
 				);
 			}
 			let userInfo: {
@@ -1512,12 +1569,16 @@ export const callbackSSO = (options?: SSOOptions) => {
 					throw ctx.redirect(
 						`${
 							errorURL || callbackURL
-						}/error?error=invalid_provider&error_description=jwks_endpoint_not_found`,
+						}?error=invalid_provider&error_description=jwks_endpoint_not_found`,
 					);
 				}
 				const verified = await validateToken(
 					tokenResponse.idToken,
 					config.jwksEndpoint,
+					{
+						audience: config.clientId,
+						issuer: provider.issuer,
+					},
 				).catch((e) => {
 					ctx.context.logger.error(e);
 					return null;
@@ -1526,14 +1587,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 					throw ctx.redirect(
 						`${
 							errorURL || callbackURL
-						}/error?error=invalid_provider&error_description=token_not_verified`,
-					);
-				}
-				if (verified.payload.iss !== provider.issuer) {
-					throw ctx.redirect(
-						`${
-							errorURL || callbackURL
-						}/error?error=invalid_provider&error_description=issuer_mismatch`,
+						}?error=invalid_provider&error_description=token_not_verified`,
 					);
 				}
 
@@ -1566,7 +1620,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 					throw ctx.redirect(
 						`${
 							errorURL || callbackURL
-						}/error?error=invalid_provider&error_description=user_info_endpoint_not_found`,
+						}?error=invalid_provider&error_description=user_info_endpoint_not_found`,
 					);
 				}
 				const userInfoResponse = await betterFetch<{
@@ -1584,7 +1638,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 					throw ctx.redirect(
 						`${
 							errorURL || callbackURL
-						}/error?error=invalid_provider&error_description=${
+						}?error=invalid_provider&error_description=${
 							userInfoResponse.error.message
 						}`,
 					);
@@ -1596,7 +1650,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 				throw ctx.redirect(
 					`${
 						errorURL || callbackURL
-					}/error?error=invalid_provider&error_description=missing_user_info`,
+					}?error=invalid_provider&error_description=missing_user_info`,
 				);
 			}
 			const isTrustedProvider =
@@ -1630,9 +1684,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 				isTrustedProvider,
 			});
 			if (linked.error) {
-				throw ctx.redirect(
-					`${errorURL || callbackURL}/error?error=${linked.error}`,
-				);
+				throw ctx.redirect(`${errorURL || callbackURL}?error=${linked.error}`);
 			}
 			const { session, user } = linked.data!;
 
@@ -1683,12 +1735,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 +1810,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 +1826,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 +1870,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(
@@ -1784,6 +1936,21 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					message: "Invalid SAML configuration",
 				});
 			}
+
+			const isTrusted = (
+				url: string,
+				settings?: { allowRelativePaths: boolean },
+			) => ctx.context.isTrustedOrigin(url, settings);
+
+			const safeErrorUrl = getSafeRedirectUrl(
+				relayState?.errorURL ||
+					relayState?.callbackURL ||
+					parsedSamlConfig.callbackUrl,
+				currentCallbackPath,
+				appOrigin,
+				isTrusted,
+			);
+
 			const idpData = parsedSamlConfig.idpMetadata;
 			let idp: IdentityProvider | null = null;
 
@@ -1791,7 +1958,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 			if (!idpData?.metadata) {
 				idp = saml.IdentityProvider({
 					entityID: idpData?.entityID || parsedSamlConfig.issuer,
-					singleSignOnService: [
+					singleSignOnService: idpData?.singleSignOnService || [
 						{
 							Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
 							Location: parsedSamlConfig.entryPoint,
@@ -1799,7 +1966,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					],
 					signingCert: idpData?.cert || parsedSamlConfig.cert,
 					wantAuthnRequestsSigned:
-						parsedSamlConfig.wantAssertionsSigned || false,
+						parsedSamlConfig.authnRequestsSigned || false,
 					isAssertionEncrypted: idpData?.isAssertionEncrypted || false,
 					encPrivateKey: idpData?.encPrivateKey,
 					encPrivateKeyPass: idpData?.encPrivateKeyPass,
@@ -1846,7 +2013,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 				parsedResponse = await sp.parseLoginResponse(idp, "post", {
 					body: {
 						SAMLResponse,
-						RelayState: RelayState || undefined,
+						RelayState: ctx.body.RelayState || undefined,
 					},
 				});
 
@@ -1856,8 +2023,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 			} catch (error) {
 				ctx.context.logger.error("SAML response validation failed", {
 					error,
-					decodedResponse: Buffer.from(SAMLResponse, "base64").toString(
-						"utf-8",
+					decodedResponse: new TextDecoder().decode(
+						base64.decode(SAMLResponse),
 					),
 				});
 				throw new APIError("BAD_REQUEST", {
@@ -1908,10 +2075,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 							"SAML InResponseTo validation failed: unknown or expired request ID",
 							{ inResponseTo, providerId: provider.providerId },
 						);
-						const redirectUrl =
-							RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 						throw ctx.redirect(
-							`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`,
+							`${safeErrorUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`,
 						);
 					}
 
@@ -1928,10 +2093,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 						await ctx.context.internalAdapter.deleteVerificationByIdentifier(
 							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
 						);
-						const redirectUrl =
-							RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 						throw ctx.redirect(
-							`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`,
+							`${safeErrorUrl}?error=invalid_saml_response&error_description=Provider+mismatch`,
 						);
 					}
 
@@ -1943,10 +2106,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 						"SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false",
 						{ providerId: provider.providerId },
 					);
-					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 					throw ctx.redirect(
-						`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`,
+						`${safeErrorUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`,
 					);
 				}
 			}
@@ -1996,10 +2157,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 							providerId: provider.providerId,
 						},
 					);
-					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 					throw ctx.redirect(
-						`${redirectUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`,
+						`${safeErrorUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`,
 					);
 				}
 
@@ -2070,8 +2229,12 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					!!(provider as { domainVerified?: boolean }).domainVerified &&
 					validateEmailDomain(userInfo.email as string, provider.domain));
 
-			const callbackUrl =
-				RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+			const safeCallbackUrl = getSafeRedirectUrl(
+				relayState?.callbackURL || parsedSamlConfig.callbackUrl,
+				currentCallbackPath,
+				appOrigin,
+				isTrusted,
+			);
 
 			const result = await handleOAuthUserInfo(ctx, {
 				userInfo: {
@@ -2086,14 +2249,14 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					accessToken: "",
 					refreshToken: "",
 				},
-				callbackURL: callbackUrl,
+				callbackURL: safeCallbackUrl,
 				disableSignUp: options?.disableImplicitSignUp,
 				isTrustedProvider,
 			});
 
 			if (result.error) {
 				throw ctx.redirect(
-					`${callbackUrl}?error=${result.error.split(" ").join("_")}`,
+					`${safeCallbackUrl}?error=${result.error.split(" ").join("_")}`,
 				);
 			}
 
@@ -2122,7 +2285,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 			});
 
 			await setSessionCookie(ctx, { session, user });
-			throw ctx.redirect(callbackUrl);
+			throw ctx.redirect(safeCallbackUrl);
 		},
 	);
 };
@@ -2159,8 +2322,10 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			},
 		},
 		async (ctx) => {
-			const { SAMLResponse, RelayState = "" } = ctx.body;
+			const { SAMLResponse } = ctx.body;
 			const { providerId } = ctx.params;
+			const currentCallbackPath = `${ctx.context.baseURL}/sso/saml2/sp/acs/${providerId}`;
+			const appOrigin = new URL(ctx.context.baseURL).origin;
 
 			const maxResponseSize =
 				options?.saml?.maxResponseSize ?? DEFAULT_MAX_SAML_RESPONSE_SIZE;
@@ -2169,6 +2334,14 @@ export const acsEndpoint = (options?: SSOOptions) => {
 					message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)`,
 				});
 			}
+			let relayState: RelayState | null = null;
+			if (ctx.body.RelayState) {
+				try {
+					relayState = await parseRelayState(ctx);
+				} catch {
+					relayState = null;
+				}
+			}
 
 			// If defaultSSO is configured, use it as the provider
 			let provider: SSOProvider<SSOOptions> | null = null;
@@ -2233,6 +2406,23 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			}
 
 			const parsedSamlConfig = provider.samlConfig;
+
+			const isTrusted = (
+				url: string,
+				settings?: { allowRelativePaths: boolean },
+			) => ctx.context.isTrustedOrigin(url, settings);
+
+			// Compute a safe error redirect URL once, reused by all error paths.
+			// Prefers errorURL from relay state, falls back to callbackURL, then provider config, then baseURL.
+			const safeErrorUrl = getSafeRedirectUrl(
+				relayState?.errorURL ||
+					relayState?.callbackURL ||
+					parsedSamlConfig.callbackUrl,
+				currentCallbackPath,
+				appOrigin,
+				isTrusted,
+			);
+
 			// Configure SP and IdP
 			const sp = saml.ServiceProvider({
 				entityID:
@@ -2277,14 +2467,12 @@ export const acsEndpoint = (options?: SSOOptions) => {
 				validateSingleAssertion(SAMLResponse);
 			} catch (error) {
 				if (error instanceof APIError) {
-					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 					const errorCode =
 						error.body?.code === "SAML_MULTIPLE_ASSERTIONS"
 							? "multiple_assertions"
 							: "no_assertion";
 					throw ctx.redirect(
-						`${redirectUrl}?error=${errorCode}&error_description=${encodeURIComponent(error.message)}`,
+						`${safeErrorUrl}?error=${errorCode}&error_description=${encodeURIComponent(error.message)}`,
 					);
 				}
 				throw error;
@@ -2296,7 +2484,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 				parsedResponse = await sp.parseLoginResponse(idp, "post", {
 					body: {
 						SAMLResponse,
-						RelayState: RelayState || undefined,
+						RelayState: ctx.body.RelayState || undefined,
 					},
 				});
 
@@ -2306,8 +2494,8 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			} catch (error) {
 				ctx.context.logger.error("SAML response validation failed", {
 					error,
-					decodedResponse: Buffer.from(SAMLResponse, "base64").toString(
-						"utf-8",
+					decodedResponse: new TextDecoder().decode(
+						base64.decode(SAMLResponse),
 					),
 				});
 				throw new APIError("BAD_REQUEST", {
@@ -2360,10 +2548,8 @@ export const acsEndpoint = (options?: SSOOptions) => {
 							"SAML InResponseTo validation failed: unknown or expired request ID",
 							{ inResponseTo: inResponseToAcs, providerId },
 						);
-						const redirectUrl =
-							RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 						throw ctx.redirect(
-							`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`,
+							`${safeErrorUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`,
 						);
 					}
 
@@ -2379,10 +2565,8 @@ export const acsEndpoint = (options?: SSOOptions) => {
 						await ctx.context.internalAdapter.deleteVerificationByIdentifier(
 							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
 						);
-						const redirectUrl =
-							RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 						throw ctx.redirect(
-							`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`,
+							`${safeErrorUrl}?error=invalid_saml_response&error_description=Provider+mismatch`,
 						);
 					}
 
@@ -2394,17 +2578,15 @@ export const acsEndpoint = (options?: SSOOptions) => {
 						"SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false",
 						{ providerId },
 					);
-					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 					throw ctx.redirect(
-						`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`,
+						`${safeErrorUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`,
 					);
 				}
 			}
 
 			// Assertion Replay Protection
-			const samlContentAcs = Buffer.from(SAMLResponse, "base64").toString(
-				"utf-8",
+			const samlContentAcs = new TextDecoder().decode(
+				base64.decode(SAMLResponse),
 			);
 			const assertionIdAcs = extractAssertionId(samlContentAcs);
 
@@ -2447,10 +2629,8 @@ export const acsEndpoint = (options?: SSOOptions) => {
 							providerId,
 						},
 					);
-					const redirectUrl =
-						RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
 					throw ctx.redirect(
-						`${redirectUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`,
+						`${safeErrorUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`,
 					);
 				}
 
@@ -2522,8 +2702,12 @@ export const acsEndpoint = (options?: SSOOptions) => {
 					!!(provider as { domainVerified?: boolean }).domainVerified &&
 					validateEmailDomain(userInfo.email as string, provider.domain));
 
-			const callbackUrl =
-				RelayState || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+			const safeCallbackUrl = getSafeRedirectUrl(
+				relayState?.callbackURL || parsedSamlConfig.callbackUrl,
+				currentCallbackPath,
+				appOrigin,
+				isTrusted,
+			);
 
 			const result = await handleOAuthUserInfo(ctx, {
 				userInfo: {
@@ -2538,14 +2722,14 @@ export const acsEndpoint = (options?: SSOOptions) => {
 					accessToken: "",
 					refreshToken: "",
 				},
-				callbackURL: callbackUrl,
+				callbackURL: safeCallbackUrl,
 				disableSignUp: options?.disableImplicitSignUp,
 				isTrustedProvider,
 			});
 
 			if (result.error) {
 				throw ctx.redirect(
-					`${callbackUrl}?error=${result.error.split(" ").join("_")}`,
+					`${safeCallbackUrl}?error=${result.error.split(" ").join("_")}`,
 				);
 			}
 
@@ -2574,7 +2758,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			});
 
 			await setSessionCookie(ctx, { session, user });
-			throw ctx.redirect(callbackUrl);
+			throw ctx.redirect(safeCallbackUrl);
 		},
 	);
 };