Preview authentication
Preview deployments receive changing hostnames and cannot each have a provider callback registered.
Better Auth · Const
oAuthProxy
OAuth Proxy lets trusted local and preview deployments use one OAuth client with a fixed production callback URL. It routes their OAuth flows through the production callback server.
How it works
oAuthProxy adds a routing layer for OAuth sign-ins from trusted previews and local development. The participating environment sends the flow through the production callback server, which uses the registered production OAuth callback and returns the result to the originating deployment.
Syntax
oAuthProxy({ productionURL, secret })Parameters
| Name | Type | Description |
|---|---|---|
productionURL | string | The URL of the production server that receives the provider callback. |
secret | string | A shared dedicated secret used by all trusted participating environments. |
Returns
Adds OAuth proxy routing to the Better Auth configuration; the page does not specify a separate return value.
Key points
- Use the plugin when local or preview callback URLs are dynamic and cannot conveniently be registered with the provider.
- A single OAuth client can support multiple non-production environments through the fixed production callback.
- Production completes the provider exchange and sends the resulting profile data back to the requesting environment.
- OAuth authorization requests from trusted non-production deployments are routed through production.
- Provider configuration does not require separate callback registrations for every preview deployment.
- After setup, routing from previews and local development to production is automatic.
Common mistakes
- Every participating environment must use the identical proxy secret.
- Register the provider callback on the production domain rather than each preview or local URL.
- The plugin must be installed wherever the proxy flow participates, not only on production.
Example: Configure OAuth Proxy
import { betterAuth } from "better-auth"
import { oAuthProxy } from "better-auth/plugins"
export const auth = betterAuth({
plugins: [
oAuthProxy({
productionURL: "https://my-production-app.com",
secret: process.env.OAUTH_PROXY_SECRET,
}),
],
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID || "",
clientSecret: process.env.GITHUB_CLIENT_SECRET || "",
},
},
})Configure the OAuth proxy identically on production and trusted preview or local environments, using one shared secret.
When to use it
Local development
A developer needs social sign-in locally without creating a separate OAuth application.
Shared OAuth client
One production OAuth client must serve several trusted environments.
Interview questions
QWhat problem does oAuthProxy solve?
oAuthProxy lets one OAuth client serve local development and preview deployments whose callback URLs are variable. The production server receives the provider callback, exchanges the authorization code, and returns encrypted profile data to the originating deployment.
Follow-up: How is the OAuth provider configured? Register only the production callback URL; the proxy routes preview and development requests through that callback.
QHow should the plugin be configured across environments?
Configure the plugin with the production callback server URL and a dedicated secret. Use the same configuration and secret on production, previews, and localhost.
Follow-up: Why must the secret match? The participating environments use it to communicate securely during the proxied flow.
QWhich callback URL should be registered with the provider?
The OAuth provider needs only the callback URL on the production domain. Preview and development callbacks are routed through production automatically by the plugin.
Follow-up: What deployment requirement follows? Only trusted environments should participate, and each must have the plugin installed and the shared secret configured.
Related
betterAuthsocialProviderstrustedOriginsOAuth