@better-auth/sso 1.6.1 → 1.7.0-beta.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as PACKAGE_VERSION } from "./version-CfoAqE_A.mjs";
+import { t as PACKAGE_VERSION } from "./version-CzfTSPRz.mjs";
 import { APIError, createAuthEndpoint, createAuthMiddleware, getSessionFromCtx, sessionMiddleware } from "better-auth/api";
 import { XMLParser, XMLValidator } from "fast-xml-parser";
 import * as saml from "samlify";
@@ -8,7 +8,7 @@ import { generateRandomString } from "better-auth/crypto";
 import * as z from "zod";
 import { base64 } from "@better-auth/utils/base64";
 import { BetterFetchError, betterFetch } from "@better-fetch/fetch";
-import { HIDE_METADATA, createAuthorizationURL, generateGenericState, generateState, parseGenericState, parseState, validateAuthorizationCode, validateToken } from "better-auth";
+import { ASSERTION_SIGNING_ALGORITHMS, HIDE_METADATA, createAuthorizationURL, generateGenericState, generateState, parseGenericState, parseState, validateAuthorizationCode, validateToken } from "better-auth";
 import { deleteSessionCookie, setSessionCookie } from "better-auth/cookies";
 import { handleOAuthUserInfo } from "better-auth/oauth2";
 import { decodeJwt } from "jose";
