OAuth Proxy

OAuth Proxy is intended for local development and trusted preview deployments whose callback URLs change. It lets these deployments use an OAuth client with a fixed callback URL registered on your production server.

Your production server handles the provider callback, exchanges the authorization code, and returns encrypted profile data to the development or preview deployment. That deployment creates the user and session in its own database. Install the plugin on both the production callback server and each trusted development or preview deployment that participates in the flow.

For ordinary production sign-ins, use the normal OAuth provider flow. When the current origin matches productionURL, the plugin skips proxying the sign-in request. The production server still handles proxy callbacks for participating development and preview deployments.

Installation

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 || "",
    },
  },
})

https://my-production-app.com/api/auth/callback/github

export const auth = betterAuth({
  // ...other config
  trustedOrigins: [ 
    "http://localhost:3000", 
    "https://my-app-*-preview.example.com", 
  ], 
})

oAuthProxy({
  productionURL: "https://my-production-app.com",
  secret: process.env.OAUTH_PROXY_SECRET, // Same value on ALL environments
})

Upgrading existing deployments

The oAuthProxy configuration does not change. Keep the existing productionURL and shared secret. This upgrade does not require rotating the secret; any separate rotation must still keep every participating environment on the same value.

Upgrade production and every preview or development deployment that participates in the same OAuth proxy flow to the same Better Auth version in one coordinated cutover. Mixed versions cannot exchange proxy state packages or provider profiles. Sign-in and account-linking flows started before the cutover must be restarted, whether they use database-backed or cookie-backed OAuth state. When using cookie-backed state, upgrade every node that serves the same auth base together because the state cookie encryption key also changes. The plugin does not fall back to the previous shared encryption key.

How it works

The plugin allows you to use a single OAuth client (registered with your production URL) across multiple environments like preview deployments or local development.

1. Preview server initiates OAuth, redirecting to the OAuth provider with production's redirect URI
2. OAuth provider callbacks to production server
3. Production server exchanges the code for tokens and fetches user info
4. Production server encrypts the profile data and redirects to preview server (no database write on production)
5. Preview server decrypts the profile, creates user/session in its own database, and sets the session cookie

import { authClient } from "@/lib/auth-client"

await authClient.signIn.social({
    provider: "github",
    callbackURL: "/dashboard"
})

The encrypted profile data is passed via URL query parameters and can only be decrypted by servers sharing the same secret. This also allows preview deployments to use separate databases from production if needed.

Options

productionURL: The URL of the production server that handles provider callbacks for development and preview sign-ins. Sign-in requests are not proxied when the current origin matches this URL's origin. Defaults to the BETTER_AUTH_URL environment variable, then the auth baseURL.

currentURL: The application's current URL is automatically determined by the plugin. It first checks the request URL, then vendor-specific environment variables from popular hosting providers, and finally falls back to the baseURL in your auth config. You only need to set this if the URL isn't being inferred correctly in your environment.

maxAge: Maximum age in seconds for encrypted profile payloads. Payloads older than this will be rejected to prevent replay attacks. Keep this value short (e.g., 30-60 seconds) to minimize the window for potential replay attacks while still allowing normal OAuth flows. Defaults to 60 seconds.

secret: A dedicated secret used to derive keys for the OAuth proxy flow. When set, this is used instead of the global BETTER_AUTH_SECRET, so a leaked proxy secret cannot decrypt data protected only by the main secret. Holders of the proxy secret can assert provider identities to participating deployments and obtain sessions when those identities are accepted. Share it only with trusted environments and code. All environments participating in the proxy flow must share the same secret value.

Troubleshooting

state_mismatch or "State not persisted correctly" error

This error typically occurs when production and preview environments have different secrets and no shared secret is configured in the plugin options.

What happens:

1. Preview encrypts the OAuth state with its secret
2. OAuth provider redirects to production
3. Production tries to decrypt with a different secret → fails
4. The regular OAuth callback runs and fails because the state cookie doesn't exist on production

Solution: Configure a shared secret in the oAuthProxy options on all environments:

oAuthProxy({
  productionURL: "https://my-production-app.com",
  secret: process.env.OAUTH_PROXY_SECRET, 
})

Make sure OAUTH_PROXY_SECRET has the same value on production and each trusted preview or localhost deployment participating in the flow. Keep it out of deployments running untrusted contributor code.

OAuth works on production but fails on preview/localhost

Ensure all of the following:

1. Shared secret is configured (see above)
2. Trusted origins include your preview/localhost URLs
3. Production callback URL is registered with your OAuth provider (e.g., https://production.com/api/auth/callback/github)