feat(auth): auto-join org by google sso email domain

Let enterprise org admins configure an email domain so users signing in
with a Google account on that domain auto-join the org as a developer.

- schema: organization.ssoAutoJoinDomain + unique index
- api: PATCH /orgs guards (enterprise + owner/admin), domain validation,
  409 on duplicate domain, audit logging
- auth hook: auto-join on verified Google sign-in before default-org
  creation; runs for new and existing users, idempotent per membership
- email: notify the joined user via a transactional email
- ui: org SSO auto-join settings card on the Team page (enterprise gated)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: steebchen

apps/api/src/auth/config.ts

@@ -14,6 +14,7 @@ import { validateEmail } from "@/utils/email-validation.js";
 import { sendTransactionalEmail } from "@/utils/email.js";
 import { resolveSignupName } from "@/utils/infer-name.js";
 import { getOrCreatePersonalOrg } from "@/utils/personal-org.js";
+import { autoJoinByEmailDomain } from "@/utils/sso-domain.js";
 
 import { logAuditEvent } from "@llmgateway/audit";
 import { db, eq, tables } from "@llmgateway/db";
@@ -1131,13 +1132,40 @@ The LLM Gateway Team`.trim();
 					const activeOrganizations = userOrganizations.filter(
 						(uo) => uo.organization?.status !== "deleted",
 					);
-					const hasActiveDashboardOrganization = activeOrganizations.some(
+					const hadActiveDashboardOrganization = activeOrganizations.some(
 						(uo) => uo.organization?.kind === "default",
 					);
 					const hasActivePersonalOrganization = activeOrganizations.some(
 						(uo) => uo.organization?.kind === "devpass",
 					);
 
+					// Google SSO domain auto-join: if this user has a Google account and
+					// their verified email domain matches an enterprise org's configured
+					// SSO domain, add them to that org as a developer. A successful join
+					// gives them an active dashboard org, so the default-org creation below
+					// is skipped (no redundant personal "Default Organization"). Existing
+					// members are a no-op. Never fatal to login.
+					let autoJoinedOrgId: string | null = null;
+					if (newSession.user.emailVerified && dbUser?.email) {
+						const googleAccount = await db.query.account.findFirst({
+							where: {
+								userId: { eq: userId },
+								providerId: { eq: "google" },
+							},
+						});
+						if (googleAccount) {
+							try {
+								autoJoinedOrgId = await autoJoinByEmailDomain({
+									userId,
+									email: dbUser.email,
+									name: dbUser.name,
+								});
+							} catch (error) {
+								logger.error("SSO auto-join failed", error);
+							}
+						}
+					}
+
 					// DevPass (code app) signups get a personal organization instead of
 					// the shared "Default Organization" used by the main LLM Gateway
 					// dashboard. For social sign-in the request hits the OAuth callback
@@ -1154,29 +1182,33 @@ The LLM Gateway Team`.trim();
 						});
 						if (
 							hasActivePersonalOrganization ||
-							hasActiveDashboardOrganization
+							hadActiveDashboardOrganization
 						) {
 							return;
 						}
