@hammadj/better-auth-sso 1.5.0-beta.9

package/src/index.ts

@@ -0,0 +1,265 @@
+import type { BetterAuthPlugin } from "better-auth";
+import { createAuthMiddleware } from "better-auth/api";
+import { XMLValidator } from "fast-xml-parser";
+import * as saml from "samlify";
+import { assignOrganizationByDomain } from "./linking";
+import {
+	requestDomainVerification,
+	verifyDomain,
+} from "./routes/domain-verification";
+import {
+	deleteSSOProvider,
+	getSSOProvider,
+	listSSOProviders,
+	updateSSOProvider,
+} from "./routes/providers";
+import {
+	acsEndpoint,
+	callbackSSO,
+	callbackSSOSAML,
+	registerSSOProvider,
+	signInSSO,
+	spMetadata,
+} from "./routes/sso";
+
+export {
+	DEFAULT_CLOCK_SKEW_MS,
+	DEFAULT_MAX_SAML_METADATA_SIZE,
+	DEFAULT_MAX_SAML_RESPONSE_SIZE,
+} from "./constants";
+
+export {
+	type SAMLConditions,
+	type TimestampValidationOptions,
+	validateSAMLTimestamp,
+} from "./routes/sso";
+
+export {
+	type AlgorithmValidationOptions,
+	DataEncryptionAlgorithm,
+	type DeprecatedAlgorithmBehavior,
+	DigestAlgorithm,
+	KeyEncryptionAlgorithm,
+	SignatureAlgorithm,
+} from "./saml";
+
+import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "./types";
+
+export type { SAMLConfig, OIDCConfig, SSOOptions, SSOProvider };
+
+declare module "@better-auth/core" {
+	interface BetterAuthPluginRegistry<AuthOptions, Options> {
+		sso: {
+			creator: typeof sso;
+		};
+	}
+}
+
+export {
+	computeDiscoveryUrl,
+	type DiscoverOIDCConfigParams,
+	DiscoveryError,
+	type DiscoveryErrorCode,
+	discoverOIDCConfig,
+	fetchDiscoveryDocument,
+	type HydratedOIDCConfig,
+	needsRuntimeDiscovery,
+	normalizeDiscoveryUrls,
+	normalizeUrl,
+	type OIDCDiscoveryDocument,
+	REQUIRED_DISCOVERY_FIELDS,
+	type RequiredDiscoveryField,
+	selectTokenEndpointAuthMethod,
+	validateDiscoveryDocument,
+	validateDiscoveryUrl,
+} from "./oidc";
+
+const fastValidator = {
+	async validate(xml: string) {
+		const isValid = XMLValidator.validate(xml, {
+			allowBooleanAttributes: true,
+		});
+		if (isValid === true) return "SUCCESS_VALIDATE_XML";
+		throw "ERR_INVALID_XML";
+	},
+};
+
+saml.setSchemaValidator(fastValidator);
+
+type DomainVerificationEndpoints = {
+	requestDomainVerification: ReturnType<typeof requestDomainVerification>;
+	verifyDomain: ReturnType<typeof verifyDomain>;
+};
+
+type SSOEndpoints<O extends SSOOptions> = {
+	spMetadata: ReturnType<typeof spMetadata>;
+	registerSSOProvider: ReturnType<typeof registerSSOProvider<O>>;
+	signInSSO: ReturnType<typeof signInSSO>;
+	callbackSSO: ReturnType<typeof callbackSSO>;
+	callbackSSOSAML: ReturnType<typeof callbackSSOSAML>;
+	acsEndpoint: ReturnType<typeof acsEndpoint>;
+	listSSOProviders: ReturnType<typeof listSSOProviders>;
+	getSSOProvider: ReturnType<typeof getSSOProvider>;
+	updateSSOProvider: ReturnType<typeof updateSSOProvider>;
+	deleteSSOProvider: ReturnType<typeof deleteSSOProvider>;
+};
+
+export type SSOPlugin<O extends SSOOptions> = {
+	id: "sso";
+	endpoints: SSOEndpoints<O> &
+		(O extends { domainVerification: { enabled: true } }
+			? DomainVerificationEndpoints
+			: {});
+};
+
+/**
+ * SAML endpoint paths that should skip origin check validation.
+ * These endpoints receive POST requests from external Identity Providers,
+ * which won't have a matching Origin header.
+ */
+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)
+];
+
+export function sso<
+	O extends SSOOptions & {
+		domainVerification?: { enabled: true };
+	},
+>(
+	options?: O | undefined,
+): {
+	id: "sso";
+	endpoints: SSOEndpoints<O> & DomainVerificationEndpoints;
+	schema: NonNullable<BetterAuthPlugin["schema"]>;
+	options: O;
+};
+export function sso<O extends SSOOptions>(
+	options?: O | undefined,
+): {
+	id: "sso";
+	endpoints: SSOEndpoints<O>;
+};
+
+export function sso<O extends SSOOptions>(
+	options?: O | undefined,
+): BetterAuthPlugin {
+	const optionsWithStore = options as O;
+
+	let endpoints = {
+		spMetadata: spMetadata(),
+		registerSSOProvider: registerSSOProvider(optionsWithStore),
+		signInSSO: signInSSO(optionsWithStore),
+		callbackSSO: callbackSSO(optionsWithStore),
+		callbackSSOSAML: callbackSSOSAML(optionsWithStore),
+		acsEndpoint: acsEndpoint(optionsWithStore),
+		listSSOProviders: listSSOProviders(),
+		getSSOProvider: getSSOProvider(),
+		updateSSOProvider: updateSSOProvider(optionsWithStore),
+		deleteSSOProvider: deleteSSOProvider(),
+	};
+
+	if (options?.domainVerification?.enabled) {
+		const domainVerificationEndpoints = {
+			requestDomainVerification: requestDomainVerification(optionsWithStore),
+			verifyDomain: verifyDomain(optionsWithStore),
+		};
+
+		endpoints = {
+			...endpoints,
+			...domainVerificationEndpoints,
+		};
+	}
+
+	return {
+		id: "sso",
+		init(ctx) {
+			const existing = ctx.skipOriginCheck;
+			if (existing === true) {
+				return {};
+			}
+			const existingPaths = Array.isArray(existing) ? existing : [];
+			return {
+				context: {
+					skipOriginCheck: [...existingPaths, ...SAML_SKIP_ORIGIN_CHECK_PATHS],
+				},
+			};
+		},
+		endpoints,
+		hooks: {
+			after: [
+				{
+					matcher(context) {
+						return context.path?.startsWith("/callback/") ?? false;
+					},
+					handler: createAuthMiddleware(async (ctx) => {
+						const newSession = ctx.context.newSession;
+						if (!newSession?.user) {
+							return;
+						}
+
+						if (!ctx.context.hasPlugin("organization")) {
+							return;
+						}
+
+						await assignOrganizationByDomain(ctx, {
+							user: newSession.user,
+							provisioningOptions: options?.organizationProvisioning,
+							domainVerification: options?.domainVerification,
+						});
+					}),
+				},
+			],
+		},
+		schema: {
+			ssoProvider: {
+				modelName: options?.modelName ?? "ssoProvider",
+				fields: {
+					issuer: {
+						type: "string",
+						required: true,
+						fieldName: options?.fields?.issuer ?? "issuer",
+					},
+					oidcConfig: {
+						type: "string",
+						required: false,
+						fieldName: options?.fields?.oidcConfig ?? "oidcConfig",
+					},
+					samlConfig: {
+						type: "string",
+						required: false,
+						fieldName: options?.fields?.samlConfig ?? "samlConfig",
+					},
+					userId: {
+						type: "string",
+						references: {
+							model: "user",
+							field: "id",
+						},
+						fieldName: options?.fields?.userId ?? "userId",
+					},
+					providerId: {
+						type: "string",
+						required: true,
+						unique: true,
+						fieldName: options?.fields?.providerId ?? "providerId",
+					},
+					organizationId: {
+						type: "string",
+						required: false,
+						fieldName: options?.fields?.organizationId ?? "organizationId",
+					},
+					domain: {
+						type: "string",
+						required: true,
+						fieldName: options?.fields?.domain ?? "domain",
+					},
+					...(options?.domainVerification?.enabled
+						? { domainVerified: { type: "boolean", required: false } }
+						: {}),
+				},
+			},
+		},
+		options: options as NoInfer<O>,
+	} satisfies BetterAuthPlugin;
+}

