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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@better-auth/sso",
   "author": "Bereket Engida",
-  "version": "1.5.0-beta.13",
+  "version": "1.5.0-beta.16",
   "type": "module",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -62,19 +62,19 @@
   "devDependencies": {
     "@types/body-parser": "^1.19.6",
     "@types/express": "^5.0.6",
-    "better-call": "1.2.1",
+    "better-call": "1.3.2",
     "body-parser": "^2.2.2",
     "express": "^5.2.1",
     "oauth2-mock-server": "^8.2.1",
-    "tsdown": "^0.20.1",
-    "@better-auth/core": "1.5.0-beta.13",
-    "better-auth": "1.5.0-beta.13"
+    "tsdown": "^0.20.3",
+    "better-auth": "1.5.0-beta.16",
+    "@better-auth/core": "1.5.0-beta.16"
   },
   "peerDependencies": {
     "@better-auth/utils": "0.3.1",
-    "better-call": "1.2.1",
-    "@better-auth/core": "1.5.0-beta.13",
-    "better-auth": "1.5.0-beta.13"
+    "better-call": "1.3.2",
+    "@better-auth/core": "1.5.0-beta.16",
+    "better-auth": "1.5.0-beta.16"
   },
   "scripts": {
     "test": "vitest",

package/src/client.ts

@@ -23,7 +23,7 @@ export const ssoClient = <CO extends SSOClientOptions>(
 		}>,
 		pathMethods: {
 			"/sso/providers": "GET",
-			"/sso/providers/:providerId": "GET",
+			"/sso/get-provider": "GET",
 		},
 	} satisfies BetterAuthClientPlugin;
 };

package/src/constants.ts

@@ -14,6 +14,15 @@ export const AUTHN_REQUEST_KEY_PREFIX = "saml-authn-request:";
 /** Prefix for used Assertion IDs used in replay protection */
 export const USED_ASSERTION_KEY_PREFIX = "saml-used-assertion:";
 
+/** Prefix for SAML session data (NameID + SessionIndex) for SLO */
+export const SAML_SESSION_KEY_PREFIX = "saml-session:";
+
+/** Prefix for reverse lookup of SAML session by Better Auth session ID */
+export const SAML_SESSION_BY_ID_PREFIX = "saml-session-by-id:";
+
+/** Prefix for LogoutRequest IDs used in SP-initiated SLO validation */
+export const LOGOUT_REQUEST_KEY_PREFIX = "saml-logout-request:";
+
 // ============================================================================
 // Time-To-Live (TTL) Defaults
 // ============================================================================
@@ -30,6 +39,12 @@ export const DEFAULT_AUTHN_REQUEST_TTL_MS = 5 * 60 * 1000;
  */
 export const DEFAULT_ASSERTION_TTL_MS = 15 * 60 * 1000;
 
+/**
+ * Default TTL for LogoutRequest records (5 minutes).
+ * Should be sufficient for IdP to process and respond.
+ */
+export const DEFAULT_LOGOUT_REQUEST_TTL_MS = 5 * 60 * 1000;
+
 /**
  * Default clock skew tolerance (5 minutes).
  * Allows for minor time differences between IdP and SP servers.
@@ -56,3 +71,9 @@ export const DEFAULT_MAX_SAML_RESPONSE_SIZE = 256 * 1024;
  * Protects against oversized metadata documents.
  */
 export const DEFAULT_MAX_SAML_METADATA_SIZE = 100 * 1024;
+
+// ============================================================================
+// SAML Status Codes
+// ============================================================================
+
+export const SAML_STATUS_SUCCESS = "urn:oasis:names:tc:SAML:2.0:status:Success";

package/src/domain-verification.test.ts

