@better-auth/sso 1.5.0-beta.13 → 1.5.0-beta.15

package/src/routes/sso.ts

@@ -14,7 +14,7 @@ import {
 	getSessionFromCtx,
 	sessionMiddleware,
 } from "better-auth/api";
-import { setSessionCookie } from "better-auth/cookies";
+import { deleteSessionCookie, setSessionCookie } from "better-auth/cookies";
 import { generateRandomString } from "better-auth/crypto";
 import { handleOAuthUserInfo } from "better-auth/oauth2";
 import { XMLParser } from "fast-xml-parser";
@@ -24,6 +24,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;
@@ -32,15 +33,7 @@ interface AuthnRequestRecord {
 	expiresAt: number;
 }
 
-import {
-	AUTHN_REQUEST_KEY_PREFIX,
-	DEFAULT_ASSERTION_TTL_MS,
-	DEFAULT_AUTHN_REQUEST_TTL_MS,
-	DEFAULT_CLOCK_SKEW_MS,
-	DEFAULT_MAX_SAML_METADATA_SIZE,
-	DEFAULT_MAX_SAML_RESPONSE_SIZE,
-	USED_ASSERTION_KEY_PREFIX,
-} from "../constants";
+import * as constants from "../constants";
 import { assignOrganizationFromProvider } from "../linking";
 import type { HydratedOIDCConfig } from "../oidc";
 import {
@@ -53,9 +46,48 @@ import {
 	validateSAMLAlgorithms,
 	validateSingleAssertion,
 } from "../saml";
+import { SAML_ERROR_CODES } from "../saml/error-codes";
 import { generateRelayState, parseRelayState } from "../saml-state";
-import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "../types";
+import type {
+	OIDCConfig,
+	SAMLAssertionExtract,
+	SAMLConfig,
+	SAMLSessionRecord,
+	SSOOptions,
+	SSOProvider,
+} from "../types";
 import { domainMatches, safeJsonParse, validateEmailDomain } from "../utils";
+import {
+	createIdP,
+	createSAMLPostForm,
+	createSP,
+	findSAMLProvider,
+} from "./helpers";
+
+/**
+ * Builds the OIDC redirect URI. Uses the shared `redirectURI` option
+ * when set, otherwise falls back to `/sso/callback/:providerId`.
+ */
+function getOIDCRedirectURI(
+	baseURL: string,
+	providerId: string,
+	options?: SSOOptions,
+): string {
+	if (options?.redirectURI?.trim()) {
+		try {
+			// Full URL — use as-is
+			new URL(options.redirectURI);
+			return options.redirectURI;
+		} catch {
+			// Relative path — append to baseURL
+			const path = options.redirectURI.startsWith("/")
+				? options.redirectURI
+				: `/${options.redirectURI}`;
+			return `${baseURL}${path}`;
+		}
+	}
+	return `${baseURL}/sso/callback/${providerId}`;
+}
 
 export interface TimestampValidationOptions {
 	clockSkew?: number;
@@ -80,7 +112,7 @@ export function validateSAMLTimestamp(
 	conditions: SAMLConditions | undefined,
 	options: TimestampValidationOptions = {},
 ): void {
-	const clockSkew = options.clockSkew ?? DEFAULT_CLOCK_SKEW_MS;
+	const clockSkew = options.clockSkew ?? constants.DEFAULT_CLOCK_SKEW_MS;
 	const hasTimestamps = conditions?.notBefore || conditions?.notOnOrAfter;
 
 	if (!hasTimestamps) {
@@ -169,7 +201,7 @@ const spMetadataQuerySchema = z.object({
 
 type RelayState = Awaited<ReturnType<typeof parseRelayState>>;
 
-export const spMetadata = () => {
+export const spMetadata = (options?: SSOOptions) => {
 	return createAuthEndpoint(
 		"/sso/saml2/sp/metadata",
 		{
@@ -213,6 +245,21 @@ export const spMetadata = () => {
 					message: "Invalid SAML configuration",
 				});
 			}
+
+			const sloLocation = `${ctx.context.baseURL}/sso/saml2/sp/slo/${ctx.query.providerId}`;
+			const singleLogoutService = options?.saml?.enableSingleLogout
+				? [
+						{
+							Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
+							Location: sloLocation,
+						},
+						{
+							Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+							Location: sloLocation,
+						},
+					]
+				: undefined;
+
 			const sp = parsedSamlConfig.spMetadata.metadata
 				? saml.ServiceProvider({
 						metadata: parsedSamlConfig.spMetadata.metadata,
@@ -228,6 +275,7 @@ export const spMetadata = () => {
 									`${ctx.context.baseURL}/sso/saml2/sp/acs/${provider.id}`,
 							},
 						],
+						singleLogoutService,
 						wantMessageSigned: parsedSamlConfig.wantAssertionsSigned || false,
 						authnRequestsSigned: parsedSamlConfig.authnRequestsSigned || false,
 						nameIDFormat: parsedSamlConfig.identifierFormat
@@ -681,7 +729,8 @@ export const registerSSOProvider = <O extends SSOOptions>(options: O) => {
 
 			if (body.samlConfig?.idpMetadata?.metadata) {
 				const maxMetadataSize =
-					options?.saml?.maxMetadataSize ?? DEFAULT_MAX_SAML_METADATA_SIZE;
+					options?.saml?.maxMetadataSize ??
+					constants.DEFAULT_MAX_SAML_METADATA_SIZE;
 				if (
 					new TextEncoder().encode(body.samlConfig.idpMetadata.metadata)
 						.length > maxMetadataSize
@@ -863,9 +912,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,
@@ -895,7 +942,11 @@ export const registerSSOProvider = <O extends SSOOptions>(options: O) => {
 				samlConfig: safeJsonParse<SAMLConfig>(
 					provider.samlConfig as unknown as string,
 				),
-				redirectURI: `${ctx.context.baseURL}/sso/callback/${provider.providerId}`,
+				redirectURI: getOIDCRedirectURI(
+					ctx.context.baseURL,
+					provider.providerId,
+					options,
+				),
 				...(options?.domainVerification?.enabled ? { domainVerified } : {}),
 				...(options?.domainVerification?.enabled
 					? { domainVerificationToken }
@@ -1228,8 +1279,18 @@ export const signInSSO = (options?: SSOOptions) => {
 						message: "Invalid OIDC configuration. Authorization URL not found.",
 					});
 				}
-				const state = await generateState(ctx, undefined, false);
-				const redirectURI = `${ctx.context.baseURL}/sso/callback/${provider.providerId}`;
+				const state = await generateState(
+					ctx,
+					undefined,
+					options?.redirectURI?.trim()
+						? { ssoProviderId: provider.providerId }
+						: false,
+				);
+				const redirectURI = getOIDCRedirectURI(
+					ctx.context.baseURL,
+					provider.providerId,
+					options,
+				);
 				const authorizationURL = await createAuthorizationURL({
 					id: provider.issuer,
 					options: {
@@ -1368,7 +1429,8 @@ export const signInSSO = (options?: SSOOptions) => {
 				const shouldSaveRequest =
 					loginRequest.id && options?.saml?.enableInResponseToValidation;
 				if (shouldSaveRequest) {
-					const ttl = options?.saml?.requestTTL ?? DEFAULT_AUTHN_REQUEST_TTL_MS;
+					const ttl =
+						options?.saml?.requestTTL ?? constants.DEFAULT_AUTHN_REQUEST_TTL_MS;
 					const record: AuthnRequestRecord = {
 						id: loginRequest.id,
 						providerId: provider.providerId,
@@ -1376,7 +1438,7 @@ export const signInSSO = (options?: SSOOptions) => {
 						expiresAt: Date.now() + ttl,
 					};
 					await ctx.context.internalAdapter.createVerificationValue({
-						identifier: `${AUTHN_REQUEST_KEY_PREFIX}${record.id}`,
+						identifier: `${constants.AUTHN_REQUEST_KEY_PREFIX}${record.id}`,
 						value: JSON.stringify(record),
 						expiresAt: new Date(record.expiresAt),
 					});
@@ -1401,33 +1463,384 @@ const callbackSSOQuerySchema = z.object({
 	error_description: z.string().optional(),
 });
 
+/**
+ * Core OIDC callback handler logic, shared between the per-provider and
+ * shared callback endpoints. Resolves the provider, exchanges the
+ * authorization code for tokens, and creates a session.
+ *
+ * @param stateData - Pre-parsed state data. If not provided, it will be
+ *   parsed from the request context.
+ */
+async function handleOIDCCallback(
+	ctx: any,
+	options: SSOOptions | undefined,
+	providerId: string,
+	stateData?: Awaited<ReturnType<typeof parseState>>,
+) {
+	const { code, error, error_description } = ctx.query;
+	if (!stateData) {
+		stateData = await parseState(ctx);
+	}
+	if (!stateData) {
+		const errorURL =
+			ctx.context.options.onAPIError?.errorURL ||
+			`${ctx.context.baseURL}/error`;
+		throw ctx.redirect(`${errorURL}?error=invalid_state`);
+	}
+	const { callbackURL, errorURL, newUserURL, requestSignUp } = stateData;
+	if (!code || error) {
+		throw ctx.redirect(
+			`${
+				errorURL || callbackURL
+			}?error=${error}&error_description=${error_description}`,
+		);
+	}
+	let provider: SSOProvider<SSOOptions> | null = null;
+	if (options?.defaultSSO?.length) {
+		const matchingDefault = options.defaultSSO.find(
+			(defaultProvider) => defaultProvider.providerId === providerId,
+		);
+		if (matchingDefault) {
+			provider = {
+				...matchingDefault,
+				issuer: matchingDefault.oidcConfig?.issuer || "",
+				userId: "default",
+				...(options.domainVerification?.enabled
+					? { domainVerified: true }
+					: {}),
+			} as SSOProvider<SSOOptions>;
+		}
+	}
+	if (!provider) {
+		provider = await ctx.context.adapter
+			.findOne({
+				model: "ssoProvider",
+				where: [
+					{
+						field: "providerId",
+						value: providerId,
+					},
+				],
+			})
+			.then((res: { oidcConfig: string } | null) => {
+				if (!res) {
+					return null;
+				}
+				return {
+					...res,
+					oidcConfig: safeJsonParse<OIDCConfig>(res.oidcConfig) || undefined,
+				} as SSOProvider<SSOOptions>;
+			});
+	}
+	if (!provider) {
+		throw ctx.redirect(
+			`${
+				errorURL || callbackURL
+			}?error=invalid_provider&error_description=provider not found`,
+		);
+	}
+
+	if (
+		options?.domainVerification?.enabled &&
+		!("domainVerified" in provider && provider.domainVerified)
+	) {
+		throw new APIError("UNAUTHORIZED", {
+			message: "Provider domain has not been verified",
+		});
+	}
+
+	let config = provider.oidcConfig;
+
+	if (!config) {
+		throw ctx.redirect(
+			`${
+				errorURL || callbackURL
+			}?error=invalid_provider&error_description=provider not found`,
+		);
+	}
+
+	const discovery = await betterFetch<{
+		token_endpoint: string;
+		userinfo_endpoint: string;
+		token_endpoint_auth_method: "client_secret_basic" | "client_secret_post";
+	}>(config.discoveryEndpoint);
+
+	if (discovery.data) {
+		config = {
+			tokenEndpoint: discovery.data.token_endpoint,
+			tokenEndpointAuthentication: discovery.data.token_endpoint_auth_method,
+			userInfoEndpoint: discovery.data.userinfo_endpoint,
+			scopes: ["openid", "email", "profile", "offline_access"],
+			...config,
+		};
+	}
+
+	if (!config.tokenEndpoint) {
+		throw ctx.redirect(
+			`${
+				errorURL || callbackURL
+			}?error=invalid_provider&error_description=token_endpoint_not_found`,
+		);
+	}
+
+	const tokenResponse = await validateAuthorizationCode({
+		code,
+		codeVerifier: config.pkce ? stateData.codeVerifier : undefined,
+		redirectURI: getOIDCRedirectURI(
+			ctx.context.baseURL,
+			provider.providerId,
+			options,
+		),
+		options: {
+			clientId: config.clientId,
+			clientSecret: config.clientSecret,
+		},
+		tokenEndpoint: config.tokenEndpoint,
+		authentication:
+			config.tokenEndpointAuthentication === "client_secret_post"
+				? "post"
+				: "basic",
+	}).catch((e) => {
+		if (e instanceof BetterFetchError) {
+			throw ctx.redirect(
+				`${
+					errorURL || callbackURL
+				}?error=invalid_provider&error_description=${e.message}`,
+			);
+		}
+		return null;
+	});
+	if (!tokenResponse) {
+		throw ctx.redirect(
+			`${
+				errorURL || callbackURL
+			}?error=invalid_provider&error_description=token_response_not_found`,
+		);
+	}
+	let userInfo: {
+		id?: string;
+		email?: string;
+		name?: string;
+		image?: string;
+		emailVerified?: boolean;
+		[key: string]: any;
+	} | null = null;
+	if (tokenResponse.idToken) {
+		const idToken = decodeJwt(tokenResponse.idToken);
+		if (!config.jwksEndpoint) {
+			throw ctx.redirect(
+				`${
+					errorURL || callbackURL
+				}?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;
+		});
+		if (!verified) {
+			throw ctx.redirect(
+				`${
+					errorURL || callbackURL
+				}?error=invalid_provider&error_description=token_not_verified`,
+			);
+		}
+
+		const mapping = config.mapping || {};
+		userInfo = {
+			...Object.fromEntries(
+				Object.entries(mapping.extraFields || {}).map(([key, value]) => [
+					key,
+					verified.payload[value],
+				]),
+			),
+			id: idToken[mapping.id || "sub"],
+			email: idToken[mapping.email || "email"],
+			emailVerified: options?.trustEmailVerified
+				? idToken[mapping.emailVerified || "email_verified"]
+				: false,
+			name: idToken[mapping.name || "name"],
+			image: idToken[mapping.image || "picture"],
+		} as {
+			id?: string;
+			email?: string;
+			name?: string;
+			image?: string;
+			emailVerified?: boolean;
+		};
+	}
+
+	if (!userInfo) {
+		if (!config.userInfoEndpoint) {
+			throw ctx.redirect(
+				`${
+					errorURL || callbackURL
+				}?error=invalid_provider&error_description=user_info_endpoint_not_found`,
+			);
+		}
+		const userInfoResponse = await betterFetch<{
+			email?: string;
+			name?: string;
+			id?: string;
+			image?: string;
+			emailVerified?: boolean;
+		}>(config.userInfoEndpoint, {
+			headers: {
+				Authorization: `Bearer ${tokenResponse.accessToken}`,
+			},
+		});
+		if (userInfoResponse.error) {
+			throw ctx.redirect(
+				`${errorURL || callbackURL}?error=invalid_provider&error_description=${
+					userInfoResponse.error.message
+				}`,
+			);
+		}
+		userInfo = userInfoResponse.data;
+	}
+
+	if (!userInfo.email || !userInfo.id) {
+		throw ctx.redirect(
+			`${
+				errorURL || callbackURL
+			}?error=invalid_provider&error_description=missing_user_info`,
+		);
+	}
+	const isTrustedProvider =
+		"domainVerified" in provider &&
+		(provider as { domainVerified?: boolean }).domainVerified === true &&
+		validateEmailDomain(userInfo.email, provider.domain);
+
+	const linked = await handleOAuthUserInfo(ctx, {
+		userInfo: {
+			email: userInfo.email,
+			name: userInfo.name || "",
+			id: userInfo.id,
+			image: userInfo.image,
+			emailVerified: options?.trustEmailVerified
+				? userInfo.emailVerified || false
+				: false,
+		},
+		account: {
+			idToken: tokenResponse.idToken,
+			accessToken: tokenResponse.accessToken,
+			refreshToken: tokenResponse.refreshToken,
+			accountId: userInfo.id,
+			providerId: provider.providerId,
+			accessTokenExpiresAt: tokenResponse.accessTokenExpiresAt,
+			refreshTokenExpiresAt: tokenResponse.refreshTokenExpiresAt,
+			scope: tokenResponse.scopes?.join(","),
+		},
+		callbackURL,
+		disableSignUp: options?.disableImplicitSignUp && !requestSignUp,
+		overrideUserInfo: config.overrideUserInfo,
+		isTrustedProvider,
+	});
+	if (linked.error) {
+		throw ctx.redirect(`${errorURL || callbackURL}?error=${linked.error}`);
+	}
+	const { session, user } = linked.data!;
+
+	if (options?.provisionUser && linked.isRegister) {
+		await options.provisionUser({
+			user,
+			userInfo,
+			token: tokenResponse,
+			provider,
+		});
+	}
+
+	await assignOrganizationFromProvider(ctx as any, {
+		user,
+		profile: {
+			providerType: "oidc",
+			providerId: provider.providerId,
+			accountId: userInfo.id,
+			email: userInfo.email,
+			emailVerified: Boolean(userInfo.emailVerified),
+			rawAttributes: userInfo,
+		},
+		provider,
+		token: tokenResponse,
+		provisioningOptions: options?.organizationProvisioning,
+	});
+
+	await setSessionCookie(ctx, {
+		session,
+		user,
+	});
+	let toRedirectTo: string;
+	try {
+		const url = linked.isRegister ? newUserURL || callbackURL : callbackURL;
+		toRedirectTo = url.toString();
+	} catch {
+		toRedirectTo = linked.isRegister ? newUserURL || callbackURL : callbackURL;
+	}
+	throw ctx.redirect(toRedirectTo);
+}
+
+const callbackSSOEndpointConfig = {
+	method: "GET" as const,
+	query: callbackSSOQuerySchema,
+	allowedMediaTypes: [
+		"application/x-www-form-urlencoded",
+		"application/json",
+	] as const,
+	metadata: {
+		...HIDE_METADATA,
+		openapi: {
+			operationId: "handleSSOCallback",
+			summary: "Callback URL for SSO provider",
+			description:
+				"This endpoint is used as the callback URL for SSO providers. It handles the authorization code and exchanges it for an access token",
+			responses: {
+				"302": {
+					description: "Redirects to the callback URL",
+				},
+			},
+		},
+	},
+};
+
 export const callbackSSO = (options?: SSOOptions) => {
 	return createAuthEndpoint(
 		"/sso/callback/:providerId",
+		callbackSSOEndpointConfig,
+		async (ctx) => {
+			return handleOIDCCallback(ctx, options, ctx.params.providerId);
+		},
+	);
+};
+
+/**
+ * Shared OIDC callback endpoint (no `:providerId` in path).
+ * Used when `options.redirectURI` is set — the `providerId` is read from
+ * the OAuth state instead of the URL path.
+ */
+export const callbackSSOShared = (options?: SSOOptions) => {
+	return createAuthEndpoint(
+		"/sso/callback",
 		{
-			method: "GET",
-			query: callbackSSOQuerySchema,
-			allowedMediaTypes: [
-				"application/x-www-form-urlencoded",
-				"application/json",
-			],
+			...callbackSSOEndpointConfig,
 			metadata: {
-				...HIDE_METADATA,
+				...callbackSSOEndpointConfig.metadata,
 				openapi: {
-					operationId: "handleSSOCallback",
-					summary: "Callback URL for SSO provider",
+					...callbackSSOEndpointConfig.metadata.openapi,
+					operationId: "handleSSOCallbackShared",
+					summary: "Shared callback URL for all SSO providers",
 					description:
-						"This endpoint is used as the callback URL for SSO providers. It handles the authorization code and exchanges it for an access token",
-					responses: {
-						"302": {
-							description: "Redirects to the callback URL",
-						},
-					},
+						"This endpoint is used as a shared callback URL for all SSO providers when `redirectURI` is configured. The provider is identified via the OAuth state parameter.",
 				},
 			},
 		},
 		async (ctx) => {
-			const { code, error, error_description } = ctx.query;
 			const stateData = await parseState(ctx);
 			if (!stateData) {
 				const errorURL =
@@ -1435,310 +1848,16 @@ export const callbackSSO = (options?: SSOOptions) => {
 					`${ctx.context.baseURL}/error`;
 				throw ctx.redirect(`${errorURL}?error=invalid_state`);
 			}
-			const { callbackURL, errorURL, newUserURL, requestSignUp } = stateData;
-			if (!code || error) {
-				throw ctx.redirect(
-					`${
-						errorURL || callbackURL
-					}?error=${error}&error_description=${error_description}`,
-				);
-			}
-			let provider: SSOProvider<SSOOptions> | null = null;
-			if (options?.defaultSSO?.length) {
-				const matchingDefault = options.defaultSSO.find(
-					(defaultProvider) =>
-						defaultProvider.providerId === ctx.params.providerId,
-				);
-				if (matchingDefault) {
-					provider = {
-						...matchingDefault,
-						issuer: matchingDefault.oidcConfig?.issuer || "",
-						userId: "default",
-						...(options.domainVerification?.enabled
-							? { domainVerified: true }
-							: {}),
-					} as SSOProvider<SSOOptions>;
-				}
-			}
-			if (!provider) {
-				provider = await ctx.context.adapter
-					.findOne<{
-						oidcConfig: string;
-					}>({
-						model: "ssoProvider",
-						where: [
-							{
-								field: "providerId",
-								value: ctx.params.providerId,
-							},
-						],
-					})
-					.then((res) => {
-						if (!res) {
-							return null;
-						}
-						return {
-							...res,
-							oidcConfig:
-								safeJsonParse<OIDCConfig>(res.oidcConfig) || undefined,
-						} as SSOProvider<SSOOptions>;
-					});
-			}
-			if (!provider) {
-				throw ctx.redirect(
-					`${
-						errorURL || callbackURL
-					}?error=invalid_provider&error_description=provider not found`,
-				);
-			}
-
-			if (
-				options?.domainVerification?.enabled &&
-				!("domainVerified" in provider && provider.domainVerified)
-			) {
-				throw new APIError("UNAUTHORIZED", {
-					message: "Provider domain has not been verified",
-				});
-			}
-
-			let config = provider.oidcConfig;
-
-			if (!config) {
-				throw ctx.redirect(
-					`${
-						errorURL || callbackURL
-					}?error=invalid_provider&error_description=provider not found`,
-				);
-			}
-
-			const discovery = await betterFetch<{
-				token_endpoint: string;
-				userinfo_endpoint: string;
-				token_endpoint_auth_method:
-					| "client_secret_basic"
-					| "client_secret_post";
-			}>(config.discoveryEndpoint);
-
-			if (discovery.data) {
-				config = {
-					tokenEndpoint: discovery.data.token_endpoint,
-					tokenEndpointAuthentication:
-						discovery.data.token_endpoint_auth_method,
-					userInfoEndpoint: discovery.data.userinfo_endpoint,
-					scopes: ["openid", "email", "profile", "offline_access"],
-					...config,
-				};
-			}
-
-			if (!config.tokenEndpoint) {
-				throw ctx.redirect(
-					`${
-						errorURL || callbackURL
-					}?error=invalid_provider&error_description=token_endpoint_not_found`,
-				);
-			}
-
-			const tokenResponse = await validateAuthorizationCode({
-				code,
-				codeVerifier: config.pkce ? stateData.codeVerifier : undefined,
-				redirectURI: `${ctx.context.baseURL}/sso/callback/${provider.providerId}`,
-				options: {
-					clientId: config.clientId,
-					clientSecret: config.clientSecret,
-				},
-				tokenEndpoint: config.tokenEndpoint,
-				authentication:
-					config.tokenEndpointAuthentication === "client_secret_post"
-						? "post"
-						: "basic",
-			}).catch((e) => {
-				if (e instanceof BetterFetchError) {
-					throw ctx.redirect(
-						`${
-							errorURL || callbackURL
-						}?error=invalid_provider&error_description=${e.message}`,
-					);
-				}
-				return null;
-			});
-			if (!tokenResponse) {
-				throw ctx.redirect(
-					`${
-						errorURL || callbackURL
-					}?error=invalid_provider&error_description=token_response_not_found`,
-				);
-			}
-			let userInfo: {
-				id?: string;
-				email?: string;
-				name?: string;
-				image?: string;
-				emailVerified?: boolean;
-				[key: string]: any;
-			} | null = null;
-			if (tokenResponse.idToken) {
-				const idToken = decodeJwt(tokenResponse.idToken);
-				if (!config.jwksEndpoint) {
-					throw ctx.redirect(
-						`${
-							errorURL || callbackURL
-						}?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;
-				});
-				if (!verified) {
-					throw ctx.redirect(
-						`${
-							errorURL || callbackURL
-						}?error=invalid_provider&error_description=token_not_verified`,
-					);
-				}
-
-				const mapping = config.mapping || {};
-				userInfo = {
-					...Object.fromEntries(
-						Object.entries(mapping.extraFields || {}).map(([key, value]) => [
-							key,
-							verified.payload[value],
-						]),
-					),
-					id: idToken[mapping.id || "sub"],
-					email: idToken[mapping.email || "email"],
-					emailVerified: options?.trustEmailVerified
-						? idToken[mapping.emailVerified || "email_verified"]
-						: false,
-					name: idToken[mapping.name || "name"],
-					image: idToken[mapping.image || "picture"],
-				} as {
-					id?: string;
-					email?: string;
-					name?: string;
-					image?: string;
-					emailVerified?: boolean;
-				};
-			}
 
-			if (!userInfo) {
-				if (!config.userInfoEndpoint) {
-					throw ctx.redirect(
-						`${
-							errorURL || callbackURL
-						}?error=invalid_provider&error_description=user_info_endpoint_not_found`,
-					);
-				}
-				const userInfoResponse = await betterFetch<{
-					email?: string;
-					name?: string;
-					id?: string;
-					image?: string;
-					emailVerified?: boolean;
-				}>(config.userInfoEndpoint, {
-					headers: {
-						Authorization: `Bearer ${tokenResponse.accessToken}`,
-					},
-				});
-				if (userInfoResponse.error) {
-					throw ctx.redirect(
-						`${
-							errorURL || callbackURL
-						}?error=invalid_provider&error_description=${
-							userInfoResponse.error.message
-						}`,
-					);
-				}
-				userInfo = userInfoResponse.data;
-			}
-
-			if (!userInfo.email || !userInfo.id) {
+			const providerId = stateData.ssoProviderId as string | undefined;
+			if (!providerId) {
+				const errorURL = stateData.errorURL || stateData.callbackURL;
 				throw ctx.redirect(
-					`${
-						errorURL || callbackURL
-					}?error=invalid_provider&error_description=missing_user_info`,
+					`${errorURL}?error=invalid_state&error_description=missing_provider_id`,
 				);
 			}
-			const isTrustedProvider =
-				"domainVerified" in provider &&
-				(provider as { domainVerified?: boolean }).domainVerified === true &&
-				validateEmailDomain(userInfo.email, provider.domain);
-
-			const linked = await handleOAuthUserInfo(ctx, {
-				userInfo: {
-					email: userInfo.email,
-					name: userInfo.name || userInfo.email,
-					id: userInfo.id,
-					image: userInfo.image,
-					emailVerified: options?.trustEmailVerified
-						? userInfo.emailVerified || false
-						: false,
-				},
-				account: {
-					idToken: tokenResponse.idToken,
-					accessToken: tokenResponse.accessToken,
-					refreshToken: tokenResponse.refreshToken,
-					accountId: userInfo.id,
-					providerId: provider.providerId,
-					accessTokenExpiresAt: tokenResponse.accessTokenExpiresAt,
-					refreshTokenExpiresAt: tokenResponse.refreshTokenExpiresAt,
-					scope: tokenResponse.scopes?.join(","),
-				},
-				callbackURL,
-				disableSignUp: options?.disableImplicitSignUp && !requestSignUp,
-				overrideUserInfo: config.overrideUserInfo,
-				isTrustedProvider,
-			});
-			if (linked.error) {
-				throw ctx.redirect(`${errorURL || callbackURL}?error=${linked.error}`);
-			}
-			const { session, user } = linked.data!;
 
-			if (options?.provisionUser) {
-				await options.provisionUser({
-					user,
-					userInfo,
-					token: tokenResponse,
-					provider,
-				});
-			}
-
-			await assignOrganizationFromProvider(ctx as any, {
-				user,
-				profile: {
-					providerType: "oidc",
-					providerId: provider.providerId,
-					accountId: userInfo.id,
-					email: userInfo.email,
-					emailVerified: Boolean(userInfo.emailVerified),
-					rawAttributes: userInfo,
-				},
-				provider,
-				token: tokenResponse,
-				provisioningOptions: options?.organizationProvisioning,
-			});
-
-			await setSessionCookie(ctx, {
-				session,
-				user,
-			});
-			let toRedirectTo: string;
-			try {
-				const url = linked.isRegister ? newUserURL || callbackURL : callbackURL;
-				toRedirectTo = url.toString();
-			} catch {
-				toRedirectTo = linked.isRegister
-					? newUserURL || callbackURL
-					: callbackURL;
-			}
-			throw ctx.redirect(toRedirectTo);
+			return handleOIDCCallback(ctx, options, providerId, stateData);
 		},
 	);
 };
@@ -1876,7 +1995,8 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 			const { SAMLResponse } = ctx.body;
 
 			const maxResponseSize =
-				options?.saml?.maxResponseSize ?? DEFAULT_MAX_SAML_RESPONSE_SIZE;
+				options?.saml?.maxResponseSize ??
+				constants.DEFAULT_MAX_SAML_RESPONSE_SIZE;
 			if (new TextEncoder().encode(SAMLResponse).length > maxResponseSize) {
 				throw new APIError("BAD_REQUEST", {
 					message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)`,
@@ -2035,13 +2155,15 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 
 			validateSAMLAlgorithms(parsedResponse, options?.saml?.algorithms);
 
-			validateSAMLTimestamp((extract as any).conditions, {
+			validateSAMLTimestamp((extract as SAMLAssertionExtract).conditions, {
 				clockSkew: options?.saml?.clockSkew,
 				requireTimestamps: options?.saml?.requireTimestamps,
 				logger: ctx.context.logger,
 			});
 
-			const inResponseTo = (extract as any).inResponseTo as string | undefined;
+			const inResponseTo = (extract as SAMLAssertionExtract).inResponseTo as
+				| string
+				| undefined;
 			const shouldValidateInResponseTo =
 				options?.saml?.enableInResponseToValidation;
 
@@ -2053,7 +2175,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 
 					const verification =
 						await ctx.context.internalAdapter.findVerificationValue(
-							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
+							`${constants.AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
 						);
 					if (verification) {
 						try {
@@ -2093,7 +2215,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 						);
 
 						await ctx.context.internalAdapter.deleteVerificationByIdentifier(
-							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
+							`${constants.AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
 						);
 						const redirectUrl =
 							relayState?.callbackURL ||
@@ -2105,7 +2227,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 					}
 
 					await ctx.context.internalAdapter.deleteVerificationByIdentifier(
-						`${AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
+						`${constants.AUTHN_REQUEST_KEY_PREFIX}${inResponseTo}`,
 					);
 				} else if (!allowIdpInitiated) {
 					ctx.context.logger.error(
@@ -2130,17 +2252,18 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 
 			if (assertionId) {
 				const issuer = idp.entityMeta.getEntityID();
-				const conditions = (extract as any).conditions as
+				const conditions = (extract as SAMLAssertionExtract).conditions as
 					| SAMLConditions
 					| undefined;
-				const clockSkew = options?.saml?.clockSkew ?? DEFAULT_CLOCK_SKEW_MS;
+				const clockSkew =
+					options?.saml?.clockSkew ?? constants.DEFAULT_CLOCK_SKEW_MS;
 				const expiresAt = conditions?.notOnOrAfter
 					? new Date(conditions.notOnOrAfter).getTime() + clockSkew
-					: Date.now() + DEFAULT_ASSERTION_TTL_MS;
+					: Date.now() + constants.DEFAULT_ASSERTION_TTL_MS;
 
 				const existingAssertion =
 					await ctx.context.internalAdapter.findVerificationValue(
-						`${USED_ASSERTION_KEY_PREFIX}${assertionId}`,
+						`${constants.USED_ASSERTION_KEY_PREFIX}${assertionId}`,
 					);
 
 				let isReplay = false;
@@ -2177,7 +2300,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 				}
 
 				await ctx.context.internalAdapter.createVerificationValue({
-					identifier: `${USED_ASSERTION_KEY_PREFIX}${assertionId}`,
+					identifier: `${constants.USED_ASSERTION_KEY_PREFIX}${assertionId}`,
 					value: JSON.stringify({
 						assertionId,
 						issuer,
@@ -2300,6 +2423,39 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 
 			await setSessionCookie(ctx, { session, user });
 
+			if (options?.saml?.enableSingleLogout && extract.nameID) {
+				const samlSessionKey = `${constants.SAML_SESSION_KEY_PREFIX}${provider.providerId}:${extract.nameID}`;
+				const samlSessionData: SAMLSessionRecord = {
+					sessionId: session.id,
+					providerId: provider.providerId,
+					nameID: extract.nameID,
+					sessionIndex: (extract as SAMLAssertionExtract).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: `${constants.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,
@@ -2349,7 +2505,8 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			const appOrigin = new URL(ctx.context.baseURL).origin;
 
 			const maxResponseSize =
-				options?.saml?.maxResponseSize ?? DEFAULT_MAX_SAML_RESPONSE_SIZE;
+				options?.saml?.maxResponseSize ??
+				constants.DEFAULT_MAX_SAML_RESPONSE_SIZE;
 			if (new TextEncoder().encode(SAMLResponse).length > maxResponseSize) {
 				throw new APIError("BAD_REQUEST", {
 					message: `SAML response exceeds maximum allowed size (${maxResponseSize} bytes)`,
@@ -2516,13 +2673,13 @@ export const acsEndpoint = (options?: SSOOptions) => {
 
 			validateSAMLAlgorithms(parsedResponse, options?.saml?.algorithms);
 
-			validateSAMLTimestamp((extract as any).conditions, {
+			validateSAMLTimestamp((extract as SAMLAssertionExtract).conditions, {
 				clockSkew: options?.saml?.clockSkew,
 				requireTimestamps: options?.saml?.requireTimestamps,
 				logger: ctx.context.logger,
 			});
 
-			const inResponseToAcs = (extract as any).inResponseTo as
+			const inResponseToAcs = (extract as SAMLAssertionExtract).inResponseTo as
 				| string
 				| undefined;
 			const shouldValidateInResponseToAcs =
@@ -2536,7 +2693,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 
 					const verification =
 						await ctx.context.internalAdapter.findVerificationValue(
-							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
+							`${constants.AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
 						);
 					if (verification) {
 						try {
@@ -2575,7 +2732,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 							},
 						);
 						await ctx.context.internalAdapter.deleteVerificationByIdentifier(
-							`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
+							`${constants.AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
 						);
 						const redirectUrl =
 							relayState?.callbackURL ||
@@ -2587,7 +2744,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 					}
 
 					await ctx.context.internalAdapter.deleteVerificationByIdentifier(
-						`${AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
+						`${constants.AUTHN_REQUEST_KEY_PREFIX}${inResponseToAcs}`,
 					);
 				} else if (!allowIdpInitiated) {
 					ctx.context.logger.error(
@@ -2612,17 +2769,18 @@ export const acsEndpoint = (options?: SSOOptions) => {
 
 			if (assertionIdAcs) {
 				const issuer = idp.entityMeta.getEntityID();
-				const conditions = (extract as any).conditions as
+				const conditions = (extract as SAMLAssertionExtract).conditions as
 					| SAMLConditions
 					| undefined;
-				const clockSkew = options?.saml?.clockSkew ?? DEFAULT_CLOCK_SKEW_MS;
+				const clockSkew =
+					options?.saml?.clockSkew ?? constants.DEFAULT_CLOCK_SKEW_MS;
 				const expiresAt = conditions?.notOnOrAfter
 					? new Date(conditions.notOnOrAfter).getTime() + clockSkew
-					: Date.now() + DEFAULT_ASSERTION_TTL_MS;
+					: Date.now() + constants.DEFAULT_ASSERTION_TTL_MS;
 
 				const existingAssertion =
 					await ctx.context.internalAdapter.findVerificationValue(
-						`${USED_ASSERTION_KEY_PREFIX}${assertionIdAcs}`,
+						`${constants.USED_ASSERTION_KEY_PREFIX}${assertionIdAcs}`,
 					);
 
 				let isReplay = false;
@@ -2659,7 +2817,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 				}
 
 				await ctx.context.internalAdapter.createVerificationValue({
-					identifier: `${USED_ASSERTION_KEY_PREFIX}${assertionIdAcs}`,
+					identifier: `${constants.USED_ASSERTION_KEY_PREFIX}${assertionIdAcs}`,
 					value: JSON.stringify({
 						assertionId: assertionIdAcs,
 						issuer,
@@ -2782,6 +2940,39 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			});
 
 			await setSessionCookie(ctx, { session, user });
+			if (options?.saml?.enableSingleLogout && extract.nameID) {
+				const samlSessionKey = `${constants.SAML_SESSION_KEY_PREFIX}${providerId}:${extract.nameID}`;
+				const samlSessionData: SAMLSessionRecord = {
+					sessionId: session.id,
+					providerId,
+					nameID: extract.nameID,
+					sessionIndex: (extract as SAMLAssertionExtract).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: `${constants.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,
@@ -2792,3 +2983,383 @@ export const acsEndpoint = (options?: SSOOptions) => {
 		},
 	);
 };
+
+const sloSchema = z.object({
+	SAMLRequest: z.string().optional(),
+	SAMLResponse: z.string().optional(),
+	RelayState: z.string().optional(),
+	SigAlg: z.string().optional(),
+	Signature: z.string().optional(),
+});
+
+export const sloEndpoint = (options?: SSOOptions) => {
+	return createAuthEndpoint(
+		"/sso/saml2/sp/slo/:providerId",
+		{
+			method: ["GET", "POST"],
+			body: sloSchema.optional(),
+			query: sloSchema.optional(),
+			metadata: {
+				...HIDE_METADATA,
+				allowedMediaTypes: [
+					"application/x-www-form-urlencoded",
+					"application/json",
+				],
+			},
+		},
+		async (ctx) => {
+			if (!options?.saml?.enableSingleLogout) {
+				throw APIError.from(
+					"BAD_REQUEST",
+					SAML_ERROR_CODES.SINGLE_LOGOUT_NOT_ENABLED,
+				);
+			}
+
+			const { providerId } = ctx.params;
+
+			const samlRequest = ctx.body?.SAMLRequest || ctx.query?.SAMLRequest;
+			const samlResponse = ctx.body?.SAMLResponse || ctx.query?.SAMLResponse;
+			const relayState = ctx.body?.RelayState || ctx.query?.RelayState;
+			const appOrigin = new URL(ctx.context.baseURL).origin;
+			const safeErrorURL = getSafeRedirectUrl(
+				relayState,
+				`${appOrigin}/sso/saml2/sp/slo/${providerId}`,
+				appOrigin,
+				(url, settings) => ctx.context.isTrustedOrigin(url, settings),
+			);
+
+			if (!samlRequest && !samlResponse) {
+				throw ctx.redirect(
+					`${safeErrorURL}?error=invalid_request&error_description=missing_logout_data`,
+				);
+			}
+
+			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 as SAMLConfig;
+			const sp = createSP(config, ctx.context.baseURL, providerId, {
+				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);
+		},
+	);
+};
+
+async function handleLogoutResponse(
+	ctx: any,
+	sp: ReturnType<typeof createSP>,
+	idp: ReturnType<typeof createIdP>,
+	relayState: string | undefined,
+	providerId: string,
+) {
+	const binding =
+		ctx.method === "POST" && ctx.body?.SAMLResponse ? "post" : "redirect";
+
+	let parsed: Awaited<ReturnType<typeof sp.parseLogoutResponse>> | undefined;
+	try {
+		parsed = await sp.parseLogoutResponse(idp, binding, {
+			body: ctx.body,
+			query: ctx.query,
+		});
+	} catch (error) {
+		ctx.context.logger.error("LogoutResponse validation failed", { error });
+		throw APIError.from(
+			"BAD_REQUEST",
+			SAML_ERROR_CODES.INVALID_LOGOUT_RESPONSE,
+		);
+	}
+
+	const extract = parsed?.extract as {
+		response?: { inResponseTo?: string };
+		status?: string;
+		statusCode?: string;
+	};
+
+	const statusCode =
+		extract?.statusCode ||
+		extract?.status ||
+		(parsed as any)?.samlContent?.status?.statusCode;
+	if (statusCode && statusCode !== constants.SAML_STATUS_SUCCESS) {
+		ctx.context.logger.warn("LogoutResponse indicates failure", { statusCode });
+		throw APIError.from("BAD_REQUEST", SAML_ERROR_CODES.LOGOUT_FAILED_AT_IDP);
+	}
+
+	const inResponseTo = extract?.response?.inResponseTo;
+	if (inResponseTo) {
+		const key = `${constants.LOGOUT_REQUEST_KEY_PREFIX}${inResponseTo}`;
+		const pendingRequest =
+			await ctx.context.internalAdapter.findVerificationValue(key);
+
+		if (!pendingRequest) {
+			ctx.context.logger.warn(
+				"LogoutResponse references unknown or expired request",
+				{ inResponseTo },
+			);
+		}
+
+		await ctx.context.internalAdapter
+			.deleteVerificationValue(key)
+			.catch((e: unknown) =>
+				ctx.context.logger.warn(
+					"Failed to delete logout request verification value",
+					e,
+				),
+			);
+	}
+
+	deleteSessionCookie(ctx);
+
+	const appOrigin = new URL(ctx.context.baseURL).origin;
+	const safeRedirectUrl = getSafeRedirectUrl(
+		relayState,
+		`${appOrigin}/sso/saml2/sp/slo/${providerId}`,
+		appOrigin,
+		(url, settings) => ctx.context.isTrustedOrigin(url, settings),
+	);
+	throw ctx.redirect(safeRedirectUrl);
+}
+
+async function handleLogoutRequest(
+	ctx: any,
+	sp: ReturnType<typeof createSP>,
+	idp: ReturnType<typeof createIdP>,
+	relayState: string | undefined,
+	providerId: string,
+) {
+	const binding =
+		ctx.method === "POST" && ctx.body?.SAMLRequest ? "post" : "redirect";
+
+	let parsed: Awaited<ReturnType<typeof sp.parseLogoutRequest>> | undefined;
+	try {
+		parsed = await sp.parseLogoutRequest(idp, binding, {
+			body: ctx.body,
+			query: ctx.query,
+		});
+	} catch (error) {
+		ctx.context.logger.error("LogoutRequest validation failed", { error });
+		throw APIError.from("BAD_REQUEST", SAML_ERROR_CODES.INVALID_LOGOUT_REQUEST);
+	}
+	if (!parsed?.extract) {
+		throw APIError.from("BAD_REQUEST", SAML_ERROR_CODES.INVALID_LOGOUT_REQUEST);
+	}
+
+	const { nameID } = parsed.extract;
+	const sessionIndex = (parsed.extract as SAMLAssertionExtract).sessionIndex;
+
+	const key = `${constants.SAML_SESSION_KEY_PREFIX}${providerId}:${nameID}`;
+	const stored = await ctx.context.internalAdapter.findVerificationValue(key);
+
+	if (stored) {
+		const data = safeJsonParse<SAMLSessionRecord>(stored.value);
+		if (data) {
+			if (
+				!sessionIndex ||
+				!data.sessionIndex ||
+				sessionIndex === data.sessionIndex
+			) {
+				await ctx.context.internalAdapter
+					.deleteSession(data.sessionId)
+					.catch((e: unknown) =>
+						ctx.context.logger.warn("Failed to delete session during SLO", {
+							error: e,
+						}),
+					);
+				await ctx.context.internalAdapter
+					.deleteVerificationValue(
+						`${constants.SAML_SESSION_BY_ID_PREFIX}${data.sessionId}`,
+					)
+					.catch((e: unknown) =>
+						ctx.context.logger.warn(
+							"Failed to delete SAML session lookup during SLO",
+							e,
+						),
+					);
+			} else {
+				ctx.context.logger.warn(
+					"SessionIndex mismatch in LogoutRequest - skipping session deletion",
+					{
+						providerId,
+						requestedSessionIndex: sessionIndex,
+						storedSessionIndex: data.sessionIndex,
+					},
+				);
+			}
+		}
+		await ctx.context.internalAdapter
+			.deleteVerificationValue(key)
+			.catch((e: unknown) =>
+				ctx.context.logger.warn(
+					"Failed to delete SAML session key during SLO",
+					e,
+				),
+			);
+	}
+
+	const currentSession = await getSessionFromCtx(ctx);
+	if (currentSession?.session) {
+		await ctx.context.internalAdapter.deleteSession(currentSession.session.id);
+	}
+
+	deleteSessionCookie(ctx);
+
+	const requestId = parsed.extract.request?.id || "";
+	const res = sp.createLogoutResponse(
+		idp,
+		null,
+		binding,
+		relayState || "",
+		(template: string) =>
+			template
+				.replace("{InResponseTo}", requestId)
+				.replace("{StatusCode}", constants.SAML_STATUS_SUCCESS),
+	) as { context: string; entityEndpoint?: string };
+
+	if (binding === "post" && res.entityEndpoint) {
+		return createSAMLPostForm(
+			res.entityEndpoint,
+			"SAMLResponse",
+			res.context,
+			relayState,
+		);
+	}
+	throw ctx.redirect(res.context);
+}
+
+export const initiateSLO = (options?: SSOOptions) => {
+	return createAuthEndpoint(
+		"/sso/saml2/logout/:providerId",
+		{
+			method: "POST",
+			body: z.object({
+				callbackURL: z.string().optional(),
+			}),
+			use: [sessionMiddleware],
+			metadata: HIDE_METADATA,
+		},
+		async (ctx) => {
+			if (!options?.saml?.enableSingleLogout) {
+				throw APIError.from(
+					"BAD_REQUEST",
+					SAML_ERROR_CODES.SINGLE_LOGOUT_NOT_ENABLED,
+				);
+			}
+
+			const { providerId } = ctx.params;
+			const callbackURL = ctx.body.callbackURL || ctx.context.baseURL;
+
+			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 as SAMLConfig;
+
+			const idpHasSLO =
+				config.idpMetadata?.singleLogoutService?.length ||
+				(config.idpMetadata?.metadata &&
+					config.idpMetadata.metadata.includes("SingleLogoutService"));
+			if (!idpHasSLO) {
+				throw APIError.from(
+					"BAD_REQUEST",
+					SAML_ERROR_CODES.IDP_SLO_NOT_SUPPORTED,
+				);
+			}
+
+			const sp = createSP(config, ctx.context.baseURL, providerId, {
+				wantLogoutRequestSigned: options?.saml?.wantLogoutRequestSigned,
+				wantLogoutResponseSigned: options?.saml?.wantLogoutResponseSigned,
+			});
+			const idp = createIdP(config);
+
+			const session = ctx.context.session;
+			const sessionLookupKey = `${constants.SAML_SESSION_BY_ID_PREFIX}${session.session.id}`;
+			const sessionLookup =
+				await ctx.context.internalAdapter.findVerificationValue(
+					sessionLookupKey,
+				);
+
+			let nameID = session.user.email;
+			let sessionIndex: string | undefined;
+			let samlSessionKey: string | undefined;
+
+			if (sessionLookup) {
+				samlSessionKey = sessionLookup.value;
+				const stored =
+					await ctx.context.internalAdapter.findVerificationValue(
+						samlSessionKey,
+					);
+				if (stored) {
+					const data = safeJsonParse<SAMLSessionRecord>(stored.value);
+					if (data) {
+						nameID = data.nameID || nameID;
+						sessionIndex = data.sessionIndex;
+					}
+				}
+			}
+
+			const logoutRequest = sp.createLogoutRequest(idp, "redirect", {
+				logoutNameID: nameID,
+				sessionIndex,
+				relayState: callbackURL,
+			}) as { id: string; context: string };
+
+			const ttl =
+				options?.saml?.logoutRequestTTL ??
+				constants.DEFAULT_LOGOUT_REQUEST_TTL_MS;
+			await ctx.context.internalAdapter.createVerificationValue({
+				identifier: `${constants.LOGOUT_REQUEST_KEY_PREFIX}${logoutRequest.id}`,
+				value: providerId,
+				expiresAt: new Date(Date.now() + ttl),
+			});
+
+			if (samlSessionKey) {
+				await ctx.context.internalAdapter
+					.deleteVerificationValue(samlSessionKey)
+					.catch((e) =>
+						ctx.context.logger.warn(
+							"Failed to delete SAML session key during logout",
+							e,
+						),
+					);
+			}
+			await ctx.context.internalAdapter
+				.deleteVerificationValue(sessionLookupKey)
+				.catch((e) =>
+					ctx.context.logger.warn(
+						"Failed to delete session lookup key during logout",
+						e,
+					),
+				);
+
+			await ctx.context.internalAdapter.deleteSession(session.session.id);
+
+			deleteSessionCookie(ctx);
+
+			throw ctx.redirect(logoutRequest.context);
+		},
+	);
+};