OAuth Providers

Overview

This template supports OAuth authentication with Google and GitHub providers through Better-Auth.

Supported Providers

Google OAuth Setup

1. Create Google OAuth App

2. Configure Environment Variables

Add to .env.local:

GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

3. Test Google Login

1. Start your development server
2. Navigate to the login page
3. Click "Continue with Google"
4. Authorize the application
5. You should be redirected back and logged in

GitHub OAuth Setup

1. Create GitHub OAuth App

2. Configure Environment Variables

Add to .env.local:

GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

3. Test GitHub Login

1. Start your development server
2. Navigate to the login page
3. Click "Continue with GitHub"
4. Authorize the application
5. You should be redirected back and logged in

Using OAuth in Components

Login Form with Social Providers

import { FormLogin } from "@/features/auth/components";

<FormLogin
  onSuccess={() => router.push(PageDashboard())}
  showSocialProviders={true}
/>

Manual OAuth Trigger

"use client";

import { authClient } from "@/lib/auth/client";
import { PageDashboard } from "@/routes";
import { Button } from "@/components/ui/button";
import { Icon } from "@/components/ui/icon";

export function SocialLogin() {
  const handleGoogleLogin = async () => {
    await authClient.signIn.social({
      provider: "google",
      callbackURL: PageDashboard(),
    });
  };

  const handleGitHubLogin = async () => {
    await authClient.signIn.social({
      provider: "github",
      callbackURL: PageDashboard(),
    });
  };

  return (
    <div className="space-y-2">
      <Button onClick={handleGoogleLogin} variant="outline" className="w-full">
        <Icon iconKey="BrandGoogle" className="mr-2" />
        Continue with Google
      </Button>
      
      <Button onClick={handleGitHubLogin} variant="outline" className="w-full">
        <Icon iconKey="BrandGithub" className="mr-2" />
        Continue with GitHub
      </Button>
    </div>
  );
}

OAuth Flow

Authentication Flow

1. User clicks "Continue with [Provider]"
2. User redirected to provider's authorization page
3. User authorizes the application
4. Provider redirects back with authorization code
5. Server exchanges code for access token
6. User profile fetched from provider
7. User account created or linked
8. Session created and user logged in
9. Redirect to callback URL

Account Linking

If a user signs in with OAuth and an account with that email already exists:

• Auto-link: Account is automatically linked if email is verified
• Manual link: User prompted to link accounts

OAuth Data Stored

When a user signs in with OAuth, the following data is stored:

Manage OAuth Connections

Link/Unlink Providers

import { FormManageProviders } from "@/features/auth/components";

<FormManageProviders />

This component allows users to:

• View linked OAuth accounts
• Link new OAuth providers
• Unlink OAuth providers (if password is set)

Security Considerations

1. Callback URL Validation

Always validate callback URLs match your domain:

// In OAuth callback handler
const allowedCallbacks = [
  "https://your-app.com",
  "http://localhost:3000", // Dev only
];

2. State Parameter

Better-Auth automatically handles CSRF protection via the state parameter.

3. Scope Limitations

Only request necessary scopes:

• Google: email, profile
• GitHub: user:email

4. Email Verification

OAuth emails are automatically marked as verified since they're verified by the provider.

Troubleshooting

Redirect URI Mismatch

Error: redirect_uri_mismatch

Solution:

• Check the redirect URI in provider settings exactly matches
• Include protocol (http/https)
• No trailing slashes
• Match port number in development

Invalid Client

Error: invalid_client

Solution:

• Verify CLIENT_ID and CLIENT_SECRET are correct
• Check environment variables are loaded
• Restart development server after adding variables

OAuth Not Working in Production

Checklist:

• Update BETTER_AUTH_URL to production domain
• Add production callback URL to provider settings
• Use HTTPS in production
• Check environment variables are set in deployment

User Email Not Available

Some providers may not return email if:

• Email is not verified on provider
• Email permission not granted
• Email scope not requested

Adding More Providers

Better-Auth supports many OAuth providers. To add more:

1. Install provider package if needed
2. Add provider configuration to src/lib/auth/server.ts
3. Add environment variables
4. Update UI components to include new provider

See Better-Auth documentation for more providers.

Next Steps