@better-auth/sso 1.4.0-beta.21 → 1.4.0-beta.23

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,11 +1,9 @@
 import { BetterFetchError, betterFetch } from "@better-fetch/fetch";
+import type { Account, Session, User, Verification } from "better-auth";
 import {
-	type Account,
 	createAuthorizationURL,
 	generateState,
 	parseState,
-	type Session,
-	type User,
 	validateAuthorizationCode,
 	validateToken,
 } from "better-auth";
@@ -15,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";
@@ -23,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
@@ -128,7 +128,7 @@ export const spMetadata = () => {
 	);
 };
 
-export const registerSSOProvider = (options?: SSOOptions) => {
+export const registerSSOProvider = <O extends SSOOptions>(options: O) => {
 	return createAuthEndpoint(
 		"/sso/register",
 		{
@@ -360,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: {
@@ -588,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,
@@ -642,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(
@@ -651,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);
 		},
 	);
 };
@@ -842,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
@@ -864,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) {
@@ -875,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: [
 							{
@@ -927,7 +973,32 @@ 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) {
+					const discovery = await betterFetch<{
+						authorization_endpoint: string;
+					}>(provider.oidcConfig.discoveryEndpoint, {
+						method: "GET",
+					});
+					if (discovery.data) {
+						finalAuthUrl = discovery.data.authorization_endpoint;
+					}
+				}
+				if (!finalAuthUrl) {
+					throw new APIError("BAD_REQUEST", {
+						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 authorizationURL = await createAuthorizationURL({
@@ -949,7 +1020,7 @@ export const signInSSO = (options?: SSOOptions) => {
 							"offline_access",
 						],
 					loginHint: ctx.body.loginHint || email,
-					authorizationEndpoint: provider.oidcConfig.authorizationEndpoint!,
+					authorizationEndpoint: finalAuthUrl,
 				});
 				return ctx.json({
 					url: authorizationURL.toString(),
@@ -1014,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: {
@@ -1046,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) =>
@@ -1057,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) {
@@ -1081,7 +1159,7 @@ export const callbackSSO = (options?: SSOOptions) => {
 							...res,
 							oidcConfig:
 								safeJsonParse<OIDCConfig>(res.oidcConfig) || undefined,
-						} as SSOProvider;
+						} as SSOProvider<SSOOptions>;
 					});
 			}
 			if (!provider) {
@@ -1092,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) {
@@ -1387,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,
@@ -1397,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 }],
 					})
@@ -1425,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,
 			);
@@ -1718,7 +1817,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
@@ -1735,11 +1834,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: [
 							{
@@ -1767,6 +1869,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({
@@ -1940,7 +2051,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`,