package/src/linking/index.ts

@@ -0,0 +1,2 @@
+export * from "./org-assignment";
+export * from "./types";

package/src/linking/org-assignment.test.ts

@@ -0,0 +1,325 @@
+import type { GenericEndpointContext, User } from "better-auth";
+import { betterAuth } from "better-auth";
+import { memoryAdapter } from "better-auth/adapters/memory";
+import { organization } from "better-auth/plugins";
+import { describe, expect, it } from "vitest";
+import { sso } from "..";
+import { assignOrganizationByDomain } from "./org-assignment";
+
+describe("assignOrganizationByDomain", () => {
+	const createTestContext = () => {
+		const data = {
+			user: [] as User[],
+			session: [] as { id: string }[],
+			account: [] as { id: string }[],
+			ssoProvider: [] as {
+				id: string;
+				providerId: string;
+				issuer: string;
+				domain: string;
+				domainVerified: boolean;
+				organizationId: string | null;
+				userId: string;
+			}[],
+			member: [] as {
+				id: string;
+				organizationId: string;
+				userId: string;
+				role: string;
+				createdAt: Date;
+			}[],
+			organization: [] as {
+				id: string;
+				name: string;
+				slug: string;
+				createdAt: Date;
+			}[],
+		};
+
+		const memory = memoryAdapter(data);
+
+		const auth = betterAuth({
+			database: memory,
+			baseURL: "http://localhost:3000",
+			emailAndPassword: {
+				enabled: true,
+			},
+			plugins: [
+				sso({
+					domainVerification: {
+						enabled: true,
+					},
+				}),
+				organization(),
+			],
+		});
+
+		const createContext = async () => {
+			const context = await auth.$context;
+			return { context } as unknown as Partial<GenericEndpointContext>;
+		};
+
+		return { auth, data, createContext };
+	};
+
+	const createUser = (overrides: Partial<User> = {}): User => ({
+		id: "user-1",
+		email: "alice@example.com",
+		name: "Alice",
+		emailVerified: true,
+		createdAt: new Date(),
+		updatedAt: new Date(),
+		...overrides,
+	});
+
+	const createOrg = (
+		overrides: Partial<{ id: string; name: string; slug: string }> = {},
+	) => ({
+		id: "org-1",
+		name: "Test Org",
+		slug: "test-org",
+		createdAt: new Date(),
+		...overrides,
+	});
+
+	const createProvider = (
+		overrides: Partial<{
+			id: string;
+			providerId: string;
+			issuer: string;
+			domain: string;
+			domainVerified: boolean;
+			organizationId: string | null;
+			userId: string;
+		}> = {},
+	) => ({
+		id: "provider-1",
+		providerId: "test-provider",
+		issuer: "https://idp.example.com",
+		domain: "example.com",
+		domainVerified: false,
+		organizationId: "org-1" as string | null,
+		userId: "user-1",
+		...overrides,
+	});
+
+	it("should NOT assign user to org when provider domain is unverified", async () => {
+		const { data, createContext } = createTestContext();
+
+		data.organization.push(createOrg());
+		data.ssoProvider.push(createProvider({ domainVerified: false }));
+
+		const user = createUser();
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(0);
+	});
+
+	it("should assign user to org when provider domain is verified", async () => {
+		const { data, createContext } = createTestContext();
+
+		const org = createOrg();
+		data.organization.push(org);
+		data.ssoProvider.push(
+			createProvider({ domainVerified: true, organizationId: org.id }),
+		);
+
+		const user = createUser();
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(1);
+		expect(members[0]?.organizationId).toBe(org.id);
+		expect(members[0]?.role).toBe("member");
+	});
+
+	it("should NOT assign user when email domain does not match any provider", async () => {
+		const { data, createContext } = createTestContext();
+
+		data.organization.push(createOrg());
+		data.ssoProvider.push(createProvider({ domainVerified: true }));
+
+		const user = createUser({ email: "alice@other-domain.com" });
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(0);
+	});
+
+	it("should NOT assign user when provider has no organizationId", async () => {
+		const { data, createContext } = createTestContext();
+
+		data.ssoProvider.push(
+			createProvider({ domainVerified: true, organizationId: null }),
+		);
+
+		const user = createUser();
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(0);
+	});
+
+	it("should NOT assign user when provider has no domainVerified field (verification enabled)", async () => {
+		const { data, createContext } = createTestContext();
+
+		const org = createOrg();
+		data.organization.push(org);
+
+		data.ssoProvider.push({
+			id: "provider-1",
+			providerId: "test-provider",
+			issuer: "https://idp.example.com",
+			domain: "example.com",
+			organizationId: org.id,
+			userId: "user-1",
+		} as {
+			id: string;
+			providerId: string;
+			issuer: string;
+			domain: string;
+			domainVerified: boolean;
+			organizationId: string | null;
+			userId: string;
+		});
+
+		const user = createUser();
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(0);
+	});
+
+	it("should assign user when verification is disabled (no domainVerified check)", async () => {
+		const { data, createContext } = createTestContext();
+
+		const org = createOrg();
+		data.organization.push(org);
+		data.ssoProvider.push(
+			createProvider({ domainVerified: false, organizationId: org.id }),
+		);
+
+		const user = createUser();
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: false },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(1);
+		expect(members[0]?.organizationId).toBe(org.id);
+	});
+
+	it("should NOT assign user when already a member of the org", async () => {
+		const { data, createContext } = createTestContext();
+
+		const org = createOrg();
+		data.organization.push(org);
+		data.ssoProvider.push(
+			createProvider({ domainVerified: true, organizationId: org.id }),
+		);
+
+		const user = createUser();
+		data.user.push(user);
+
+		data.member.push({
+			id: "member-1",
+			organizationId: org.id,
+			userId: user.id,
+			role: "admin",
+			createdAt: new Date(),
+		});
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(1);
+		expect(members[0]?.role).toBe("admin");
+	});
+
+	it("should only find verified provider when multiple providers claim same domain", async () => {
+		const { data, createContext } = createTestContext();
+
+		const legitOrg = createOrg({
+			id: "legit-org",
+			name: "Legit Org",
+			slug: "legit-org",
+		});
+		const attackerOrg = createOrg({
+			id: "attacker-org",
+			name: "Attacker Org",
+			slug: "attacker-org",
+		});
+		data.organization.push(legitOrg, attackerOrg);
+
+		data.ssoProvider.push(
+			createProvider({
+				id: "attacker-provider",
+				providerId: "attacker-provider",
+				issuer: "https://attacker.com",
+				domainVerified: false,
+				organizationId: attackerOrg.id,
+			}),
+		);
+
+		data.ssoProvider.push(
+			createProvider({
+				id: "legit-provider",
+				providerId: "legit-provider",
+				domainVerified: true,
+				organizationId: legitOrg.id,
+			}),
+		);
+
+		const user = createUser();
+		data.user.push(user);
+
+		const ctx = (await createContext()) as GenericEndpointContext;
+		await assignOrganizationByDomain(ctx, {
+			user,
+			domainVerification: { enabled: true },
+		});
+
+		const members = data.member.filter((m) => m.userId === user.id);
+		expect(members).toHaveLength(1);
+		expect(members[0]?.organizationId).toBe(legitOrg.id);
+	});
+});