# Social Providers

> Configure OAuth providers for social login (Google, GitHub, etc.)

*Canonical: https://makerkit.dev/docs/nextjs-prisma/better-auth/social-providers*

---

Add "Sign in with Google" or "Sign in with GitHub" buttons by configuring OAuth credentials - no code changes to the sign-in forms required.

This page is part of the [Authentication documentation](./overview).

OAuth social providers let users authenticate with existing accounts from Google, GitHub, and other identity providers. This repo ships Google provider wiring. The sign-in forms only display buttons for providers listed in `NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS`, and the provider must also be configured server-side.

OAuth social providers are third-party identity providers (Google, GitHub, Microsoft, etc.) that handle authentication and return user identity to your app via the [OAuth 2.0 protocol](https://oauth.net/2/).

## Enabled Providers

Control which OAuth providers appear on sign-in forms:

```bash {% title="./.env.local" %}
NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS=google,github
```

## Google OAuth Setup

### 1. Create OAuth Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a new OAuth 2.0 Client ID
3. Set the authorized redirect URI (see Redirect URL section below)
4. Copy the Client ID and Client Secret

### 2. Add Environment Variables

```bash {% title="./.env.local" %}
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
```

Google OAuth is available when these credentials are present. Add `google` to `NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS` to show the button in the UI.

## Adding New OAuth Providers

To add a provider like GitHub:

### 1. Create Provider Plugin

Create a file in `packages/better-auth/src/plugins/`:

```tsx {% title="packages/better-auth/src/plugins/github-provider.ts" %}
import { socialProviders } from 'better-auth/social-providers';
import * as z from 'zod';

export function createGithubProviderPlugin() {
  const githubClientId = z
    .string()
    .min(1)
    .optional()
    .parse(process.env.GITHUB_CLIENT_ID);

  const githubClientSecret = z
    .string()
    .min(1)
    .optional()
    .parse(process.env.GITHUB_CLIENT_SECRET);

  if (!githubClientId || !githubClientSecret) {
    return [] as never;
  }

  return [
    socialProviders.github({
      clientId: githubClientId,
      clientSecret: githubClientSecret,
    }),
  ];
}
```

### 2. Register in `social-providers.ts`

Add to `packages/better-auth/src/plugins/social-providers.ts`:

```tsx
import { createGithubProviderPlugin } from './github-provider';

export const createSocialProviderPlugin = () => {
  const googleSocialProviderPlugin = createGoogleProviderPlugin();
  const githubSocialProviderPlugin = createGithubProviderPlugin();

  return {
    ...googleSocialProviderPlugin,
    ...githubSocialProviderPlugin,
  };
};
```

### 3. Add Environment Variables

```bash {% title="./.env.local" %}
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS=google,github
```

## Redirect URL

Configure this redirect URL in your OAuth provider's dashboard:

```
https://<your-site-url>/api/auth/callback/<provider-name>
```

**Examples:**
- Google: `https://myapp.com/api/auth/callback/google`
- GitHub: `https://myapp.com/api/auth/callback/github`
- Development: `http://localhost:3000/api/auth/callback/google`

See the [Better Auth social providers documentation](https://www.better-auth.com/docs/authentication/social-sign-in) for provider-specific configuration.

## Common Pitfalls

- **Mismatched redirect URLs**: The redirect URL in your OAuth provider dashboard must exactly match your `NEXT_PUBLIC_SITE_URL`. `http://localhost:3000` is different from `http://127.0.0.1:3000`.
- **Missing environment variables**: The provider silently disables itself if credentials are missing. Check your `.env.local` file.
- **Forgetting to add provider to `NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS`**: The plugin loads, but the button won't appear on sign-in forms.
- **Production credentials in development**: Create separate OAuth apps for development and production with different redirect URLs.
- **Not verifying the OAuth app**: Some providers (Google) require app verification for production use with more than 100 users.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Why is my OAuth button not showing up?", "answer": "Check three things: (1) credentials are in .env.local, (2) provider is in NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS, (3) redirect URL matches in the provider dashboard."},
     {"question": "Can users link multiple OAuth accounts?", "answer": "Yes. Better Auth supports account linking. A user can sign up with Google and later link their GitHub account from settings."},
     {"question": "What user data do OAuth providers return?", "answer": "Typically: email, name, and profile picture. The exact fields vary by provider. Email is always available from Google and GitHub."},
     {"question": "How do I customize what happens after OAuth sign-in?", "answer": "The post-auth redirect is controlled by the callbackURL parameter and your middleware. By default, users go to the app home path."},
     {"question": "Do I need different OAuth apps for staging and production?", "answer": "Yes. Create separate OAuth apps with different redirect URLs for each environment."}
   ]
/%}

---

**Next:** [Multi-Factor Authentication Configuration →](./mfa-configuration)