@better-auth/sso 1.4.0-beta.22 → 1.4.0-beta.24

package/src/routes/domain-verification.ts

@@ -0,0 +1,275 @@
+import type { Verification } from "better-auth";
+import {
+	APIError,
+	createAuthEndpoint,
+	sessionMiddleware,
+} from "better-auth/api";
+import { generateRandomString } from "better-auth/crypto";
+import * as z from "zod/v4";
+import type { SSOOptions, SSOProvider } from "../types";
+
+export const requestDomainVerification = (options: SSOOptions) => {
+	return createAuthEndpoint(
+		"/sso/request-domain-verification",
+		{
+			method: "POST",
+			body: z.object({
+				providerId: z.string(),
+			}),
+			metadata: {
+				openapi: {
+					summary: "Request a domain verification",
+					description:
+						"Request a domain verification for the given SSO provider",
+					responses: {
+						"404": {
+							description: "Provider not found",
+						},
+						"409": {
+							description: "Domain has already been verified",
+						},
+						"201": {
+							description: "Domain submitted for verification",
+						},
+					},
+				},
+			},
+			use: [sessionMiddleware],
+		},
+		async (ctx) => {
+			const body = ctx.body;
+			const provider = await ctx.context.adapter.findOne<
+				SSOProvider<SSOOptions>
+			>({
+				model: "ssoProvider",
+				where: [{ field: "providerId", value: body.providerId }],
+			});
+
+			if (!provider) {
+				throw new APIError("NOT_FOUND", {
+					message: "Provider not found",
+					code: "PROVIDER_NOT_FOUND",
+				});
+			}
+
+			const userId = ctx.context.session.user.id;
+			let isOrgMember = true;
+			if (provider.organizationId) {
+				const membershipsCount = await ctx.context.adapter.count({
+					model: "member",
+					where: [
+						{ field: "userId", value: userId },
+						{ field: "organizationId", value: provider.organizationId },
+					],
+				});
+
+				isOrgMember = membershipsCount > 0;
+			}
+
+			if (provider.userId !== userId || !isOrgMember) {
+				throw new APIError("FORBIDDEN", {
+					message:
+						"User must be owner of or belong to the SSO provider organization",
+					code: "INSUFICCIENT_ACCESS",
+				});
+			}
+
+			if ("domainVerified" in provider && provider.domainVerified) {
+				throw new APIError("CONFLICT", {
+					message: "Domain has already been verified",
+					code: "DOMAIN_VERIFIED",
+				});
+			}
+
+			const activeVerification =
+				await ctx.context.adapter.findOne<Verification>({
+					model: "verification",
+					where: [
+						{
+							field: "identifier",
+							value: options.domainVerification?.tokenPrefix
+								? `${options.domainVerification?.tokenPrefix}-${provider.providerId}`
+								: `better-auth-token-${provider.providerId}`,
+						},
+						{ field: "expiresAt", value: new Date(), operator: "gt" },
+					],
+				});
+
+			if (activeVerification) {
+				ctx.setStatus(201);
+				return ctx.json({ domainVerificationToken: activeVerification.value });
+			}
+
+			const domainVerificationToken = generateRandomString(24);
+			await ctx.context.adapter.create<Verification>({
+				model: "verification",
+				data: {
+					identifier: options.domainVerification?.tokenPrefix
+						? `${options.domainVerification?.tokenPrefix}-${provider.providerId}`
+						: `better-auth-token-${provider.providerId}`,
+					createdAt: new Date(),
+					updatedAt: new Date(),
+					value: domainVerificationToken,
+					expiresAt: new Date(Date.now() + 3600 * 24 * 7 * 1000), // 1 week
+				},
+			});
+
+			ctx.setStatus(201);
+			return ctx.json({
+				domainVerificationToken,
+			});
+		},
+	);
+};
+
+export const verifyDomain = (options: SSOOptions) => {
+	return createAuthEndpoint(
+		"/sso/verify-domain",
+		{
+			method: "POST",
+			body: z.object({
+				providerId: z.string(),
+			}),
+			metadata: {
+				openapi: {
+					summary: "Verify the provider domain ownership",
+					description: "Verify the provider domain ownership via DNS records",
+					responses: {
+						"404": {
+							description: "Provider not found",
+						},
+						"409": {
+							description:
+								"Domain has already been verified or no pending verification exists",
+						},
+						"502": {
+							description:
+								"Unable to verify domain ownership due to upstream validator error",
+						},
+						"204": {
+							description: "Domain ownership was verified",
+						},
+					},
+				},
+			},
+			use: [sessionMiddleware],
+		},
+		async (ctx) => {
+			const body = ctx.body;
+			const provider = await ctx.context.adapter.findOne<
+				SSOProvider<SSOOptions>
+			>({
+				model: "ssoProvider",
+				where: [{ field: "providerId", value: body.providerId }],
+			});
+
+			if (!provider) {
+				throw new APIError("NOT_FOUND", {
+					message: "Provider not found",
+					code: "PROVIDER_NOT_FOUND",
+				});
+			}
+
+			const userId = ctx.context.session.user.id;
+			let isOrgMember = true;
+			if (provider.organizationId) {
+				const membershipsCount = await ctx.context.adapter.count({
+					model: "member",
+					where: [
+						{ field: "userId", value: userId },
+						{ field: "organizationId", value: provider.organizationId },
+					],
+				});
+
+				isOrgMember = membershipsCount > 0;
+			}
+
+			if (provider.userId !== userId || !isOrgMember) {
+				throw new APIError("FORBIDDEN", {
+					message:
+						"User must be owner of or belong to the SSO provider organization",
+					code: "INSUFICCIENT_ACCESS",
+				});
+			}
+
+			if ("domainVerified" in provider && provider.domainVerified) {
+				throw new APIError("CONFLICT", {
+					message: "Domain has already been verified",
+					code: "DOMAIN_VERIFIED",
+				});
+			}
+
+			const activeVerification =
+				await ctx.context.adapter.findOne<Verification>({
+					model: "verification",
+					where: [
+						{
+							field: "identifier",
+							value: options.domainVerification?.tokenPrefix
+								? `${options.domainVerification?.tokenPrefix}-${provider.providerId}`
+								: `better-auth-token-${provider.providerId}`,
+						},
+						{ field: "expiresAt", value: new Date(), operator: "gt" },
+					],
+				});
+
+			if (!activeVerification) {
+				throw new APIError("NOT_FOUND", {
+					message: "No pending domain verification exists",
+					code: "NO_PENDING_VERIFICATION",
+				});
+			}
+
+			let records: string[] = [];
+			let dns: typeof import("node:dns/promises");
+
+			try {
+				dns = await import("node:dns/promises");
+			} catch (error) {
+				ctx.context.logger.error(
+					"The core node:dns module is required for the domain verification feature",
+					error,
+				);
+				throw new APIError("INTERNAL_SERVER_ERROR", {
+					message: "Unable to verify domain ownership due to server error",
+					code: "DOMAIN_VERIFICATION_FAILED",
+				});
+			}
+
+			try {
+				const dnsRecords = await dns.resolveTxt(
+					new URL(provider.domain).hostname,
+				);
+				records = dnsRecords.flat();
+			} catch (error) {
+				ctx.context.logger.warn(
+					"DNS resolution failure while validating domain ownership",
+					error,
+				);
+			}
+
+			const record = records.find((record) =>
+				record.includes(
+					`${activeVerification.identifier}=${activeVerification.value}`,
+				),
+			);
+			if (!record) {
+				throw new APIError("BAD_GATEWAY", {
+					message: "Unable to verify domain ownership. Try again later",
+					code: "DOMAIN_VERIFICATION_FAILED",
+				});
+			}
+
+			await ctx.context.adapter.update<SSOProvider<SSOOptions>>({
+				model: "ssoProvider",
+				where: [{ field: "providerId", value: provider.providerId }],
+				update: {
+					domainVerified: true,
+				},
+			});
+
+			ctx.setStatus(204);
+			return;
+		},
+	);
+};

