diff --git a/docs/pages/advanced.mdx b/docs/pages/advanced.mdx
index 06ccaeb..e909d18 100644
--- a/docs/pages/advanced.mdx
+++ b/docs/pages/advanced.mdx
@@ -1,4 +1,5 @@
import { Aside } from "../components/Aside";
+import { Callout } from "nextra/components";
# Advanced: Details
@@ -34,12 +35,13 @@ Convex Auth follows this logic:
import GitHub from "@auth/core/providers/github";
import { convexAuth } from "@convex-dev/auth/server";
- export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
- providers: [
- Resend,
- GitHub({ allowDangerousEmailAccountLinking: false }),
- ],
- });
+ export const { auth, signIn, signOut, store, isAuthenticated } =
+ convexAuth({
+ providers: [
+ Resend,
+ GitHub({ allowDangerousEmailAccountLinking: false }),
+ ],
+ });
```
@@ -170,3 +172,28 @@ The session documents are created and deleted by Convex Auth.
For this reason if you're tying other documents to sessions, and you don't want
to lose information when the session expires, you should store both the session
ID and the user ID in your other document.
+
+## Custom callback and sign-in URLs
+
+For ease of configuration, Convex Auth defaults to using the builtin
+`CONVEX_SITE_URL` value in callback and sign-in URLs. For some OAuth providers
+(Google, for example) this can lead to something like
+`happy-animal-123.convex.site` showing up to users on the OAuth consent screen.
+
+If you're using a
+[custom domain](https://docs.convex.dev/production/hosting/custom#custom-domains)
+for your production Convex deployment, you can configure Convex Auth to use that
+domain for the sign-in and callback URLs.
+
+With your **Production** deployment selected in the Convex dashboard, navigate
+to **Settings -> Environment Variables**. Add a `CUSTOM_AUTH_SITE_URL`
+environment variable pointing to the custom domain you configured for the
+deployment. For example, if your custom HTTP Actions domain is
+`convex.example.com` then you'd set `CUSTOM_AUTH_SITE_URL` to
+`https://convex.example.com` (no trailing slash).
+
+
+ Make sure to update your OAuth provider config for your production deployment
+ with your new callback URL. Otherwise it will refuse to redirect users to your
+ application.
+
diff --git a/docs/pages/config/oauth/google.mdx b/docs/pages/config/oauth/google.mdx
index 75a73a5..0682551 100644
--- a/docs/pages/config/oauth/google.mdx
+++ b/docs/pages/config/oauth/google.mdx
@@ -87,6 +87,15 @@ https://fast-horse-123.convex.site/api/auth/callback/google
Click **CREATE**.
+
+ If you follow the steps above exactly, Google will render the text
+ `fast-horse-123.convex.site` in their OAuth consent screen. If you're signed
+ up for a Convex Pro account, you can configure Convex Auth in your production
+ deployment to show a [custom
+ domain](../../advanced#custom-callback-and-sign-in-urls) in that screen
+ instead.
+
+
### Set Convex environment variables for Google OAuth
Reopen the client configuration.
diff --git a/src/server/implementation/signIn.ts b/src/server/implementation/signIn.ts
index ae2ebdd..458e068 100644
--- a/src/server/implementation/signIn.ts
+++ b/src/server/implementation/signIn.ts
@@ -235,7 +235,7 @@ async function handleOAuthProvider(
};
}
const redirect = new URL(
- requireEnv("CONVEX_SITE_URL") + `/api/auth/signin/${provider.id}`,
+ (process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv("CONVEX_SITE_URL")) + `/api/auth/signin/${provider.id}`,
);
const verifier = await callVerifier(ctx);
redirect.searchParams.set("code", verifier);
diff --git a/src/server/oauth/convexAuth.ts b/src/server/oauth/convexAuth.ts
index 1bcb13f..f6166dd 100644
--- a/src/server/oauth/convexAuth.ts
+++ b/src/server/oauth/convexAuth.ts
@@ -10,7 +10,7 @@ import { OAuthConfig } from "@auth/core/providers/oauth.js";
// ConvexAuth: The logic for the callback URL is different from Auth.js
export function callbackUrl(providerId: string) {
- return requireEnv("CONVEX_SITE_URL") + "/api/auth/callback/" + providerId;
+ return (process.env.CUSTOM_AUTH_SITE_URL ?? requireEnv("CONVEX_SITE_URL")) + "/api/auth/callback/" + providerId;
}
// ConvexAuth: This is a ConvexAuth specific function that produces a string that the