Social Authentication

Social authentication allows users to login with their existing accounts from Google, GitHub, Facebook, or Apple. No new passwords to remember!
Perfect for: Reducing friction, increasing conversion rates, and providing trusted authentication.

How to Activate

1

Add to auth methods

# Add social providers to available methods
NEXT_PUBLIC_AUTH_METHODS="credential,magiclink,google,github"

# Configure each provider (see sections below)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-secret"
2

Configure providers

Set up OAuth apps with each provider (detailed below).
3

That's it!

Social login buttons automatically appear on /[locale]/login and /[locale]/register.

Available Providers

Most popular choice - works for all Gmail usersSetup location: Google Cloud ConsoleRequired scopes: email, profile

Google OAuth Setup

1

Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Create new project or select existing one
  3. Enable "Google+ API" in API Library
2

Create OAuth Credentials

  1. Go to "Credentials" section
  2. Click "Create Credentials" → "OAuth 2.0 Client IDs"
  3. Choose "Web application"
  4. Add authorized redirect URIs:
    • Development: http://localhost:3000/api/auth/callback/google
    • Production: https://yourdomain.com/api/auth/callback/google
3

Get credentials

GOOGLE_CLIENT_ID="123456789.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
Google setup docs: OAuth 2.0 Setup Guide

GitHub OAuth Setup

1

Go to GitHub Settings

  1. Visit GitHub Developer Settings
  2. Click "OAuth Apps" → "New OAuth App"
2

Configure OAuth App

  • Application name: Your App Name
  • Homepage URL: http://localhost:3000 (development)
  • Authorization callback URL: http://localhost:3000/api/auth/callback/github
  • Application description: Optional description
3

Get credentials

GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"
GitHub setup docs: Creating an OAuth App

Facebook OAuth Setup

1

Create Facebook App

  1. Go to Facebook Developers
  2. Click "My Apps" → "Create App"
  3. Choose "Consumer" app type
2

Add Facebook Login

  1. In app dashboard, click "Add Product"
  2. Find "Facebook Login" and click "Set Up"
  3. Choose "Web" platform
3

Configure Valid OAuth URIs

Add redirect URIs in Facebook Login settings:
  • Development: http://localhost:3000/api/auth/callback/facebook
  • Production: https://yourdomain.com/api/auth/callback/facebook
4

Get credentials

FACEBOOK_CLIENT_ID="your-facebook-app-id"
FACEBOOK_CLIENT_SECRET="your-facebook-app-secret"
Facebook setup docs: Facebook Login for Web

Apple Sign In Setup

1

Apple Developer Account

  1. Go to Apple Developer Portal
  2. Sign in with Apple Developer account (requires membership)
2

Create Service ID

  1. Go to "Certificates, Identifiers & Profiles"
  2. Click "Identifiers" → "+"
  3. Choose "Services IDs"
  4. Configure your service identifier
3

Configure Sign In with Apple

  1. Enable "Sign In with Apple" for your Service ID
  2. Add domains and redirect URLs:
    • Domain: yourdomain.com
    • Redirect URL: https://yourdomain.com/api/auth/callback/apple
4

Get credentials

APPLE_CLIENT_ID="your-apple-service-id"
APPLE_CLIENT_SECRET="your-apple-private-key"
Apple requires HTTPS: Apple Sign In only works with HTTPS domains, not localhost. Test in production or use ngrok for development.
Apple setup docs: Sign In with Apple JS

How Social Login Works

User Experience Flow

1

User clicks social button

On login/register page, user clicks "Sign in with Google" (or other provider).
2

Redirect to provider

User is redirected to provider's authorization page (Google, GitHub, etc.).
3

User authorizes

User logs into their provider account and grants permissions.
4

Return with data

Provider redirects back with user info (email, name, avatar).
5

Account created/linked

  • New user: Account created automatically
  • Existing user: Provider linked to existing account
  • User is logged in and redirected to dashboard

Account Linking

Smart account linking: If a user signs up with Google using john@gmail.com, then later tries to login with GitHub using the same email, the accounts are automatically linked.
Account linking features:
  • Same email = automatic account linking
  • Users can have multiple providers on one account
  • Can unlink providers in account settings
  • Primary email remains consistent

Better Auth Configuration

The social providers use Better Auth's socialProviders configuration: 
// In src/lib/better-auth/auth.ts
socialProviders: {
  google: {
    prompt: 'select_account',
    clientId: env.GOOGLE_CLIENT_ID as string,
    clientSecret: env.GOOGLE_CLIENT_SECRET as string,
  },
  // Add other providers as needed
}
Account linking is enabled: 
account: {
  accountLinking: {
    enabled: true,
  },
}

Common Issues & Solutions

"Redirect URI mismatch" error?
  • Check callback URLs in provider settings match exactly
  • Include both development and production URLs
  • Verify HTTPS vs HTTP (Apple requires HTTPS)
  • Check for trailing slashes in URLs
"Invalid client" or "App not configured" error?
  • Verify CLIENT_ID and CLIENT_SECRET are correct
  • Check provider app is published/approved (not in development mode)
  • Ensure required scopes/permissions are configured
  • Confirm environment variables are loaded correctly
Social buttons not appearing?
  • Check NEXT_PUBLIC_AUTH_METHODS includes provider name
  • Verify environment variables are set with NEXT_PUBLIC_ prefix where needed
  • Restart development server after adding new variables
  • Check provider is properly configured in Better Auth config

Testing Checklist

1

Test each provider

  1. Try logging in with each configured provider
  2. Verify user info is collected correctly (name, email, avatar)
  3. Check account creation works for new users
  4. Test account linking with existing email
2

Test error scenarios

  1. Try with invalid/expired credentials
  2. Test redirect URI mismatches
  3. Verify error messages are user-friendly
3

Test account management

  1. Link multiple providers to same account
  2. Unlink providers in settings
  3. Verify primary email handling

Security Considerations

Built-in security features:
  • OAuth 2.0 standard compliance
  • Secure token exchange
  • No passwords stored for social accounts
  • Account linking prevents duplicate accounts
Best practices:
  • Keep client secrets secure and private
  • Use HTTPS in production (required for Apple)
  • Regularly rotate client secrets
  • Monitor for suspicious login patterns
All working? Your users can now login with their favorite social accounts in just one click!
    Social Authentication | ShipSaaS Documentation | ShipSaaS - Launch your SaaS with AI in days