OAuth Providers

The starter kit comes with Google OAuth pre-configured, but you can easily add additional OAuth providers like Facebook, GitHub or any provider supported by Better Auth.

Plan OAuth URLs for Every Environment

OAuth providers compare the callback URL in each request with the URLs saved in their developer console. Register every environment where people will complete sign-in:

The kit derives Better Auth's baseURL from getBaseUrl() in lib/utils.ts. On Vercel, preview deployments use NEXT_PUBLIC_VERCEL_BRANCH_URL. Production uses NEXT_PUBLIC_SITE_URL when it is set, then falls back to Vercel's generated URL.

Google requires an exact registered callback URL. A new branch preview can have a new hostname, so arbitrary preview URLs are not a reliable place to test OAuth. Use a stable staging domain for repeatable pre-production testing or add the exact preview callback URL before testing that deployment.

Google OAuth (Pre-configured)

Google OAuth is already set up in the starter kit. To enable it:

1. Create Google OAuth Credentials

1. Visit the Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth client ID
5. Configure the OAuth consent screen if you haven't already
6. Select Web application as the application type
7. Add authorized JavaScript origins:
   • http://localhost:3000 (for development)
   • https://yourdomain.com (for production)
8. Add authorized redirect URIs:
   • http://localhost:3000/api/auth/callback/google (for development)
   • https://yourdomain.com/api/auth/callback/google (for production)
9. Copy the Client ID and Client Secret

2. Configure Environment Variables

Add the credentials to your .env file:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

3. Verify Configuration

The Google provider is already configured in lib/auth/index.ts:

socialProviders: {
  google: {
    prompt: "select_account",
    clientId: env.GOOGLE_CLIENT_ID ?? "",
    clientSecret: env.GOOGLE_CLIENT_SECRET ?? "",
    scope: ["email", "profile"],
  },
},

The sign-in and sign-up pages render providers from lib/auth/oauth-providers.tsx. Google is included there by default. If the credentials are not ready, set enableSocialLogin to false in config/auth.config.ts so users are not shown a button that cannot complete authentication.

4. Test Both Environments

1. Restart the development server after changing .env.
2. Sign in with a Google account and confirm the callback returns to /dashboard.
3. Confirm a first-time Google user is created and an existing user follows the account-linking behavior you intend.
4. Repeat the flow on the final HTTPS production domain. Preview and production deployments need callback URLs accepted by the provider before they can complete OAuth.

Adding Additional OAuth Providers

To add a new OAuth provider (e.g., Facebook, GitHub), follow these steps:

1. Get Provider Credentials

Create an application with your chosen OAuth provider and obtain the Client ID and Client Secret.

2. Add Environment Variables

Add the provider credentials to your .env file:

FACEBOOK_CLIENT_ID=your-facebook-client-id
FACEBOOK_CLIENT_SECRET=your-facebook-client-secret

3. Update Auth Configuration

Add the provider to lib/auth/index.ts:

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
  // ... other config
  account: {
    accountLinking: {
      enabled: true,
      trustedProviders: ['google', 'facebook'] // Add new provider here
    }
  },
  socialProviders: {
    google: {
      // ... existing Google config
    },
    facebook: {
      clientId: env.FACEBOOK_CLIENT_ID ?? '',
      clientSecret: env.FACEBOOK_CLIENT_SECRET ?? ''
    }
  }
});

4. Update Environment Schema

Add the new variables to lib/env.ts:

server: {
  // ... existing variables
  FACEBOOK_CLIENT_ID: z.string().optional(),
  FACEBOOK_CLIENT_SECRET: z.string().optional(),
},

runtimeEnv: {
  // ... existing variables
  FACEBOOK_CLIENT_ID: process.env.FACEBOOK_CLIENT_ID,
  FACEBOOK_CLIENT_SECRET: process.env.FACEBOOK_CLIENT_SECRET,
},

5. Add Provider to the UI Registry

Add the provider's display name and icon to lib/auth/oauth-providers.tsx. The existing sign-in and sign-up cards iterate over this registry, so you do not need to create another button component:

export const oAuthProviders = {
  google: {
    name: 'Google',
    icon: GoogleIcon
  },
  facebook: {
    name: 'Facebook',
    icon: FacebookIcon
  }
} as const;

The registry key must match the provider key passed to Better Auth. Keep enableSocialLogin enabled in config/auth.config.ts when at least one listed provider is fully configured.

Supported Providers

Better Auth supports many OAuth providers out of the box:

• Google
• Facebook
• GitHub
• Discord
• Apple
• Microsoft
• And many more...

For configuration details and social sign-in examples, see the Better Auth OAuth documentation.

Account Linking

The starter kit has account linking enabled, which allows users to connect multiple OAuth providers to the same account. This is configured in the accountLinking section:

account: {
  accountLinking: {
    enabled: true,
    trustedProviders: ["google"], // Providers that can be linked
  },
},

When a user signs in with a trusted provider using the same verified email address, Better Auth can link the accounts. Only add providers you trust to verify email ownership.