@@ -137,7 +137,6 @@ describe("Domain verification", async () => {
 	};
 
 	afterEach(() => {
-		vi.clearAllMocks();
 		vi.useRealTimers();
 	});
 
@@ -286,7 +285,7 @@ describe("Domain verification", async () => {
 
 			dnsMock.resolveTxt.mockResolvedValue([
 				[
-					`better-auth-token-saml-provider-1=${provider.domainVerificationToken}`,
+					`_better-auth-token-saml-provider-1=${provider.domainVerificationToken}`,
 				],
 			]);
 
@@ -471,7 +470,7 @@ describe("Domain verification", async () => {
 					"v=spf1 ip4:50.242.118.232/29 include:_spf.google.com include:mail.zendesk.com ~all",
 				],
 				[
-					`better-auth-token-saml-provider-1=${provider.domainVerificationToken}`,
+					`_better-auth-token-saml-provider-1=${provider.domainVerificationToken}`,
 				],
 			]);
 
@@ -484,6 +483,9 @@ describe("Domain verification", async () => {
 			});
 
 			expect(response.status).toBe(204);
+			expect(dnsMock.resolveTxt).toHaveBeenCalledWith(
+				"_better-auth-token-saml-provider-1.hello.com",
+			);
 		});
 
 		it("should verify a provider domain ownership (custom token verification prefix)", async () => {
@@ -498,7 +500,7 @@ describe("Domain verification", async () => {
 				[
 					"v=spf1 ip4:50.242.118.232/29 include:_spf.google.com include:mail.zendesk.com ~all",
 				],
-				[`auth-prefix-saml-provider-1=${provider.domainVerificationToken}`],
+				[`_auth-prefix-saml-provider-1=${provider.domainVerificationToken}`],
 			]);
 
 			const response = await auth.api.verifyDomain({
@@ -510,6 +512,45 @@ describe("Domain verification", async () => {
 			});
 
 			expect(response.status).toBe(204);
+			expect(dnsMock.resolveTxt).toHaveBeenCalledWith(
+				"_auth-prefix-saml-provider-1.hello.com",
+			);
+		});
+
+		it("should return bad request when provider ID exceeds DNS label limit", async () => {
+			const longProviderId = "a".repeat(50);
+			const { auth, getAuthHeaders } = createTestAuth();
+			const headers = await getAuthHeaders(testUser);
+
+			await auth.api.registerSSOProvider({
+				body: {
+					providerId: longProviderId,
+					issuer: "http://hello.com:8081",
+					domain: "http://hello.com:8081",
+					samlConfig: {
+						entryPoint: "http://idp.com:",
+						cert: "the-cert",
+						callbackUrl: "http://hello.com:8081/api/sso/saml2/callback",
+						spMetadata: {},
+					},
+				},
+				headers,
+			});
+
+			const response = await auth.api.verifyDomain({
+				body: {
+					providerId: longProviderId,
+				},
+				headers,
+				asResponse: true,
+			});
+
+			expect(response.status).toBe(400);
+			expect(await response.json()).toEqual({
+				message:
+					"Verification identifier exceeds the DNS label limit of 63 characters",
+				code: "IDENTIFIER_TOO_LONG",
+			});
 		});
 
 		it("should fail to verify an already verified domain", async () => {
@@ -519,7 +560,7 @@ describe("Domain verification", async () => {
 
 			dnsMock.resolveTxt.mockResolvedValue([
 				[
-					`better-auth-token-saml-provider-1=${provider.domainVerificationToken}`,
+					`_better-auth-token-saml-provider-1=${provider.domainVerificationToken}`,
 				],
 			]);
 

package/src/index.ts

@@ -1,7 +1,8 @@
 import type { BetterAuthPlugin } from "better-auth";
-import { createAuthMiddleware } from "better-auth/api";
+import { createAuthMiddleware, getSessionFromCtx } from "better-auth/api";
 import { XMLValidator } from "fast-xml-parser";
 import * as saml from "samlify";
+import { SAML_SESSION_BY_ID_PREFIX } from "./constants";
 import { assignOrganizationByDomain } from "./linking";
 import {
 	requestDomainVerification,
@@ -17,8 +18,11 @@ import {
 	acsEndpoint,
 	callbackSSO,
 	callbackSSOSAML,
+	callbackSSOShared,
+	initiateSLO,
 	registerSSOProvider,
 	signInSSO,
+	sloEndpoint,
 	spMetadata,
 } from "./routes/sso";
 
@@ -96,8 +100,11 @@ type SSOEndpoints<O extends SSOOptions> = {
 	registerSSOProvider: ReturnType<typeof registerSSOProvider<O>>;
 	signInSSO: ReturnType<typeof signInSSO>;
 	callbackSSO: ReturnType<typeof callbackSSO>;
+	callbackSSOShared: ReturnType<typeof callbackSSOShared>;
 	callbackSSOSAML: ReturnType<typeof callbackSSOSAML>;
 	acsEndpoint: ReturnType<typeof acsEndpoint>;
+	sloEndpoint: ReturnType<typeof sloEndpoint>;
+	initiateSLO: ReturnType<typeof initiateSLO>;
 	listSSOProviders: ReturnType<typeof listSSOProviders>;
 	getSSOProvider: ReturnType<typeof getSSOProvider>;
 	updateSSOProvider: ReturnType<typeof updateSSOProvider>;
@@ -120,6 +127,7 @@ export type SSOPlugin<O extends SSOOptions> = {
 const SAML_SKIP_ORIGIN_CHECK_PATHS = [
 	"/sso/saml2/callback", // SP-initiated SSO callback (prefix matches /callback/:providerId)
 	"/sso/saml2/sp/acs", // IdP-initiated SSO ACS (prefix matches /sp/acs/:providerId)
+	"/sso/saml2/sp/slo", // IdP-initiated SLO (prefix matches /sp/slo/:providerId)
 ];
 
 export function sso<
@@ -139,6 +147,7 @@ export function sso<O extends SSOOptions>(
 ): {
 	id: "sso";
 	endpoints: SSOEndpoints<O>;
+	options: O;
 };
 
 export function sso<O extends SSOOptions>(
@@ -147,12 +156,15 @@ export function sso<O extends SSOOptions>(
 	const optionsWithStore = options as O;
 
 	let endpoints = {
-		spMetadata: spMetadata(),
+		spMetadata: spMetadata(optionsWithStore),
 		registerSSOProvider: registerSSOProvider(optionsWithStore),
 		signInSSO: signInSSO(optionsWithStore),
 		callbackSSO: callbackSSO(optionsWithStore),
+		callbackSSOShared: callbackSSOShared(optionsWithStore),
 		callbackSSOSAML: callbackSSOSAML(optionsWithStore),
 		acsEndpoint: acsEndpoint(optionsWithStore),
+		sloEndpoint: sloEndpoint(optionsWithStore),
+		initiateSLO: initiateSLO(optionsWithStore),
 		listSSOProviders: listSSOProviders(),
 		getSSOProvider: getSSOProvider(),
 		updateSSOProvider: updateSSOProvider(optionsWithStore),
@@ -187,6 +199,35 @@ export function sso<O extends SSOOptions>(
 		},
 		endpoints,
 		hooks: {
+			before: [
+				{
+					matcher(context) {
+						return context.path === "/sign-out";
+					},
+					handler: createAuthMiddleware(async (ctx) => {
+						if (!options?.saml?.enableSingleLogout) {
+							return;
+						}
+						const session = await getSessionFromCtx(ctx);
+						if (!session?.session?.id) {
+							return;
+						}
+						const sessionLookupKey = `${SAML_SESSION_BY_ID_PREFIX}${session.session.id}`;
+						const sessionLookup =
+							await ctx.context.internalAdapter.findVerificationValue(
+								sessionLookupKey,
+							);
+						if (sessionLookup?.value) {
+							await ctx.context.internalAdapter
+								.deleteVerificationValue(sessionLookup.value)
+								.catch(() => {});
+							await ctx.context.internalAdapter
+								.deleteVerificationValue(sessionLookupKey)
+								.catch(() => {});
+						}
+					}),
+				},
+			],
 			after: [
 				{
 					matcher(context) {

package/src/oidc/discovery.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
 	computeDiscoveryUrl,
 	discoverOIDCConfig,
@@ -560,7 +560,7 @@ describe("OIDC Discovery", () => {
 			);
 		});
 
-		it.each([
+		it.for([
 			[
 				"/oauth2/token",
 				"https://idp.example.com/base",
@@ -577,8 +577,11 @@ describe("OIDC Discovery", () => {
 				"issuer with trailing slash",
 			],
 			["//oauth2/token", "https://idp.example.com/base//", "multiple slashes"],
-		])("should resolve relative endpoint preserving issuer base path (%s, %s) - %s", (endpoint, issuer) => {
-			expect(normalizeUrl("url", endpoint, issuer)).toBe(
+		])("should resolve relative endpoint preserving issuer base path (%s, %s) - %s", ([
+			endpoint,
+			issuer,
+		]) => {
+			expect(normalizeUrl("url", endpoint!, issuer!)).toBe(
 				"https://idp.example.com/base/oauth2/token",
 			);
 		});
@@ -638,10 +641,6 @@ describe("OIDC Discovery", () => {
 	describe("fetchDiscoveryDocument", () => {
 		const mockBetterFetch = betterFetch as ReturnType<typeof vi.fn>;
 
-		beforeEach(() => {
-			vi.clearAllMocks();
-		});
-
 		it("should fetch and parse valid discovery document", async () => {
 			const expectedDoc = createMockDiscoveryDocument();
 			mockBetterFetch.mockResolvedValueOnce({
@@ -794,10 +793,6 @@ describe("OIDC Discovery", () => {
 		const issuer = "https://idp.example.com";
 		const isTrustedOrigin = vi.fn().mockReturnValue(true);
 
-		beforeEach(() => {
-			vi.clearAllMocks();
-		});
-
 		it("should return hydrated config from valid discovery", async () => {
 			const discoveryDoc = createMockDiscoveryDocument({
 				issuer,

package/src/oidc.test.ts

@@ -3,7 +3,7 @@ import { createAuthClient } from "better-auth/client";
 import { organization } from "better-auth/plugins";
 import { getTestInstance } from "better-auth/test";
 import { OAuth2Server } from "oauth2-mock-server";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { sso } from ".";
 import { ssoClient } from "./client";
 
@@ -684,3 +684,304 @@ describe("provisioning", async (ctx) => {
 		expect(res.url).toContain("http://localhost:8080/authorize");
 	});
 });
+
+/**
+ * @see https://github.com/better-auth/better-auth/issues/7857
+ */
+describe("provisionUser should only be called for new users", async () => {
+	const provisionUserFn = vi.fn();
+	const { auth, signInWithTestUser, customFetchImpl, cookieSetter } =
+		await getTestInstance({
+			trustedOrigins: ["http://localhost:8080"],
+			plugins: [
+				sso({
+					provisionUser: provisionUserFn,
+				}),
+				organization(),
+			],
+		});
+
+	const authClient = createAuthClient({
+		plugins: [ssoClient()],
+		baseURL: "http://localhost:3000",
+		fetchOptions: {
+			customFetchImpl,
+		},
+	});
+
+	beforeAll(async () => {
+		await server.issuer.keys.generate("RS256");
+		server.service.removeAllListeners("beforeUserinfo");
+		server.service.removeAllListeners("beforeTokenSigning");
+		server.service.on("beforeUserinfo", (userInfoResponse) => {
+			userInfoResponse.body = {
+				email: "provision-test@localhost.com",
+				name: "Provision Test",
+				sub: "provision-test-sub",
+				picture: "https://test.com/picture.png",
+				email_verified: true,
+			};
+			userInfoResponse.statusCode = 200;
+		});
+		server.service.on("beforeTokenSigning", (token) => {
+			token.payload.email = "provision-test@localhost.com";
+			token.payload.email_verified = true;
+			token.payload.name = "Provision Test";
+			token.payload.picture = "https://test.com/picture.png";
+		});
+		await server.start(8080, "localhost");
+	});
+
+	afterAll(async () => {
+		await server.stop();
+	});
+
+	async function simulateOAuthFlow(authUrl: string, headers: Headers) {
+		let location: string | null = null;
+		await betterFetch(authUrl, {
+			method: "GET",
+			redirect: "manual",
+			onError(context) {
+				location = context.response.headers.get("location");
+			},
+		});
+
+		if (!location) throw new Error("No redirect location found");
+
+		let callbackURL = "";
+		const newHeaders = new Headers();
+		await betterFetch(location, {
+			method: "GET",
+			customFetchImpl,
+			headers,
+			onError(context) {
+				callbackURL = context.response.headers.get("location") || "";
+				cookieSetter(newHeaders)(context);
+			},
+		});
+
+		return { callbackURL, headers: newHeaders };
+	}
+
+	it("should call provisionUser only on first sign-in (new user), not on subsequent sign-ins", async () => {
+		const { headers } = await signInWithTestUser();
+		await auth.api.registerSSOProvider({
+			body: {
+				issuer: server.issuer.url!,
+				domain: "localhost.com",
+				oidcConfig: {
+					clientId: "test",
+					clientSecret: "test",
+					authorizationEndpoint: `${server.issuer.url}/authorize`,
+					tokenEndpoint: `${server.issuer.url}/token`,
+					jwksEndpoint: `${server.issuer.url}/jwks`,
+					discoveryEndpoint: `${server.issuer.url}/.well-known/openid-configuration`,
+					mapping: {
+						id: "sub",
+						email: "email",
+						emailVerified: "email_verified",
+						name: "name",
+						image: "picture",
+					},
+				},
+				providerId: "provision-test",
+			},
+			headers,
+		});
+
+		provisionUserFn.mockClear();
+
+		// First sign-in: new user -> provisionUser should be called
+		const signInHeaders1 = new Headers();
+		const res1 = await authClient.signIn.sso({
+			email: "user@localhost.com",
+			callbackURL: "/dashboard",
+			fetchOptions: {
+				throw: true,
+				onSuccess: cookieSetter(signInHeaders1),
+			},
+		});
+		await simulateOAuthFlow(res1.url, signInHeaders1);
+		expect(provisionUserFn).toHaveBeenCalledTimes(1);
+
+		provisionUserFn.mockClear();
+
+		// Second sign-in: existing user -> provisionUser should NOT be called
+		const signInHeaders2 = new Headers();
+		const res2 = await authClient.signIn.sso({
+			email: "user@localhost.com",
+			callbackURL: "/dashboard",
+			fetchOptions: {
+				throw: true,
+				onSuccess: cookieSetter(signInHeaders2),
+			},
+		});
+		await simulateOAuthFlow(res2.url, signInHeaders2);
+		expect(provisionUserFn).toHaveBeenCalledTimes(0);
+	});
+});
+
+/**
+ * @see https://github.com/better-auth/better-auth/issues/7693
+ */
+describe("SSO shared redirectURI", async () => {
+	const { auth, signInWithTestUser, customFetchImpl, cookieSetter } =
+		await getTestInstance({
+			trustedOrigins: ["http://localhost:8080"],
+			plugins: [
+				sso({
+					redirectURI: "/sso/callback",
+				}),
+				organization(),
+			],
+		});
+
+	const authClient = createAuthClient({
+		plugins: [ssoClient()],
+		baseURL: "http://localhost:3000",
+		fetchOptions: {
+			customFetchImpl,
+		},
+	});
+
+	const userinfoHandler = (userInfoResponse: any) => {
+		userInfoResponse.body = {
+			email: "shared-redirect@test.com",
+			name: "Shared Redirect User",
+			sub: "shared-redirect-user",
+			picture: "https://test.com/shared.png",
+			email_verified: true,
+		};
+		userInfoResponse.statusCode = 200;
+	};
+
+	const tokenHandler = (token: any) => {
+		token.payload.email = "shared-redirect@test.com";
+		token.payload.email_verified = true;
+		token.payload.name = "Shared Redirect User";
+		token.payload.picture = "https://test.com/shared.png";
+	};
+
+	beforeAll(async () => {
+		await server.issuer.keys.generate("RS256");
+		server.service.removeAllListeners("beforeUserinfo");
+		server.service.removeAllListeners("beforeTokenSigning");
+		server.service.on("beforeUserinfo", userinfoHandler);
+		server.service.on("beforeTokenSigning", tokenHandler);
+		await server.start(8080, "localhost");
+	});
+
+	afterAll(async () => {
+		server.service.removeListener("beforeUserinfo", userinfoHandler);
+		server.service.removeListener("beforeTokenSigning", tokenHandler);
+		await server.stop().catch(() => {});
+	});
+
+	async function simulateOAuthFlow(
+		authUrl: string,
+		headers: Headers,
+		fetchImpl?: (...args: any) => any,
+	) {
+		let location: string | null = null;
+		await betterFetch(authUrl, {
+			method: "GET",
+			redirect: "manual",
+			onError(context) {
+				location = context.response.headers.get("location");
+			},
+		});
+
+		if (!location) throw new Error("No redirect location found");
+		const newHeaders = new Headers();
+		let callbackURL = "";
+		await betterFetch(location, {
+			method: "GET",
+			customFetchImpl: fetchImpl || customFetchImpl,
+			headers,
+			onError(context) {
+				callbackURL = context.response.headers.get("location") || "";
+				cookieSetter(newHeaders)(context);
+			},
+		});
+
+		return { callbackURL, headers: newHeaders };
+	}
+
+	it("should return shared redirectURI when registering provider", async () => {
+		const { headers } = await signInWithTestUser();
+		const provider = await auth.api.registerSSOProvider({
+			body: {
+				issuer: server.issuer.url!,
+				domain: "shared-redirect.com",
+				oidcConfig: {
+					clientId: "shared-test",
+					clientSecret: "shared-test-secret",
+					authorizationEndpoint: `${server.issuer.url}/authorize`,
+					tokenEndpoint: `${server.issuer.url}/token`,
+					jwksEndpoint: `${server.issuer.url}/jwks`,
+					discoveryEndpoint: `${server.issuer.url}/.well-known/openid-configuration`,
+					mapping: {
+						id: "sub",
+						email: "email",
+						emailVerified: "email_verified",
+						name: "name",
+						image: "picture",
+					},
+				},
+				providerId: "shared-test",
+			},
+			headers,
+		});
+		// Should use the shared redirect URI, not per-provider
+		expect(provider.redirectURI).toBe(
+			"http://localhost:3000/api/auth/sso/callback",
+		);
+		expect(provider.redirectURI).not.toContain("shared-test");
+	});
+
+	it("should use shared redirect URI in authorization URL", async () => {
+		const headers = new Headers();
+		const res = await authClient.signIn.sso({
+			email: "user@shared-redirect.com",
+			callbackURL: "/dashboard",
+			fetchOptions: {
+				throw: true,
+				onSuccess: cookieSetter(headers),
+			},
+		});
+		expect(res.url).toContain("http://localhost:8080/authorize");
+		// Should use shared redirect URI without providerId in path
+		expect(res.url).toContain(
+			"redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fauth%2Fsso%2Fcallback",
+		);
+		// Should NOT contain the per-provider path
+		expect(res.url).not.toContain(
+			"redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fauth%2Fsso%2Fcallback%2Fshared-test",
+		);
+	});
+
+	it("should complete OIDC flow using shared callback endpoint", async () => {
+		const headers = new Headers();
+		const res = await authClient.signIn.sso({
+			email: "user@shared-redirect.com",
+			callbackURL: "/dashboard",
+			fetchOptions: {
+				throw: true,
+				onSuccess: cookieSetter(headers),
+			},
+		});
+		const { callbackURL, headers: sessionHeaders } = await simulateOAuthFlow(
+			res.url,
+			headers,
+		);
+		expect(callbackURL).toContain("/dashboard");
+
+		// Verify session was created
+		const session = await authClient.getSession({
+			fetchOptions: {
+				headers: sessionHeaders,
+			},
+		});
+		expect(session.data?.user.email).toBe("shared-redirect@test.com");
+	});
+});