@@ -606,7 +606,7 @@ function countAssertions(xml) {
 function validateSingleAssertion(samlResponse) {
 	let xml;
 	try {
-		xml = new TextDecoder().decode(base64.decode(samlResponse));
+		xml = new TextDecoder().decode(base64.decode(samlResponse.replace(/\s+/g, "")));
 		if (!xml.includes("<")) throw new Error("Not XML");
 	} catch {
 		throw new APIError("BAD_REQUEST", {
@@ -625,6 +625,91 @@ function validateSingleAssertion(samlResponse) {
 	});
 }
 //#endregion
+//#region src/saml/response-validation.ts
+function errorRedirectUrl(base, error, description) {
+	try {
+		const url = new URL(base);
+		url.searchParams.set("error", error);
+		url.searchParams.set("error_description", description);
+		return url.toString();
+	} catch {
+		const hashIdx = base.indexOf("#");
+		const path = hashIdx >= 0 ? base.slice(0, hashIdx) : base;
+		const hash = hashIdx >= 0 ? base.slice(hashIdx + 1) : void 0;
+		return `${path}${path.includes("?") ? "&" : "?"}${`error=${encodeURIComponent(error)}&error_description=${encodeURIComponent(description)}`}${hash ? `#${hash}` : ""}`;
+	}
+}
+/**
+* Validates the InResponseTo attribute of a SAML Response.
+*
+* This binds the IdP's Response to a specific SP-initiated AuthnRequest,
+* preventing replay attacks, unsolicited response injection, and
+* cross-provider assertion swaps.
+*
+* The InResponseTo value lives at `extract.response.inResponseTo` in
+* samlify's parsed output (not at the top level).
+*/
+async function validateInResponseTo(c, ctx) {
+	if (ctx.options.enableInResponseToValidation === false) return;
+	const inResponseTo = ctx.extract.response?.inResponseTo;
+	const allowIdpInitiated = ctx.options.allowIdpInitiated ?? false;
+	if (inResponseTo) {
+		let storedRequest = null;
+		const verification = await c.context.internalAdapter.findVerificationValue(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
+		if (verification) try {
+			storedRequest = JSON.parse(verification.value);
+			if (storedRequest && storedRequest.expiresAt < Date.now()) storedRequest = null;
+		} catch {
+			storedRequest = null;
+		}
+		if (!storedRequest) {
+			c.context.logger.error("SAML InResponseTo validation failed: unknown or expired request ID", {
+				inResponseTo,
+				providerId: ctx.providerId
+			});
+			throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Unknown or expired request ID"));
+		}
+		if (storedRequest.providerId !== ctx.providerId) {
+			c.context.logger.error("SAML InResponseTo validation failed: provider mismatch", {
+				inResponseTo,
+				expectedProvider: storedRequest.providerId,
+				actualProvider: ctx.providerId
+			});
+			await c.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
+			throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Provider mismatch"));
+		}
+		await c.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
+	} else if (!allowIdpInitiated) {
+		c.context.logger.error("SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false", { providerId: ctx.providerId });
+		throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "unsolicited_response", "IdP-initiated SSO not allowed"));
+	}
+}
+/**
+* Validates the AudienceRestriction of a SAML assertion.
+*
+* Per SAML 2.0 Core §2.5.1, an assertion's Audience element specifies
+* the intended recipient SP. Without this check, an assertion issued
+* for a different SP (e.g., another application sharing the same IdP)
+* could be accepted.
+*/
+function validateAudience(c, ctx) {
+	if (!ctx.expectedAudience) return;
+	const audience = ctx.extract.audience;
+	if (!audience) {
+		c.context.logger.error("SAML assertion missing AudienceRestriction but audience is configured — rejecting", { providerId: ctx.providerId });
+		throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Audience restriction missing"));
+	}
+	const audiences = Array.isArray(audience) ? audience : [audience];
+	if (!audiences.includes(ctx.expectedAudience)) {
+		c.context.logger.error("SAML audience mismatch: assertion was issued for a different service provider", {
+			expected: ctx.expectedAudience,
+			received: audiences,
+			providerId: ctx.providerId
+		});
+		throw c.redirect(errorRedirectUrl(ctx.redirectUrl, "invalid_saml_response", "Audience mismatch"));
+	}
+}
+//#endregion
 //#region src/routes/schemas.ts
 const oidcMappingSchema = z.object({
 	id: z.string().optional(),
@@ -649,7 +734,13 @@ const oidcConfigSchema = z.object({
 	authorizationEndpoint: z.string().url().optional(),
 	tokenEndpoint: z.string().url().optional(),
 	userInfoEndpoint: z.string().url().optional(),
-	tokenEndpointAuthentication: z.enum(["client_secret_post", "client_secret_basic"]).optional(),
+	tokenEndpointAuthentication: z.enum([
+		"client_secret_post",
+		"client_secret_basic",
+		"private_key_jwt"
+	]).optional(),
+	privateKeyId: z.string().optional(),
+	privateKeyAlgorithm: z.string().optional(),
 	jwksEndpoint: z.string().url().optional(),
 	discoveryEndpoint: z.string().url().optional(),
 	scopes: z.array(z.string()).optional(),
@@ -900,7 +991,9 @@ function mergeOIDCConfig(current, updates, issuer) {
 		tokenEndpoint: updates.tokenEndpoint ?? current.tokenEndpoint,
 		userInfoEndpoint: updates.userInfoEndpoint ?? current.userInfoEndpoint,
 		jwksEndpoint: updates.jwksEndpoint ?? current.jwksEndpoint,
-		tokenEndpointAuthentication: updates.tokenEndpointAuthentication ?? current.tokenEndpointAuthentication
+		tokenEndpointAuthentication: updates.tokenEndpointAuthentication ?? current.tokenEndpointAuthentication,
+		privateKeyId: updates.privateKeyId ?? current.privateKeyId,
+		privateKeyAlgorithm: updates.privateKeyAlgorithm ?? current.privateKeyAlgorithm
 	};
 }
 const updateSSOProvider = (options) => {
@@ -945,6 +1038,8 @@ const updateSSOProvider = (options) => {
 		if (body.oidcConfig) {
 			const currentOidcConfig = parseAndValidateConfig(existingProvider.oidcConfig, "OIDC");
 			const updatedOidcConfig = mergeOIDCConfig(currentOidcConfig, body.oidcConfig, updateData.issuer || currentOidcConfig.issuer || existingProvider.issuer);
+			if (updatedOidcConfig.tokenEndpointAuthentication !== "private_key_jwt" && !updatedOidcConfig.clientSecret) throw new APIError("BAD_REQUEST", { message: "clientSecret is required when using client_secret_basic or client_secret_post authentication" });
+			if (updatedOidcConfig.tokenEndpointAuthentication === "private_key_jwt" && !options?.resolvePrivateKey && !options?.defaultSSO?.some((p) => p.providerId === providerId && "privateKey" in p && p.privateKey)) throw new APIError("BAD_REQUEST", { message: "private_key_jwt authentication requires either a resolvePrivateKey callback or a privateKey in defaultSSO" });
 			updateData.oidcConfig = JSON.stringify(updatedOidcConfig);
 		}
 		await ctx.context.adapter.update({
@@ -1242,11 +1337,13 @@ function parseURL(name, endpoint, base) {
 * @returns The selected authentication method
 */
 function selectTokenEndpointAuthMethod(doc, existing) {
+	if (existing === "private_key_jwt") return existing;
 	if (existing) return existing;
 	const supported = doc.token_endpoint_auth_methods_supported;
 	if (!supported || supported.length === 0) return "client_secret_basic";
 	if (supported.includes("client_secret_basic")) return "client_secret_basic";
 	if (supported.includes("client_secret_post")) return "client_secret_post";
+	if (supported.includes("private_key_jwt")) return "private_key_jwt";
 	return "client_secret_basic";
 }
 /**
@@ -1436,13 +1533,15 @@ async function findSAMLProvider(providerId, options, adapter) {
 		samlConfig: res.samlConfig ? safeJsonParse(res.samlConfig) || void 0 : void 0
 	};
 }
-function createSP(config, baseURL, providerId, sloOptions) {
+function createSP(config, baseURL, providerId, opts) {
+	const spData = config.spMetadata;
 	const sloLocation = `${baseURL}/sso/saml2/sp/slo/${providerId}`;
+	const acsUrl = config.callbackUrl || `${baseURL}/sso/saml2/sp/acs/${providerId}`;
 	return saml.ServiceProvider({
-		entityID: config.spMetadata?.entityID || config.issuer,
-		assertionConsumerService: [{
+		entityID: spData?.entityID || config.issuer,
+		assertionConsumerService: spData?.metadata ? void 0 : [{
 			Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
-			Location: config.callbackUrl || `${baseURL}/sso/saml2/sp/acs/${providerId}`
+			Location: acsUrl
 		}],
 		singleLogoutService: [{
 			Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
@@ -1452,11 +1551,16 @@ function createSP(config, baseURL, providerId, sloOptions) {
 			Location: sloLocation
 		}],
 		wantMessageSigned: config.wantAssertionsSigned || false,
-		wantLogoutRequestSigned: sloOptions?.wantLogoutRequestSigned ?? false,
-		wantLogoutResponseSigned: sloOptions?.wantLogoutResponseSigned ?? false,
-		metadata: config.spMetadata?.metadata,
-		privateKey: config.spMetadata?.privateKey || config.privateKey,
-		privateKeyPass: config.spMetadata?.privateKeyPass
+		wantLogoutRequestSigned: opts?.sloOptions?.wantLogoutRequestSigned ?? false,
+		wantLogoutResponseSigned: opts?.sloOptions?.wantLogoutResponseSigned ?? false,
+		metadata: spData?.metadata,
+		privateKey: spData?.privateKey || config.privateKey,
+		privateKeyPass: spData?.privateKeyPass,
+		isAssertionEncrypted: spData?.isAssertionEncrypted || false,
+		encPrivateKey: spData?.encPrivateKey,
+		encPrivateKeyPass: spData?.encPrivateKeyPass,
+		nameIDFormat: config.identifierFormat ? [config.identifierFormat] : void 0,
+		relayState: opts?.relayState
 	});
 }
 function createIdP(config) {
@@ -1465,6 +1569,7 @@ function createIdP(config) {
 		metadata: idpData.metadata,
 		privateKey: idpData.privateKey,
 		privateKeyPass: idpData.privateKeyPass,
+		isAssertionEncrypted: idpData.isAssertionEncrypted,
 		encPrivateKey: idpData.encPrivateKey,
 		encPrivateKeyPass: idpData.encPrivateKeyPass
 	});
@@ -1475,7 +1580,11 @@ function createIdP(config) {
 			Location: config.entryPoint
 		}],
 		singleLogoutService: idpData?.singleLogoutService,
-		signingCert: idpData?.cert || config.cert
+		signingCert: idpData?.cert || config.cert,
+		wantAuthnRequestsSigned: config.authnRequestsSigned || false,
+		isAssertionEncrypted: idpData?.isAssertionEncrypted || false,
+		encPrivateKey: idpData?.encPrivateKey,
+		encPrivateKeyPass: idpData?.encPrivateKeyPass
 	});
 }
 function escapeHtml(str) {
@@ -1491,20 +1600,7 @@ function createSAMLPostForm(action, samlParam, samlValue, relayState) {
 	return new Response(html, { headers: { "Content-Type": "text/html" } });
 }
 //#endregion
-//#region src/routes/sso.ts
-/**
-* Builds the OIDC redirect URI. Uses the shared `redirectURI` option
-* when set, otherwise falls back to `/sso/callback/:providerId`.
-*/
-function getOIDCRedirectURI(baseURL, providerId, options) {
-	if (options?.redirectURI?.trim()) try {
-		new URL(options.redirectURI);
-		return options.redirectURI;
-	} catch {
-		return `${baseURL}${options.redirectURI.startsWith("/") ? options.redirectURI : `/${options.redirectURI}`}`;
-	}
-	return `${baseURL}/sso/callback/${providerId}`;
-}
+//#region src/saml/timestamp.ts
 /**
 * Validates SAML assertion timestamp conditions (NotBefore/NotOnOrAfter).
 * Prevents acceptance of expired or future-dated assertions.
@@ -1544,9 +1640,39 @@ function validateSAMLTimestamp(conditions, options = {}) {
 		});
 	}
 }
+//#endregion
+//#region src/routes/saml-pipeline.ts
+/**
+* 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
+*/
+function getSafeRedirectUrl(url, callbackPath, appOrigin, isTrustedOrigin) {
+	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;
+		if (new URL(url).pathname === callbackPathname) return appOrigin;
+	} catch {
+		if (url === callbackPath || url.startsWith(`${callbackPath}?`)) return appOrigin;
+	}
+	return url;
+}
 /**
 * Extracts the Assertion ID from a SAML response XML.
-* Returns null if the assertion ID cannot be found.
+* Used for replay protection per SAML 2.0 Core section 2.3.3.
 */
 function extractAssertionId(samlContent) {
 	try {
@@ -1565,6 +1691,208 @@ function extractAssertionId(samlContent) {
 		return null;
 	}
 }
+/**
+* Unified SAML response processing pipeline.
+*
+* Both `/sso/saml2/callback/:providerId` (POST) and `/sso/saml2/sp/acs/:providerId`
+* delegate to this function. It handles the full lifecycle: provider lookup,
+* SP/IdP construction, response validation, session creation, and redirect
+* URL computation.
+*/
+async function processSAMLResponse(ctx, params, options) {
+	const { providerId, currentCallbackPath } = params;
+	const appOrigin = new URL(ctx.context.baseURL).origin;
+	const maxResponseSize = options?.saml?.maxResponseSize ?? 262144;
+	if (new TextEncoder().encode(params.SAMLResponse).length > maxResponseSize) throw new APIError("BAD_REQUEST", { message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)` });
+	const SAMLResponse = params.SAMLResponse.replace(/\s+/g, "");
+	let relayState = null;
+	if (params.RelayState) try {
+		relayState = await parseRelayState(ctx);
+	} catch {
+		relayState = null;
+	}
+	const provider = await findSAMLProvider(providerId, options, ctx.context.adapter);
+	if (!provider?.samlConfig) throw new APIError("NOT_FOUND", { message: "No SAML provider found" });
+	if (options?.domainVerification?.enabled && !("domainVerified" in provider && provider.domainVerified)) throw new APIError("UNAUTHORIZED", { message: "Provider domain has not been verified" });
+	const parsedSamlConfig = typeof provider.samlConfig === "object" ? provider.samlConfig : safeJsonParse(provider.samlConfig);
+	if (!parsedSamlConfig) throw new APIError("BAD_REQUEST", { message: "Invalid SAML configuration" });
+	const sp = createSP(parsedSamlConfig, ctx.context.baseURL, providerId);
+	const idp = createIdP(parsedSamlConfig);
+	const samlRedirectUrl = getSafeRedirectUrl(relayState?.callbackURL || parsedSamlConfig.callbackUrl, params.currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
+	validateSingleAssertion(SAMLResponse);
+	let parsedResponse;
+	try {
+		parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
+			SAMLResponse,
+			RelayState: params.RelayState || void 0
+		} });
+		if (!parsedResponse?.extract) throw new Error("Invalid SAML response structure");
+	} catch (error) {
+		ctx.context.logger.error("SAML response validation failed", {
+			error,
+			samlResponsePreview: SAMLResponse.slice(0, 200)
+		});
+		throw new APIError("BAD_REQUEST", {
+			message: "Invalid SAML response",
+			details: error instanceof Error ? error.message : String(error)
+		});
+	}
+	const { extract } = parsedResponse;
+	validateSAMLAlgorithms(parsedResponse, options?.saml?.algorithms);
+	validateSAMLTimestamp(extract.conditions, {
+		clockSkew: options?.saml?.clockSkew,
+		requireTimestamps: options?.saml?.requireTimestamps,
+		logger: ctx.context.logger
+	});
+	await validateInResponseTo(ctx, {
+		extract,
+		providerId,
+		options: {
+			enableInResponseToValidation: options?.saml?.enableInResponseToValidation,
+			allowIdpInitiated: options?.saml?.allowIdpInitiated
+		},
+		redirectUrl: samlRedirectUrl
+	});
+	validateAudience(ctx, {
+		extract,
+		expectedAudience: parsedSamlConfig.audience,
+		providerId,
+		redirectUrl: samlRedirectUrl
+	});
+	const samlContent = parsedResponse.samlContent;
+	const assertionId = samlContent ? extractAssertionId(samlContent) : null;
+	if (assertionId) {
+		const issuer = idp.entityMeta.getEntityID();
+		const conditions = extract.conditions;
+		const clockSkew = options?.saml?.clockSkew ?? 3e5;
+		const expiresAt = conditions?.notOnOrAfter ? new Date(conditions.notOnOrAfter).getTime() + clockSkew : Date.now() + DEFAULT_ASSERTION_TTL_MS;
+		const existingAssertion = await ctx.context.internalAdapter.findVerificationValue(`${USED_ASSERTION_KEY_PREFIX}${assertionId}`);
+		let isReplay = false;
+		if (existingAssertion) try {
+			if (JSON.parse(existingAssertion.value).expiresAt >= Date.now()) isReplay = true;
+		} catch (error) {
+			ctx.context.logger.warn("Failed to parse stored assertion record", {
+				assertionId,
+				error
+			});
+		}
+		if (isReplay) {
+			ctx.context.logger.error("SAML assertion replay detected: assertion ID already used", {
+				assertionId,
+				issuer,
+				providerId
+			});
+			throw ctx.redirect(`${samlRedirectUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`);
+		}
+		await ctx.context.internalAdapter.createVerificationValue({
+			identifier: `${USED_ASSERTION_KEY_PREFIX}${assertionId}`,
+			value: JSON.stringify({
+				assertionId,
+				issuer,
+				providerId,
+				usedAt: Date.now(),
+				expiresAt
+			}),
+			expiresAt: new Date(expiresAt)
+		});
+	} else ctx.context.logger.warn("Could not extract assertion ID for replay protection", { providerId });
+	const attributes = extract.attributes || {};
+	const mapping = parsedSamlConfig.mapping ?? {};
+	const userInfo = {
+		...Object.fromEntries(Object.entries(mapping.extraFields || {}).map(([key, value]) => [key, attributes[value]])),
+		id: attributes[mapping.id || "nameID"] || extract.nameID,
+		email: (attributes[mapping.email || "email"] || extract.nameID || "").toLowerCase(),
+		name: [attributes[mapping.firstName || "givenName"], attributes[mapping.lastName || "surname"]].filter(Boolean).join(" ") || attributes[mapping.name || "displayName"] || extract.nameID,
+		emailVerified: options?.trustEmailVerified && mapping.emailVerified ? attributes[mapping.emailVerified] || false : false
+	};
+	if (!userInfo.id || !userInfo.email) {
+		ctx.context.logger.error("Missing essential user info from SAML response", {
+			attributes: Object.keys(attributes),
+			mapping,
+			extractedId: userInfo.id,
+			extractedEmail: userInfo.email
+		});
+		throw new APIError("BAD_REQUEST", { message: "Unable to extract user ID or email from SAML response" });
+	}
+	const isTrustedProvider = ctx.context.trustedProviders.includes(providerId) || "domainVerified" in provider && !!provider.domainVerified && validateEmailDomain(userInfo.email, provider.domain);
+	const callbackUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
+	const result = await handleOAuthUserInfo(ctx, {
+		userInfo: {
+			email: userInfo.email,
+			name: userInfo.name || userInfo.email,
+			id: userInfo.id,
+			emailVerified: Boolean(userInfo.emailVerified)
+		},
+		account: {
+			providerId,
+			accountId: userInfo.id,
+			accessToken: "",
+			refreshToken: ""
+		},
+		callbackURL: callbackUrl,
+		disableSignUp: options?.disableImplicitSignUp,
+		isTrustedProvider
+	});
+	if (result.error) throw ctx.redirect(`${samlRedirectUrl}?error=${result.error.split(" ").join("_")}`);
+	const { session, user } = result.data;
+	if (options?.provisionUser && (result.isRegister || options.provisionUserOnEveryLogin)) await options.provisionUser({
+		user,
+		userInfo,
+		provider
+	});
+	await assignOrganizationFromProvider(ctx, {
+		user,
+		profile: {
+			providerType: "saml",
+			providerId,
+			accountId: userInfo.id,
+			email: userInfo.email,
+			emailVerified: Boolean(userInfo.emailVerified),
+			rawAttributes: attributes
+		},
+		provider,
+		provisioningOptions: options?.organizationProvisioning
+	});
+	await setSessionCookie(ctx, {
+		session,
+		user
+	});
+	if (options?.saml?.enableSingleLogout && extract.nameID) {
+		const samlSessionKey = `${SAML_SESSION_KEY_PREFIX}${providerId}:${extract.nameID}`;
+		const samlSessionData = {
+			sessionId: session.id,
+			providerId,
+			nameID: extract.nameID,
+			sessionIndex: extract.sessionIndex?.sessionIndex
+		};
+		await ctx.context.internalAdapter.createVerificationValue({
+			identifier: samlSessionKey,
+			value: JSON.stringify(samlSessionData),
+			expiresAt: session.expiresAt
+		}).catch((e) => ctx.context.logger.warn("Failed to create SAML session record", { error: e }));
+		await ctx.context.internalAdapter.createVerificationValue({
+			identifier: `${SAML_SESSION_BY_ID_PREFIX}${session.id}`,
+			value: samlSessionKey,
+			expiresAt: session.expiresAt
+		}).catch((e) => ctx.context.logger.warn("Failed to create SAML session lookup record", e));
+	}
+	return getSafeRedirectUrl(relayState?.callbackURL || parsedSamlConfig.callbackUrl, currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
+}
+//#endregion
+//#region src/routes/sso.ts
+/**
+* Builds the OIDC redirect URI. Uses the shared `redirectURI` option
+* when set, otherwise falls back to `/sso/callback/:providerId`.
+*/
+function getOIDCRedirectURI(baseURL, providerId, options) {
+	if (options?.redirectURI?.trim()) try {
+		new URL(options.redirectURI);
+		return options.redirectURI;
+	} catch {
+		return `${baseURL}${options.redirectURI.startsWith("/") ? options.redirectURI : `/${options.redirectURI}`}`;
+	}
+	return `${baseURL}/sso/callback/${providerId}`;
+}
 const spMetadataQuerySchema = z.object({
 	providerId: z.string(),
 	format: z.enum(["xml", "json"]).default("xml")
@@ -1602,7 +1930,7 @@ const spMetadata = (options) => {
 			entityID: parsedSamlConfig.spMetadata?.entityID || parsedSamlConfig.issuer,
 			assertionConsumerService: [{
 				Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
-				Location: parsedSamlConfig.callbackUrl || `${ctx.context.baseURL}/sso/saml2/sp/acs/${provider.id}`
+				Location: parsedSamlConfig.callbackUrl || `${ctx.context.baseURL}/sso/saml2/sp/acs/${ctx.query.providerId}`
 			}],
 			singleLogoutService,
 			wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
@@ -1618,11 +1946,17 @@ const ssoProviderBodySchema = z.object({
 	domain: z.string({}).meta({ 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({
 		clientId: z.string({}).meta({ description: "The client ID" }),
-		clientSecret: z.string({}).meta({ description: "The client secret" }),
+		clientSecret: z.string({}).optional().meta({ description: "The client secret. Required for client_secret_basic/client_secret_post. Optional for private_key_jwt." }),
 		authorizationEndpoint: z.string({}).meta({ description: "The authorization endpoint" }).optional(),
 		tokenEndpoint: z.string({}).meta({ description: "The token endpoint" }).optional(),
 		userInfoEndpoint: z.string({}).meta({ description: "The user info endpoint" }).optional(),
-		tokenEndpointAuthentication: z.enum(["client_secret_post", "client_secret_basic"]).optional(),
+		tokenEndpointAuthentication: z.enum([
+			"client_secret_post",
+			"client_secret_basic",
+			"private_key_jwt"
+		]).optional(),
+		privateKeyId: z.string().optional(),
+		privateKeyAlgorithm: z.string().optional(),
 		jwksEndpoint: z.string({}).meta({ description: "The JWKS endpoint" }).optional(),
 		discoveryEndpoint: z.string().optional(),
 		skipDiscovery: z.boolean().meta({ description: "Skip OIDC discovery during registration. When true, you must provide authorizationEndpoint, tokenEndpoint, and jwksEndpoint manually." }).optional(),
@@ -1925,6 +2259,8 @@ const registerSSOProvider = (options) => {
 				authorizationEndpoint: body.oidcConfig.authorizationEndpoint,
 				tokenEndpoint: body.oidcConfig.tokenEndpoint,
 				tokenEndpointAuthentication: body.oidcConfig.tokenEndpointAuthentication || "client_secret_basic",
+				privateKeyId: body.oidcConfig.privateKeyId,
+				privateKeyAlgorithm: body.oidcConfig.privateKeyAlgorithm,
 				jwksEndpoint: body.oidcConfig.jwksEndpoint,
 				pkce: body.oidcConfig.pkce,
 				discoveryEndpoint: body.oidcConfig.discoveryEndpoint || `${body.issuer}/.well-known/openid-configuration`,
@@ -1941,6 +2277,8 @@ const registerSSOProvider = (options) => {
 				authorizationEndpoint: hydratedOIDCConfig.authorizationEndpoint,
 				tokenEndpoint: hydratedOIDCConfig.tokenEndpoint,
 				tokenEndpointAuthentication: hydratedOIDCConfig.tokenEndpointAuthentication,
+				privateKeyId: body.oidcConfig.privateKeyId,
+				privateKeyAlgorithm: body.oidcConfig.privateKeyAlgorithm,
 				jwksEndpoint: hydratedOIDCConfig.jwksEndpoint,
 				pkce: body.oidcConfig.pkce,
 				discoveryEndpoint: hydratedOIDCConfig.discoveryEndpoint,
@@ -1950,17 +2288,35 @@ const registerSSOProvider = (options) => {
 				overrideUserInfo: ctx.body.overrideUserInfo || options?.defaultOverrideUserInfo || false
 			});
 		};
-		if (body.samlConfig) validateConfigAlgorithms({
-			signatureAlgorithm: body.samlConfig.signatureAlgorithm,
-			digestAlgorithm: body.samlConfig.digestAlgorithm
-		}, options?.saml?.algorithms);
+		if (body.samlConfig) {
+			validateConfigAlgorithms({
+				signatureAlgorithm: body.samlConfig.signatureAlgorithm,
+				digestAlgorithm: body.samlConfig.digestAlgorithm
+			}, options?.saml?.algorithms);
+			const hasIdpMetadata = body.samlConfig.idpMetadata?.metadata;
+			let hasEntryPoint = false;
+			if (body.samlConfig.entryPoint) try {
+				new URL(body.samlConfig.entryPoint);
+				hasEntryPoint = true;
+			} catch {}
+			const hasSingleSignOnService = body.samlConfig.idpMetadata?.singleSignOnService?.length;
+			if (!hasIdpMetadata && !hasEntryPoint && !hasSingleSignOnService) throw new APIError("BAD_REQUEST", { message: "SAML configuration requires either idpMetadata.metadata (IdP metadata XML), idpMetadata.singleSignOnService, or a valid entryPoint URL" });
+		}
 		const provider = await ctx.context.adapter.create({
 			model: "ssoProvider",
 			data: {
 				issuer: body.issuer,
 				domain: body.domain,
 				domainVerified: false,
-				oidcConfig: buildOIDCConfig(),
+				oidcConfig: (() => {
+					const config = buildOIDCConfig();
+					if (config) {
+						const parsed = JSON.parse(config);
+						if (parsed.tokenEndpointAuthentication !== "private_key_jwt" && !parsed.clientSecret) throw new APIError("BAD_REQUEST", { message: "clientSecret is required when using client_secret_basic or client_secret_post authentication" });
+						if (parsed.tokenEndpointAuthentication === "private_key_jwt" && !options?.resolvePrivateKey && !options?.defaultSSO?.some((p) => p.providerId === body.providerId && "privateKey" in p && p.privateKey)) throw new APIError("BAD_REQUEST", { message: "private_key_jwt authentication requires either a resolvePrivateKey callback or a privateKey in defaultSSO" });
+					}
+					return config;
+				})(),
 				samlConfig: body.samlConfig ? JSON.stringify({
 					issuer: body.issuer,
 					entryPoint: body.samlConfig.entryPoint,
@@ -2181,7 +2537,8 @@ const signInSSO = (options) => {
 		if (provider.samlConfig) {
 			const parsedSamlConfig = typeof provider.samlConfig === "object" ? provider.samlConfig : safeJsonParse(provider.samlConfig);
 			if (!parsedSamlConfig) throw new APIError("BAD_REQUEST", { message: "Invalid SAML configuration" });
-			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 });
+			if (parsedSamlConfig.authnRequestsSigned && !parsedSamlConfig.spMetadata?.privateKey && !parsedSamlConfig.privateKey) throw new APIError("BAD_REQUEST", { message: "authnRequestsSigned is enabled but no privateKey provided in spMetadata or samlConfig" });
+			const { state: relayState } = await generateRelayState(ctx, void 0, false);
 			let metadata = parsedSamlConfig.spMetadata.metadata;
 			if (!metadata) metadata = saml.SPMetadata({
 				entityID: parsedSamlConfig.spMetadata?.entityID || parsedSamlConfig.issuer,
@@ -2197,7 +2554,8 @@ const signInSSO = (options) => {
 				metadata,
 				allowCreate: true,
 				privateKey: parsedSamlConfig.spMetadata?.privateKey || parsedSamlConfig.privateKey,
-				privateKeyPass: parsedSamlConfig.spMetadata?.privateKeyPass
+				privateKeyPass: parsedSamlConfig.spMetadata?.privateKeyPass,
+				relayState
 			});
 			const idpData = parsedSamlConfig.idpMetadata;
 			let idp;
@@ -2223,7 +2581,6 @@ const signInSSO = (options) => {
 			});
 			const loginRequest = sp.createLoginRequest(idp, "redirect");
 			if (!loginRequest) throw new APIError("BAD_REQUEST", { message: "Invalid SAML request" });
-			const { state: relayState } = await generateRelayState(ctx, void 0, false);
 			if (loginRequest.id && options?.saml?.enableInResponseToValidation !== false) {
 				const ttl = options?.saml?.requestTTL ?? 3e5;
 				const record = {
@@ -2239,7 +2596,7 @@ const signInSSO = (options) => {
 				});
 			}
 			return ctx.json({
-				url: `${loginRequest.context}&RelayState=${encodeURIComponent(relayState)}`,
+				url: loginRequest.context,
 				redirect: true
 			});
 		}
@@ -2312,6 +2669,30 @@ async function handleOIDCCallback(ctx, options, providerId, stateData) {
 		]
 	};
 	if (!config.tokenEndpoint) throw ctx.redirect(`${errorURL || callbackURL}?error=invalid_provider&error_description=token_endpoint_not_found`);
+	let authMethod = "basic";
+	if (config.tokenEndpointAuthentication === "client_secret_post") authMethod = "post";
+	else if (config.tokenEndpointAuthentication === "private_key_jwt") authMethod = "private_key_jwt";
+	let clientAssertionConfig;
+	if (authMethod === "private_key_jwt") {
+		let resolved;
+		const matchingDefault = options?.defaultSSO?.find((p) => p.providerId === provider.providerId && "privateKey" in p && p.privateKey);
+		if (matchingDefault && "privateKey" in matchingDefault) resolved = matchingDefault.privateKey;
+		if (!resolved && options?.resolvePrivateKey) resolved = await options.resolvePrivateKey({
+			providerId: provider.providerId,
+			keyId: config.privateKeyId,
+			issuer: config.issuer
+		});
+		if (!resolved) throw ctx.redirect(`${errorURL || callbackURL}?error=invalid_provider&error_description=no_private_key_available`);
+		const rawAlg = config.privateKeyAlgorithm ?? resolved.algorithm;
+		const algorithm = rawAlg && ASSERTION_SIGNING_ALGORITHMS.includes(rawAlg) ? rawAlg : void 0;
+		clientAssertionConfig = {
+			privateKeyJwk: resolved.privateKeyJwk,
+			privateKeyPem: resolved.privateKeyPem,
+			kid: config.privateKeyId ?? resolved.kid,
+			algorithm,
+			tokenEndpoint: config.tokenEndpoint
+		};
+	}
 	const tokenResponse = await validateAuthorizationCode({
 		code,
 		codeVerifier: config.pkce ? stateData.codeVerifier : void 0,
@@ -2321,7 +2702,8 @@ async function handleOIDCCallback(ctx, options, providerId, stateData) {
 			clientSecret: config.clientSecret
 		},
 		tokenEndpoint: config.tokenEndpoint,
-		authentication: config.tokenEndpointAuthentication === "client_secret_post" ? "post" : "basic"
+		authentication: authMethod,
+		clientAssertion: clientAssertionConfig
 	}).catch((e) => {
 		ctx.context.logger.error("Error validating authorization code", e);
 		if (e instanceof BetterFetchError) throw ctx.redirect(`${errorURL || callbackURL}?error=invalid_provider&error_description=${e.message}`);
@@ -2475,34 +2857,6 @@ const callbackSSOSAMLBodySchema = z.object({
 	SAMLResponse: z.string(),
 	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, callbackPath, appOrigin, isTrustedOrigin) => {
-	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;
-		if (new URL(url).pathname === callbackPathname) return appOrigin;
-	} catch {
-		if (url === callbackPath || url.startsWith(`${callbackPath}?`)) return appOrigin;
-	}
-	return url;
-};
 const callbackSSOSAML = (options) => {
 	return createAuthEndpoint("/sso/saml2/callback/:providerId", {
 		method: ["GET", "POST"],
@@ -2534,261 +2888,12 @@ const callbackSSOSAML = (options) => {
 			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 ?? 262144;
-		if (new TextEncoder().encode(SAMLResponse).length > maxResponseSize) throw new APIError("BAD_REQUEST", { message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)` });
-		let relayState = null;
-		if (ctx.body.RelayState) try {
-			relayState = await parseRelayState(ctx);
-		} catch {
-			relayState = null;
-		}
-		let provider = null;
-		if (options?.defaultSSO?.length) {
-			const matchingDefault = options.defaultSSO.find((defaultProvider) => defaultProvider.providerId === providerId);
-			if (matchingDefault) provider = {
-				...matchingDefault,
-				userId: "default",
-				issuer: matchingDefault.samlConfig?.issuer || "",
-				...options.domainVerification?.enabled ? { domainVerified: true } : {}
-			};
-		}
-		if (!provider) provider = await ctx.context.adapter.findOne({
-			model: "ssoProvider",
-			where: [{
-				field: "providerId",
-				value: providerId
-			}]
-		}).then((res) => {
-			if (!res) return null;
-			return {
-				...res,
-				samlConfig: res.samlConfig ? safeJsonParse(res.samlConfig) || void 0 : void 0
-			};
-		});
-		if (!provider) throw new APIError("NOT_FOUND", { message: "No provider found for the given providerId" });
-		if (options?.domainVerification?.enabled && !("domainVerified" in provider && provider.domainVerified)) throw new APIError("UNAUTHORIZED", { message: "Provider domain has not been verified" });
-		const parsedSamlConfig = safeJsonParse(provider.samlConfig);
-		if (!parsedSamlConfig) throw new APIError("BAD_REQUEST", { message: "Invalid SAML configuration" });
-		const idpData = parsedSamlConfig.idpMetadata;
-		let idp = null;
-		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 spData = parsedSamlConfig.spMetadata;
-		const sp = saml.ServiceProvider({
-			metadata: spData?.metadata,
-			entityID: spData?.entityID || parsedSamlConfig.issuer,
-			assertionConsumerService: spData?.metadata ? void 0 : [{
-				Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
-				Location: parsedSamlConfig.callbackUrl
-			}],
-			privateKey: spData?.privateKey || parsedSamlConfig.privateKey,
-			privateKeyPass: spData?.privateKeyPass,
-			isAssertionEncrypted: spData?.isAssertionEncrypted || false,
-			encPrivateKey: spData?.encPrivateKey,
-			encPrivateKeyPass: spData?.encPrivateKeyPass,
-			wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
-			nameIDFormat: parsedSamlConfig.identifierFormat ? [parsedSamlConfig.identifierFormat] : void 0
-		});
-		validateSingleAssertion(SAMLResponse);
-		let parsedResponse;
-		try {
-			parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
-				SAMLResponse,
-				RelayState: ctx.body.RelayState || void 0
-			} });
-			if (!parsedResponse?.extract) throw new Error("Invalid SAML response structure");
-		} catch (error) {
-			ctx.context.logger.error("SAML response validation failed", {
-				error,
-				decodedResponse: Buffer.from(SAMLResponse, "base64").toString("utf-8")
-			});
-			throw new APIError("BAD_REQUEST", {
-				message: "Invalid SAML response",
-				details: error instanceof Error ? error.message : String(error)
-			});
-		}
-		const { extract } = parsedResponse;
-		validateSAMLAlgorithms(parsedResponse, options?.saml?.algorithms);
-		validateSAMLTimestamp(extract.conditions, {
-			clockSkew: options?.saml?.clockSkew,
-			requireTimestamps: options?.saml?.requireTimestamps,
-			logger: ctx.context.logger
-		});
-		const inResponseTo = extract.inResponseTo;
-		if (options?.saml?.enableInResponseToValidation !== false) {
-			const allowIdpInitiated = options?.saml?.allowIdpInitiated !== false;
-			if (inResponseTo) {
-				let storedRequest = null;
-				const verification = await ctx.context.internalAdapter.findVerificationValue(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
-				if (verification) try {
-					storedRequest = JSON.parse(verification.value);
-					if (storedRequest && storedRequest.expiresAt < Date.now()) storedRequest = null;
-				} catch {
-					storedRequest = null;
-				}
-				if (!storedRequest) {
-					ctx.context.logger.error("SAML InResponseTo validation failed: unknown or expired request ID", {
-						inResponseTo,
-						providerId: provider.providerId
-					});
-					const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`);
-				}
-				if (storedRequest.providerId !== provider.providerId) {
-					ctx.context.logger.error("SAML InResponseTo validation failed: provider mismatch", {
-						inResponseTo,
-						expectedProvider: storedRequest.providerId,
-						actualProvider: provider.providerId
-					});
-					await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
-					const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`);
-				}
-				await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`);
-			} else if (!allowIdpInitiated) {
-				ctx.context.logger.error("SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false", { providerId: provider.providerId });
-				const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-				throw ctx.redirect(`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`);
-			}
-		}
-		const samlContent = parsedResponse.samlContent;
-		const assertionId = samlContent ? extractAssertionId(samlContent) : null;
-		if (assertionId) {
-			const issuer = idp.entityMeta.getEntityID();
-			const conditions = extract.conditions;
-			const clockSkew = options?.saml?.clockSkew ?? 3e5;
-			const expiresAt = conditions?.notOnOrAfter ? new Date(conditions.notOnOrAfter).getTime() + clockSkew : Date.now() + DEFAULT_ASSERTION_TTL_MS;
-			const existingAssertion = await ctx.context.internalAdapter.findVerificationValue(`${USED_ASSERTION_KEY_PREFIX}${assertionId}`);
-			let isReplay = false;
-			if (existingAssertion) try {
-				if (JSON.parse(existingAssertion.value).expiresAt >= Date.now()) isReplay = true;
-			} catch (error) {
-				ctx.context.logger.warn("Failed to parse stored assertion record", {
-					assertionId,
-					error
-				});
-			}
-			if (isReplay) {
-				ctx.context.logger.error("SAML assertion replay detected: assertion ID already used", {
-					assertionId,
-					issuer,
-					providerId: provider.providerId
-				});
-				const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-				throw ctx.redirect(`${redirectUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`);
-			}
-			await ctx.context.internalAdapter.createVerificationValue({
-				identifier: `${USED_ASSERTION_KEY_PREFIX}${assertionId}`,
-				value: JSON.stringify({
-					assertionId,
-					issuer,
-					providerId: provider.providerId,
-					usedAt: Date.now(),
-					expiresAt
-				}),
-				expiresAt: new Date(expiresAt)
-			});
-		} else ctx.context.logger.warn("Could not extract assertion ID for replay protection", { providerId: provider.providerId });
-		const attributes = extract.attributes || {};
-		const mapping = parsedSamlConfig.mapping ?? {};
-		const userInfo = {
-			...Object.fromEntries(Object.entries(mapping.extraFields || {}).map(([key, value]) => [key, attributes[value]])),
-			id: attributes[mapping.id || "nameID"] || extract.nameID,
-			email: (attributes[mapping.email || "email"] || extract.nameID).toLowerCase(),
-			name: [attributes[mapping.firstName || "givenName"], attributes[mapping.lastName || "surname"]].filter(Boolean).join(" ") || attributes[mapping.name || "displayName"] || extract.nameID,
-			emailVerified: options?.trustEmailVerified && mapping.emailVerified ? attributes[mapping.emailVerified] || false : false
-		};
-		if (!userInfo.id || !userInfo.email) {
-			ctx.context.logger.error("Missing essential user info from SAML response", {
-				attributes: Object.keys(attributes),
-				mapping,
-				extractedId: userInfo.id,
-				extractedEmail: userInfo.email
-			});
-			throw new APIError("BAD_REQUEST", { message: "Unable to extract user ID or email from SAML response" });
-		}
-		const isTrustedProvider = ctx.context.trustedProviders.includes(provider.providerId) || "domainVerified" in provider && !!provider.domainVerified && validateEmailDomain(userInfo.email, provider.domain);
-		const callbackUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-		const result = await handleOAuthUserInfo(ctx, {
-			userInfo: {
-				email: userInfo.email,
-				name: userInfo.name || userInfo.email,
-				id: userInfo.id,
-				emailVerified: Boolean(userInfo.emailVerified)
-			},
-			account: {
-				providerId: provider.providerId,
-				accountId: userInfo.id,
-				accessToken: "",
-				refreshToken: ""
-			},
-			callbackURL: callbackUrl,
-			disableSignUp: options?.disableImplicitSignUp,
-			isTrustedProvider
-		});
-		if (result.error) throw ctx.redirect(`${callbackUrl}?error=${result.error.split(" ").join("_")}`);
-		const { session, user } = result.data;
-		if (options?.provisionUser && (result.isRegister || options.provisionUserOnEveryLogin)) await options.provisionUser({
-			user,
-			userInfo,
-			provider
-		});
-		await assignOrganizationFromProvider(ctx, {
-			user,
-			profile: {
-				providerType: "saml",
-				providerId: provider.providerId,
-				accountId: userInfo.id,
-				email: userInfo.email,
-				emailVerified: Boolean(userInfo.emailVerified),
-				rawAttributes: attributes
-			},
-			provider,
-			provisioningOptions: options?.organizationProvisioning
-		});
-		await setSessionCookie(ctx, {
-			session,
-			user
-		});
-		if (options?.saml?.enableSingleLogout && extract.nameID) {
-			const samlSessionKey = `${SAML_SESSION_KEY_PREFIX}${provider.providerId}:${extract.nameID}`;
-			const samlSessionData = {
-				sessionId: session.id,
-				providerId: provider.providerId,
-				nameID: extract.nameID,
-				sessionIndex: extract.sessionIndex
-			};
-			await ctx.context.internalAdapter.createVerificationValue({
-				identifier: samlSessionKey,
-				value: JSON.stringify(samlSessionData),
-				expiresAt: session.expiresAt
-			}).catch((e) => ctx.context.logger.warn("Failed to create SAML session record", { error: e }));
-			await ctx.context.internalAdapter.createVerificationValue({
-				identifier: `${SAML_SESSION_BY_ID_PREFIX}${session.id}`,
-				value: samlSessionKey,
-				expiresAt: session.expiresAt
-			}).catch((e) => ctx.context.logger.warn("Failed to create SAML session lookup record", e));
-		}
-		const safeRedirectUrl = getSafeRedirectUrl(relayState?.callbackURL || parsedSamlConfig.callbackUrl, currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
+		const safeRedirectUrl = await processSAMLResponse(ctx, {
+			SAMLResponse: ctx.body.SAMLResponse,
+			RelayState: ctx.body.RelayState,
+			providerId,
+			currentCallbackPath
+		}, options);
 		throw ctx.redirect(safeRedirectUrl);
 	});
 };
@@ -2811,256 +2916,27 @@ const acsEndpoint = (options) => {
 			}
 		}
 	}, async (ctx) => {
-		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 ?? 262144;
-		if (new TextEncoder().encode(SAMLResponse).length > maxResponseSize) throw new APIError("BAD_REQUEST", { message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)` });
-		let relayState = null;
-		if (ctx.body.RelayState) try {
-			relayState = await parseRelayState(ctx);
-		} catch {
-			relayState = null;
-		}
-		let provider = null;
-		if (options?.defaultSSO?.length) {
-			const matchingDefault = providerId ? options.defaultSSO.find((defaultProvider) => defaultProvider.providerId === providerId) : options.defaultSSO[0];
-			if (matchingDefault) provider = {
-				issuer: matchingDefault.samlConfig?.issuer || "",
-				providerId: matchingDefault.providerId,
-				userId: "default",
-				samlConfig: matchingDefault.samlConfig,
-				domain: matchingDefault.domain,
-				...options.domainVerification?.enabled ? { domainVerified: true } : {}
-			};
-		} else provider = await ctx.context.adapter.findOne({
-			model: "ssoProvider",
-			where: [{
-				field: "providerId",
-				value: providerId
-			}]
-		}).then((res) => {
-			if (!res) return null;
-			return {
-				...res,
-				samlConfig: res.samlConfig ? safeJsonParse(res.samlConfig) || void 0 : void 0
-			};
-		});
-		if (!provider?.samlConfig) throw new APIError("NOT_FOUND", { message: "No SAML provider found" });
-		if (options?.domainVerification?.enabled && !("domainVerified" in provider && provider.domainVerified)) throw new APIError("UNAUTHORIZED", { message: "Provider domain has not been verified" });
-		const parsedSamlConfig = provider.samlConfig;
-		const sp = saml.ServiceProvider({
-			entityID: parsedSamlConfig.spMetadata?.entityID || parsedSamlConfig.issuer,
-			assertionConsumerService: [{
-				Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
-				Location: parsedSamlConfig.callbackUrl || `${ctx.context.baseURL}/sso/saml2/sp/acs/${providerId}`
-			}],
-			wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
-			metadata: parsedSamlConfig.spMetadata?.metadata,
-			privateKey: parsedSamlConfig.spMetadata?.privateKey || parsedSamlConfig.privateKey,
-			privateKeyPass: parsedSamlConfig.spMetadata?.privateKeyPass,
-			nameIDFormat: parsedSamlConfig.identifierFormat ? [parsedSamlConfig.identifierFormat] : void 0
-		});
-		const idpData = parsedSamlConfig.idpMetadata;
-		const idp = !idpData?.metadata ? 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
-		}) : saml.IdentityProvider({ metadata: idpData.metadata });
 		try {
-			validateSingleAssertion(SAMLResponse);
+			const safeRedirectUrl = await processSAMLResponse(ctx, {
+				SAMLResponse: ctx.body.SAMLResponse,
+				RelayState: ctx.body.RelayState,
+				providerId,
+				currentCallbackPath
+			}, options);
+			throw ctx.redirect(safeRedirectUrl);
 		} catch (error) {
-			if (error instanceof APIError) {
-				const redirectUrl = relayState?.callbackURL || 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)}`);
+			if (error instanceof Response || error && typeof error === "object" && "status" in error && error.status === 302) throw error;
+			if (error instanceof APIError && error.statusCode === 400) {
+				const internalCode = error.body?.code || "";
+				const errorCode = internalCode === "SAML_MULTIPLE_ASSERTIONS" ? "multiple_assertions" : internalCode === "SAML_NO_ASSERTION" ? "no_assertion" : internalCode.toLowerCase() || "saml_error";
+				const redirectUrl = getSafeRedirectUrl(ctx.body.RelayState || void 0, currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
+				throw ctx.redirect(`${redirectUrl}${redirectUrl.includes("?") ? "&" : "?"}error=${encodeURIComponent(errorCode)}&error_description=${encodeURIComponent(error.message)}`);
 			}
 			throw error;
 		}
-		let parsedResponse;
-		try {
-			parsedResponse = await sp.parseLoginResponse(idp, "post", { body: {
-				SAMLResponse,
-				RelayState: ctx.body.RelayState || void 0
-			} });
-			if (!parsedResponse?.extract) throw new Error("Invalid SAML response structure");
-		} catch (error) {
-			ctx.context.logger.error("SAML response validation failed", {
-				error,
-				decodedResponse: Buffer.from(SAMLResponse, "base64").toString("utf-8")
-			});
-			throw new APIError("BAD_REQUEST", {
-				message: "Invalid SAML response",
-				details: error instanceof Error ? error.message : String(error)
-			});
-		}
-		const { extract } = parsedResponse;
-		validateSAMLAlgorithms(parsedResponse, options?.saml?.algorithms);
-		validateSAMLTimestamp(extract.conditions, {
-			clockSkew: options?.saml?.clockSkew,
-			requireTimestamps: options?.saml?.requireTimestamps,
-			logger: ctx.context.logger
-		});
-		const inResponseToAcs = extract.inResponseTo;
-		if (options?.saml?.enableInResponseToValidation !== false) {
-			const allowIdpInitiated = options?.saml?.allowIdpInitiated !== false;
-			if (inResponseToAcs) {
-				let storedRequest = null;
-				const verification = await ctx.context.internalAdapter.findVerificationValue(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`);
-				if (verification) try {
-					storedRequest = JSON.parse(verification.value);
-					if (storedRequest && storedRequest.expiresAt < Date.now()) storedRequest = null;
-				} catch {
-					storedRequest = null;
-				}
-				if (!storedRequest) {
-					ctx.context.logger.error("SAML InResponseTo validation failed: unknown or expired request ID", {
-						inResponseTo: inResponseToAcs,
-						providerId
-					});
-					const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Unknown+or+expired+request+ID`);
-				}
-				if (storedRequest.providerId !== providerId) {
-					ctx.context.logger.error("SAML InResponseTo validation failed: provider mismatch", {
-						inResponseTo: inResponseToAcs,
-						expectedProvider: storedRequest.providerId,
-						actualProvider: providerId
-					});
-					await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`);
-					const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-					throw ctx.redirect(`${redirectUrl}?error=invalid_saml_response&error_description=Provider+mismatch`);
-				}
-				await ctx.context.internalAdapter.deleteVerificationByIdentifier(`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`);
-			} else if (!allowIdpInitiated) {
-				ctx.context.logger.error("SAML IdP-initiated SSO rejected: InResponseTo missing and allowIdpInitiated is false", { providerId });
-				const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-				throw ctx.redirect(`${redirectUrl}?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed`);
-			}
-		}
-		const assertionIdAcs = extractAssertionId(Buffer.from(SAMLResponse, "base64").toString("utf-8"));
-		if (assertionIdAcs) {
-			const issuer = idp.entityMeta.getEntityID();
-			const conditions = extract.conditions;
-			const clockSkew = options?.saml?.clockSkew ?? 3e5;
-			const expiresAt = conditions?.notOnOrAfter ? new Date(conditions.notOnOrAfter).getTime() + clockSkew : Date.now() + DEFAULT_ASSERTION_TTL_MS;
-			const existingAssertion = await ctx.context.internalAdapter.findVerificationValue(`${USED_ASSERTION_KEY_PREFIX}${assertionIdAcs}`);
-			let isReplay = false;
-			if (existingAssertion) try {
-				if (JSON.parse(existingAssertion.value).expiresAt >= Date.now()) isReplay = true;
-			} catch (error) {
-				ctx.context.logger.warn("Failed to parse stored assertion record", {
-					assertionId: assertionIdAcs,
-					error
-				});
-			}
-			if (isReplay) {
-				ctx.context.logger.error("SAML assertion replay detected: assertion ID already used", {
-					assertionId: assertionIdAcs,
-					issuer,
-					providerId
-				});
-				const redirectUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-				throw ctx.redirect(`${redirectUrl}?error=replay_detected&error_description=SAML+assertion+has+already+been+used`);
-			}
-			await ctx.context.internalAdapter.createVerificationValue({
-				identifier: `${USED_ASSERTION_KEY_PREFIX}${assertionIdAcs}`,
-				value: JSON.stringify({
-					assertionId: assertionIdAcs,
-					issuer,
-					providerId,
-					usedAt: Date.now(),
-					expiresAt
-				}),
-				expiresAt: new Date(expiresAt)
-			});
-		} else ctx.context.logger.warn("Could not extract assertion ID for replay protection", { providerId });
-		const attributes = extract.attributes || {};
-		const mapping = parsedSamlConfig.mapping ?? {};
-		const userInfo = {
-			...Object.fromEntries(Object.entries(mapping.extraFields || {}).map(([key, value]) => [key, attributes[value]])),
-			id: attributes[mapping.id || "nameID"] || extract.nameID,
-			email: (attributes[mapping.email || "email"] || extract.nameID).toLowerCase(),
-			name: [attributes[mapping.firstName || "givenName"], attributes[mapping.lastName || "surname"]].filter(Boolean).join(" ") || attributes[mapping.name || "displayName"] || extract.nameID,
-			emailVerified: options?.trustEmailVerified && mapping.emailVerified ? attributes[mapping.emailVerified] || false : false
-		};
-		if (!userInfo.id || !userInfo.email) {
-			ctx.context.logger.error("Missing essential user info from SAML response", {
-				attributes: Object.keys(attributes),
-				mapping,
-				extractedId: userInfo.id,
-				extractedEmail: userInfo.email
-			});
-			throw new APIError("BAD_REQUEST", { message: "Unable to extract user ID or email from SAML response" });
-		}
-		const isTrustedProvider = ctx.context.trustedProviders.includes(provider.providerId) || "domainVerified" in provider && !!provider.domainVerified && validateEmailDomain(userInfo.email, provider.domain);
-		const callbackUrl = relayState?.callbackURL || parsedSamlConfig.callbackUrl || ctx.context.baseURL;
-		const result = await handleOAuthUserInfo(ctx, {
-			userInfo: {
-				email: userInfo.email,
-				name: userInfo.name || userInfo.email,
-				id: userInfo.id,
-				emailVerified: Boolean(userInfo.emailVerified)
-			},
-			account: {
-				providerId: provider.providerId,
-				accountId: userInfo.id,
-				accessToken: "",
-				refreshToken: ""
-			},
-			callbackURL: callbackUrl,
-			disableSignUp: options?.disableImplicitSignUp,
-			isTrustedProvider
-		});
-		if (result.error) throw ctx.redirect(`${callbackUrl}?error=${result.error.split(" ").join("_")}`);
-		const { session, user } = result.data;
-		if (options?.provisionUser && (result.isRegister || options.provisionUserOnEveryLogin)) await options.provisionUser({
-			user,
-			userInfo,
-			provider
-		});
-		await assignOrganizationFromProvider(ctx, {
-			user,
-			profile: {
-				providerType: "saml",
-				providerId: provider.providerId,
-				accountId: userInfo.id,
-				email: userInfo.email,
-				emailVerified: Boolean(userInfo.emailVerified),
-				rawAttributes: attributes
-			},
-			provider,
-			provisioningOptions: options?.organizationProvisioning
-		});
-		await setSessionCookie(ctx, {
-			session,
-			user
-		});
-		if (options?.saml?.enableSingleLogout && extract.nameID) {
-			const samlSessionKey = `${SAML_SESSION_KEY_PREFIX}${providerId}:${extract.nameID}`;
-			const samlSessionData = {
-				sessionId: session.id,
-				providerId,
-				nameID: extract.nameID,
-				sessionIndex: extract.sessionIndex
-			};
-			await ctx.context.internalAdapter.createVerificationValue({
-				identifier: samlSessionKey,
-				value: JSON.stringify(samlSessionData),
-				expiresAt: session.expiresAt
-			}).catch((e) => ctx.context.logger.warn("Failed to create SAML session record", { error: e }));
-			await ctx.context.internalAdapter.createVerificationValue({
-				identifier: `${SAML_SESSION_BY_ID_PREFIX}${session.id}`,
-				value: samlSessionKey,
-				expiresAt: session.expiresAt
-			}).catch((e) => ctx.context.logger.warn("Failed to create SAML session lookup record", e));
-		}
-		const safeRedirectUrl = getSafeRedirectUrl(relayState?.callbackURL || parsedSamlConfig.callbackUrl, currentCallbackPath, appOrigin, (url, settings) => ctx.context.isTrustedOrigin(url, settings));
-		throw ctx.redirect(safeRedirectUrl);
 	});
 };
 const sloSchema = z.object({
@@ -3091,10 +2967,10 @@ const sloEndpoint = (options) => {
 		const provider = await findSAMLProvider(providerId, options, ctx.context.adapter);
 		if (!provider?.samlConfig) throw APIError.from("NOT_FOUND", SAML_ERROR_CODES.SAML_PROVIDER_NOT_FOUND);
 		const config = provider.samlConfig;
-		const sp = createSP(config, ctx.context.baseURL, providerId, {
+		const sp = createSP(config, ctx.context.baseURL, providerId, { sloOptions: {
 			wantLogoutRequestSigned: options?.saml?.wantLogoutRequestSigned,
 			wantLogoutResponseSigned: options?.saml?.wantLogoutResponseSigned
-		});
+		} });
 		const idp = createIdP(config);
 		if (samlResponse) return handleLogoutResponse(ctx, sp, idp, relayState, providerId);
 		return handleLogoutRequest(ctx, sp, idp, relayState, providerId);
@@ -3180,10 +3056,10 @@ const initiateSLO = (options) => {
 		if (!provider?.samlConfig) throw APIError.from("NOT_FOUND", SAML_ERROR_CODES.SAML_PROVIDER_NOT_FOUND);
 		const config = provider.samlConfig;
 		if (!(config.idpMetadata?.singleLogoutService?.length || config.idpMetadata?.metadata && config.idpMetadata.metadata.includes("SingleLogoutService"))) throw APIError.from("BAD_REQUEST", SAML_ERROR_CODES.IDP_SLO_NOT_SUPPORTED);
-		const sp = createSP(config, ctx.context.baseURL, providerId, {
+		const sp = createSP(config, ctx.context.baseURL, providerId, { sloOptions: {
 			wantLogoutRequestSigned: options?.saml?.wantLogoutRequestSigned,
 			wantLogoutResponseSigned: options?.saml?.wantLogoutResponseSigned
-		});
+		} });
 		const idp = createIdP(config);
 		const session = ctx.context.session;
 		const sessionLookupKey = `${SAML_SESSION_BY_ID_PREFIX}${session.session.id}`;