-					} else if (hasActiveDashboardOrganization) {
+					} else if (hadActiveDashboardOrganization) {
 						return;
 					} else {
-						const cookieHeader = ctx.request?.headers.get("cookie") ?? "";
-						const referralMatch = cookieHeader.match(
-							/llmgateway_referral=([^;]+)/,
-						);
+						// A domain auto-join already gave the user an active dashboard org,
+						// so only create the fallback default org when they didn't join one.
+						if (!autoJoinedOrgId) {
+							const cookieHeader = ctx.request?.headers.get("cookie") ?? "";
+							const referralMatch = cookieHeader.match(
+								/llmgateway_referral=([^;]+)/,
+							);
 
-						await getOrCreateDefaultOrganization(
-							{
-								id: userId,
-								email: newSession.user.email,
-							},
-							{
-								referralOrganizationId: referralMatch
-									? decodeURIComponent(referralMatch[1])
-									: null,
-							},
-						);
+							await getOrCreateDefaultOrganization(
+								{
+									id: userId,
+									email: newSession.user.email,
+								},
+								{
+									referralOrganizationId: referralMatch
+										? decodeURIComponent(referralMatch[1])
+										: null,
+								},
+							);
+						}
 
 						if (activeOrganizations.length > 0) {
 							return;

apps/api/src/routes/organization.ts

@@ -13,6 +13,7 @@ import {
 	isInvoiceableTransaction,
 	isRefundTransaction,
 } from "@/utils/invoice.js";
+import { isConfigurableDomain, normalizeDomain } from "@/utils/sso-domain.js";
 
 import { logAuditEvent } from "@llmgateway/audit";
 import {
@@ -63,6 +64,7 @@ const organizationSchema = z.object({
 	apiKeyLimit: z.number().nullable(),
 	retentionLevel: z.enum(["retain", "none"]),
 	providerCompliancePolicy: providerCompliancePolicySchema.nullable(),
+	ssoAutoJoinDomain: z.string().nullable(),
 	status: z.enum(["active", "inactive", "deleted"]).nullable(),
 	autoTopUpEnabled: z.boolean(),
 	autoTopUpThreshold: z.string().nullable(),
@@ -138,6 +140,7 @@ const updateOrganizationSchema = z.object({
 	providerCompliancePolicy: providerCompliancePolicySchema
 		.nullable()
 		.optional(),
+	ssoAutoJoinDomain: z.string().max(253).nullable().optional(),
 	autoTopUpEnabled: z.boolean().optional(),
 	autoTopUpThreshold: z.number().min(5).optional(),
 	autoTopUpAmount: z
@@ -494,6 +497,7 @@ organization.openapi(updateOrganization, async (c) => {
 		billingNotes,
 		retentionLevel,
 		providerCompliancePolicy,
+		ssoAutoJoinDomain,
 		autoTopUpEnabled,
 		autoTopUpThreshold,
 		autoTopUpAmount,
@@ -559,6 +563,37 @@ organization.openapi(updateOrganization, async (c) => {
 		}
 	}
 
+	// Google SSO domain auto-join is an enterprise feature managed by owners and
+	// admins. The value is normalized and validated before storage.
+	let normalizedSsoDomain: string | null | undefined;
+	if (ssoAutoJoinDomain !== undefined) {
+		if (userOrganization.organization?.plan !== "enterprise") {
+			throw new HTTPException(403, {
+				message: "SSO auto-join requires an enterprise plan",
+			});
+		}
+		if (
+			userOrganization.role !== "owner" &&
+			userOrganization.role !== "admin"
+		) {
+			throw new HTTPException(403, {
+				message: "Only owners and admins can configure SSO auto-join",
+			});
+		}
+		if (ssoAutoJoinDomain === null || ssoAutoJoinDomain.trim() === "") {
+			normalizedSsoDomain = null;
+		} else {
+			const normalized = normalizeDomain(ssoAutoJoinDomain);
+			if (!isConfigurableDomain(normalized)) {
+				throw new HTTPException(400, {
+					message:
+						"Invalid or disallowed domain. Use a corporate domain like acme.com (consumer email domains are not allowed).",
+				});
+			}
+			normalizedSsoDomain = normalized;
+		}
+	}
+
 	const updateData: any = {};
 	if (name !== undefined) {
 		updateData.name = name;
@@ -584,6 +619,9 @@ organization.openapi(updateOrganization, async (c) => {
 	if (providerCompliancePolicy !== undefined) {
 		updateData.providerCompliancePolicy = providerCompliancePolicy;
 	}
+	if (normalizedSsoDomain !== undefined) {
+		updateData.ssoAutoJoinDomain = normalizedSsoDomain;
+	}
 	if (autoTopUpEnabled !== undefined) {
 		updateData.autoTopUpEnabled = autoTopUpEnabled;
 		if (autoTopUpEnabled && !userOrganization.organization?.autoTopUpEnabled) {
@@ -599,11 +637,24 @@ organization.openapi(updateOrganization, async (c) => {
 		updateData.autoTopUpAmount = autoTopUpAmount.toString();
 	}
 
-	const [updatedOrganization] = await db
-		.update(tables.organization)
-		.set(updateData)
-		.where(eq(tables.organization.id, id))
-		.returning();
+	let updatedOrganization;
+	try {
+		[updatedOrganization] = await db
+			.update(tables.organization)
+			.set(updateData)
+			.where(eq(tables.organization.id, id))
+			.returning();
+	} catch (err) {
+		const code =
+			(err as { code?: string; cause?: { code?: string } })?.code ??
+			(err as { cause?: { code?: string } })?.cause?.code;
+		if (code === "23505" && normalizedSsoDomain) {
+			throw new HTTPException(409, {
+				message: "This domain is already configured by another organization.",
+			});
+		}
+		throw err;
+	}
 
 	// Build changes metadata for audit log
 	const changes: Record<string, { old: unknown; new: unknown }> = {};
@@ -717,6 +768,27 @@ organization.openapi(updateOrganization, async (c) => {
 		});
 	}
 
+	if (
+		normalizedSsoDomain !== undefined &&
+		normalizedSsoDomain !== oldOrg.ssoAutoJoinDomain
+	) {
+		await logAuditEvent({
+			organizationId: id,
+			userId: user.id,
+			action: "organization.sso_auto_join.update",
+			resourceType: "organization",
+			resourceId: id,
+			metadata: {
+				changes: {
+					ssoAutoJoinDomain: {
+						old: oldOrg.ssoAutoJoinDomain,
+						new: normalizedSsoDomain,
+					},
+				},
+			},
+		});
+	}
+
 	return c.json({
 		message: "Organization updated successfully",
 		organization: updatedOrganization,

apps/api/src/utils/email.ts

@@ -283,6 +283,96 @@ export function generatePaymentFailureEmailHtml(
 	`.trim();
 }
 
+export function generateAutoJoinEmailHtml(
+	userName: string,
+	organizationName: string,
+	organizationId: string,
+): string {
+	const escapedOrgName = escapeHtml(organizationName);
+	const greetingName = userName.trim() ? escapeHtml(userName.trim()) : "there";
+	const uiUrl = process.env.UI_URL ?? "https://llmgateway.io";
+	const dashboardUrl = `${uiUrl}/dashboard/${encodeURIComponent(organizationId)}`;
+
+	return `
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<title>You've been added to ${escapedOrgName} - LLMGateway</title>
+	</head>
+	<body
+		style="margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: #ffffff;"
+	>
+		<table role="presentation" style="width: 100%; border-collapse: collapse;">
+			<tr>
+				<td align="center" style="padding: 40px 20px;">
+					<table role="presentation" style="max-width: 600px; width: 100%; border-collapse: collapse;">
+						<!-- Header -->
+						<tr>
+							<td
+								style="background-color: #000000; padding: 40px 30px; text-align: center; border-radius: 8px 8px 0 0;"
+							>
+								<h1 style="margin: 0; color: #ffffff; font-size: 28px; font-weight: 600;">Welcome to ${escapedOrgName}</h1>
+							</td>
+						</tr>
+
+						<!-- Main Content -->
+						<tr>
+							<td style="background-color: #f8f9fa; padding: 40px 30px; border-radius: 0 0 8px 8px;">
+								<p style="margin: 0 0 20px 0; font-size: 16px; line-height: 1.6; color: #333333;">
+									Hi ${greetingName},
+								</p>
+
+								<p style="margin: 0 0 20px 0; font-size: 16px; line-height: 1.6; color: #333333;">
+									You've been added to <strong>${escapedOrgName}</strong> on LLM Gateway because your
+									email domain matches the organization's single sign-on settings. You now have access
+									to its projects and shared resources.
+								</p>
+
+								<!-- CTA Button -->
+								<table role="presentation" style="width: 100%; border-collapse: collapse;">
+									<tr>
+										<td align="center" style="padding: 10px 0;">
+											<a
+												href="${dashboardUrl}"
+												style="display: inline-block; background-color: #000000; color: #ffffff; padding: 14px 40px; text-decoration: none; border-radius: 6px; font-weight: 500; font-size: 16px;"
+											>Open dashboard</a>
+										</td>
+									</tr>
+								</table>
+
+								<p style="margin: 30px 0 0 0; font-size: 14px; line-height: 1.6; color: #666666;">
+									If you don't think you should have access to this organization, please reply to this
+									email and we'll help sort it out.
+								</p>
+							</td>
+						</tr>
+
+						<!-- Footer -->
+						<tr>
+							<td
+								style="padding: 30px 40px; background-color: #f8f9fa; border-radius: 0 0 8px 8px; border-top: 1px solid #e9ecef;"
+							>
+								<p style="margin: 0 0 12px; color: #666666; font-size: 14px; line-height: 1.6;">
+									Need help? Check out our <a
+									href="https://docs.llmgateway.io" style="color: #000000; text-decoration: none;"
+								>documentation</a> or reply to this email for any questions.
+								</p>
+								<p style="margin: 0; color: #999999; font-size: 12px;">
+									© 2025 LLM Gateway. All rights reserved. This is a transactional email and it can't be unsubscribed from.
+								</p>
+							</td>
+						</tr>
+					</table>
+				</td>
+			</tr>
+		</table>
+	</body>
+</html>
+	`.trim();
+}
+
 export function generateDevPlanDuplicateCardEmailHtml(
 	organizationName: string,
 ): string {

apps/api/src/utils/sso-domain.spec.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	CONSUMER_EMAIL_DOMAINS,
+	extractEmailDomain,
+	isConfigurableDomain,
+	normalizeDomain,
+} from "./sso-domain.js";
+
+describe("normalizeDomain", () => {
+	it("lowercases, trims, and strips a leading @", () => {
+		expect(normalizeDomain("  @Acme.COM ")).toBe("acme.com");
+		expect(normalizeDomain("Example.io")).toBe("example.io");
+		expect(normalizeDomain("acme.com")).toBe("acme.com");
+	});
+});
+
+describe("extractEmailDomain", () => {
+	it("returns the lowercased domain after the last @", () => {
+		expect(extractEmailDomain("Jane.Doe@Acme.com")).toBe("acme.com");
+		expect(extractEmailDomain("weird@sub@corp.example.com")).toBe(
+			"corp.example.com",
+		);
+	});
+
+	it("returns null for malformed addresses", () => {
+		expect(extractEmailDomain("no-at-sign")).toBeNull();
+		expect(extractEmailDomain("@leading.com")).toBeNull();
+		expect(extractEmailDomain("trailing@")).toBeNull();
+		expect(extractEmailDomain("")).toBeNull();
+	});
+});
+
+describe("isConfigurableDomain", () => {
+	it("accepts well-formed corporate domains", () => {
+		expect(isConfigurableDomain("acme.com")).toBe(true);
+		expect(isConfigurableDomain("mail.corp.example.io")).toBe(true);
+	});
+
+	it("rejects consumer email providers", () => {
+		for (const consumer of CONSUMER_EMAIL_DOMAINS) {
+			expect(isConfigurableDomain(consumer)).toBe(false);
+		}
+	});
+
+	it("rejects malformed domains", () => {
+		expect(isConfigurableDomain("acme")).toBe(false);
+		expect(isConfigurableDomain("acme.")).toBe(false);
+		expect(isConfigurableDomain("@acme.com")).toBe(false);
+		expect(isConfigurableDomain("")).toBe(false);
+	});
+});