package/src/routes/sso.ts

@@ -1,5 +1,5 @@
 import { BetterFetchError, betterFetch } from "@better-fetch/fetch";
-import type { Account, Session, User } from "better-auth";
+import type { Account, Session, User, Verification } from "better-auth";
 import {
 	createAuthorizationURL,
 	generateState,
@@ -13,6 +13,7 @@ import {
 	sessionMiddleware,
 } from "better-auth/api";
 import { setSessionCookie } from "better-auth/cookies";
+import { generateRandomString } from "better-auth/crypto";
 import { handleOAuthUserInfo } from "better-auth/oauth2";
 import { decodeJwt } from "jose";
 import * as saml from "samlify";
@@ -21,6 +22,7 @@ import type { IdentityProvider } from "samlify/types/src/entity-idp";
 import type { FlowResult } from "samlify/types/src/flow";
 import * as z from "zod/v4";
 import type { OIDCConfig, SAMLConfig, SSOOptions, SSOProvider } from "../types";
+import { validateEmailDomain } from "../utils";
 
 /**
  * Safely parses a value that might be a JSON string or already a parsed object
@@ -126,7 +128,7 @@ export const spMetadata = () => {
 	);
 };
 
-export const registerSSOProvider = (options?: SSOOptions) => {
+export const registerSSOProvider = <O extends SSOOptions>(options: O) => {
 	return createAuthEndpoint(
 		"/sso/register",
 		{
@@ -358,6 +360,16 @@ export const registerSSOProvider = (options?: SSOOptions) => {
 												description:
 													"The domain of the provider, used for email matching",
 											},
+											domainVerified: {
+												type: "boolean",
+												description:
+													"A boolean indicating whether the domain has been verified or not",
+											},
+											domainVerificationToken: {
+												type: "string",
+												description:
+													"Domain verification token. It can be used to prove ownership over the SSO domain",
+											},
 											oidcConfig: {
 												type: "object",
 												properties: {
@@ -586,12 +598,13 @@ export const registerSSOProvider = (options?: SSOOptions) => {
 
 			const provider = await ctx.context.adapter.create<
 				Record<string, any>,
-				SSOProvider
+				SSOProvider<O>
 			>({
 				model: "ssoProvider",
 				data: {
 					issuer: body.issuer,
 					domain: body.domain,
+					domainVerified: false,
 					oidcConfig: body.oidcConfig
 						? JSON.stringify({
 								issuer: body.issuer,
@@ -640,6 +653,34 @@ export const registerSSOProvider = (options?: SSOOptions) => {
 				},
 			});
 
+			let domainVerificationToken: string | undefined;
+			let domainVerified: boolean | undefined;
+
+			if (options?.domainVerification?.enabled) {
+				domainVerified = false;
+				domainVerificationToken = generateRandomString(24);
+
+				await ctx.context.adapter.create<Verification>({
+					model: "verification",
+					data: {
+						identifier: options.domainVerification?.tokenPrefix
+							? `${options.domainVerification?.tokenPrefix}-${provider.providerId}`
+							: `better-auth-token-${provider.providerId}`,
+						createdAt: new Date(),
+						updatedAt: new Date(),
+						value: domainVerificationToken,
+						expiresAt: new Date(Date.now() + 3600 * 24 * 7 * 1000), // 1 week
+					},
+				});
+			}
+
+			type SSOProviderReturn = O["domainVerification"] extends { enabled: true }
+				? {
+						domainVerified: boolean;
+						domainVerificationToken: string;
+					} & SSOProvider<O>
+				: SSOProvider<O>;
+
 			return ctx.json({
 				...provider,
 				oidcConfig: JSON.parse(
@@ -649,7 +690,11 @@ export const registerSSOProvider = (options?: SSOOptions) => {
 					provider.samlConfig as unknown as string,
 				) as SAMLConfig,
 				redirectURI: `${ctx.context.baseURL}/sso/callback/${provider.providerId}`,
-			});
+				...(options?.domainVerification?.enabled ? { domainVerified } : {}),
+				...(options?.domainVerification?.enabled
+					? { domainVerificationToken }
+					: {}),
+			} as unknown as SSOProviderReturn);
 		},
 	);
 };
@@ -840,7 +885,7 @@ export const signInSSO = (options?: SSOOptions) => {
 						return res.id;
 					});
 			}
-			let provider: SSOProvider | null = null;
+			let provider: SSOProvider<SSOOptions> | null = null;
 			if (options?.defaultSSO?.length) {
 				// Find matching default SSO provider by providerId
 				const matchingDefault = providerId
@@ -862,7 +907,10 @@ export const signInSSO = (options?: SSOOptions) => {
 						oidcConfig: matchingDefault.oidcConfig,
 						samlConfig: matchingDefault.samlConfig,
 						domain: matchingDefault.domain,
-					};
+						...(options.domainVerification?.enabled
+							? { domainVerified: true }
+							: {}),
+					} as SSOProvider<SSOOptions>;
 				}
 			}
 			if (!providerId && !orgId && !domain) {
@@ -873,7 +921,7 @@ export const signInSSO = (options?: SSOOptions) => {
 			// Try to find provider in database
 			if (!provider) {
 				provider = await ctx.context.adapter
-					.findOne<SSOProvider>({
+					.findOne<SSOProvider<SSOOptions>>({
 						model: "ssoProvider",
 						where: [
 							{
@@ -925,6 +973,15 @@ export const signInSSO = (options?: SSOOptions) => {
 				}
 			}
 
+			if (
+				options?.domainVerification?.enabled &&
+				!("domainVerified" in provider && provider.domainVerified)
+			) {
+				throw new APIError("UNAUTHORIZED", {
+					message: "Provider domain has not been verified",
+				});
+			}
+
 			if (provider.oidcConfig && body.providerType !== "saml") {
 				let finalAuthUrl = provider.oidcConfig.authorizationEndpoint;
 				if (!finalAuthUrl && provider.oidcConfig.discoveryEndpoint) {
@@ -1028,6 +1085,10 @@ export const callbackSSO = (options?: SSOOptions) => {
 				error: z.string().optional(),
 				error_description: z.string().optional(),
 			}),
+			allowedMediaTypes: [
+				"application/x-www-form-urlencoded",
+				"application/json",
+			],
 			metadata: {
 				isAction: false,
 				openapi: {
@@ -1060,7 +1121,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 					}?error=${error}&error_description=${error_description}`,
 				);
 			}
-			let provider: SSOProvider | null = null;
+			let provider: SSOProvider<SSOOptions> | null = null;
 			if (options?.defaultSSO?.length) {
 				const matchingDefault = options.defaultSSO.find(
 					(defaultProvider) =>
@@ -1071,7 +1132,10 @@ export const callbackSSO = (options?: SSOOptions) => {
 						...matchingDefault,
 						issuer: matchingDefault.oidcConfig?.issuer || "",
 						userId: "default",
-					};
+						...(options.domainVerification?.enabled
+							? { domainVerified: true }
+							: {}),
+					} as SSOProvider<SSOOptions>;
 				}
 			}
 			if (!provider) {
@@ -1095,7 +1159,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 							...res,
 							oidcConfig:
 								safeJsonParse<OIDCConfig>(res.oidcConfig) || undefined,
-						} as SSOProvider;
+						} as SSOProvider<SSOOptions>;
 					});
 			}
 			if (!provider) {
@@ -1106,6 +1170,15 @@ export const callbackSSO = (options?: SSOOptions) => {
 				);
 			}
 
+			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) {
@@ -1401,7 +1474,7 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 		async (ctx) => {
 			const { SAMLResponse, RelayState } = ctx.body;
 			const { providerId } = ctx.params;
-			let provider: SSOProvider | null = null;
+			let provider: SSOProvider<SSOOptions> | null = null;
 			if (options?.defaultSSO?.length) {
 				const matchingDefault = options.defaultSSO.find(
 					(defaultProvider) => defaultProvider.providerId === providerId,
@@ -1411,12 +1484,15 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 						...matchingDefault,
 						userId: "default",
 						issuer: matchingDefault.samlConfig?.issuer || "",
-					};
+						...(options.domainVerification?.enabled
+							? { domainVerified: true }
+							: {}),
+					} as SSOProvider<SSOOptions>;
 				}
 			}
 			if (!provider) {
 				provider = await ctx.context.adapter
-					.findOne<SSOProvider>({
+					.findOne<SSOProvider<SSOOptions>>({
 						model: "ssoProvider",
 						where: [{ field: "providerId", value: providerId }],
 					})
@@ -1439,6 +1515,15 @@ export const callbackSSOSAML = (options?: SSOOptions) => {
 				});
 			}
 
+			if (
+				options?.domainVerification?.enabled &&
+				!("domainVerified" in provider && provider.domainVerified)
+			) {
+				throw new APIError("UNAUTHORIZED", {
+					message: "Provider domain has not been verified",
+				});
+			}
+
 			const parsedSamlConfig = safeJsonParse<SAMLConfig>(
 				provider.samlConfig as unknown as string,
 			);
@@ -1713,6 +1798,10 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			}),
 			metadata: {
 				isAction: false,
+				allowedMediaTypes: [
+					"application/x-www-form-urlencoded",
+					"application/json",
+				],
 				openapi: {
 					operationId: "handleSAMLAssertionConsumerService",
 					summary: "SAML Assertion Consumer Service",
@@ -1732,7 +1821,7 @@ export const acsEndpoint = (options?: SSOOptions) => {
 			const { providerId } = ctx.params;
 
 			// If defaultSSO is configured, use it as the provider
-			let provider: SSOProvider | null = null;
+			let provider: SSOProvider<SSOOptions> | null = null;
 
 			if (options?.defaultSSO?.length) {
 				// For ACS endpoint, we can use the first default provider or try to match by providerId
@@ -1749,11 +1838,14 @@ export const acsEndpoint = (options?: SSOOptions) => {
 						userId: "default",
 						samlConfig: matchingDefault.samlConfig,
 						domain: matchingDefault.domain,
+						...(options.domainVerification?.enabled
+							? { domainVerified: true }
+							: {}),
 					};
 				}
 			} else {
 				provider = await ctx.context.adapter
-					.findOne<SSOProvider>({
+					.findOne<SSOProvider<SSOOptions>>({
 						model: "ssoProvider",
 						where: [
 							{
@@ -1781,6 +1873,15 @@ export const acsEndpoint = (options?: SSOOptions) => {
 				});
 			}
 
+			if (
+				options?.domainVerification?.enabled &&
+				!("domainVerified" in provider && provider.domainVerified)
+			) {
+				throw new APIError("UNAUTHORIZED", {
+					message: "Provider domain has not been verified",
+				});
+			}
+
 			const parsedSamlConfig = provider.samlConfig;
 			// Configure SP and IdP
 			const sp = saml.ServiceProvider({
@@ -1954,7 +2055,10 @@ export const acsEndpoint = (options?: SSOOptions) => {
 					const isTrustedProvider =
 						ctx.context.options.account?.accountLinking?.trustedProviders?.includes(
 							provider.providerId,
-						);
+						) ||
+						("domainVerified" in provider &&
+							provider.domainVerified &&
+							validateEmailDomain(userInfo.email, provider.domain));
 					if (!isTrustedProvider) {
 						throw ctx.redirect(
 							`${parsedSamlConfig.callbackUrl}?error=account_not_found`,

package/src/types.ts

@@ -81,7 +81,7 @@ export interface SAMLConfig {
 	mapping?: SAMLMapping | undefined;
 }
 
-export type SSOProvider = {
+type BaseSSOProvider = {
 	issuer: string;
 	oidcConfig?: OIDCConfig | undefined;
 	samlConfig?: SAMLConfig | undefined;
@@ -91,6 +91,13 @@ export type SSOProvider = {
 	domain: string;
 };
 
+export type SSOProvider<O extends SSOOptions> =
+	O["domainVerification"] extends { enabled: true }
+		? {
+				domainVerified: boolean;
+			} & BaseSSOProvider
+		: BaseSSOProvider;
+
 export interface SSOOptions {
 	/**
 	 * custom function to provision a user when they sign in with an SSO provider.
@@ -112,7 +119,7 @@ export interface SSOOptions {
 				/**
 				 * The SSO provider
 				 */
-				provider: SSOProvider;
+				provider: SSOProvider<SSOOptions>;
 		  }) => Promise<void>)
 		| undefined;
 	/**
@@ -138,7 +145,7 @@ export interface SSOOptions {
 					/**
 					 * The SSO provider
 					 */
-					provider: SSOProvider;
+					provider: SSOProvider<SSOOptions>;
 				}) => Promise<"member" | "admin">;
 		  }
 		| undefined;
@@ -228,4 +235,22 @@ export interface SSOOptions {
 	 * @default false
 	 */
 	trustEmailVerified?: boolean | undefined;
+	/**
+	 * Enable domain verification on SSO providers
+	 *
+	 * When this option is enabled, new SSO providers will require the associated domain to be verified by the owner
+	 * prior to allowing sign-ins.
+	 */
+	domainVerification?: {
+		/**
+		 * Enables or disables the domain verification feature
+		 */
+		enabled?: boolean;
+		/**
+		 * Prefix used to generate the domain verification token
+		 *
+		 * @default "better-auth-token-"
+		 */
+		tokenPrefix?: string;
+	};
 }

package/src/utils.ts

@@ -0,0 +1,10 @@
+export const validateEmailDomain = (email: string, domain: string) => {
+	const emailDomain = email.split("@")[1]?.toLowerCase();
+	const providerDomain = domain.toLowerCase();
+	if (!emailDomain || !providerDomain) {
+		return false;
+	}
+	return (
+		emailDomain === providerDomain || emailDomain.endsWith(`.${providerDomain}`)
+	);
+};