Add OAuth

Learn how to add OAuth authentication providers to your Plainform application for one-click sign-in.

Goal

By the end of this recipe, you'll have added OAuth providers (Google, GitHub, Microsoft, etc.) to your sign-in and sign-up pages.

Prerequisites

• A working Plainform installation
• Clerk account with application configured
• Access to Clerk Dashboard

Steps

import { OAuthConnection } from '@/components/user/OAuthConnection';

export function SignInForm() {
  return (
    <div>
      {/* Email/password form */}
      
      <div className="relative my-6">
        <div className="absolute inset-0 flex items-center">
          <span className="w-full border-t" />
        </div>
        <div className="relative flex justify-center text-xs uppercase">
          <span className="bg-background px-2 text-muted-foreground">
            Or continue with
          </span>
        </div>
      </div>

      {/* OAuth buttons */}
      <div className="grid grid-cols-2 gap-4">
        <OAuthConnection strategy="oauth_google" icon="Google">
          Google
        </OAuthConnection>
        <OAuthConnection strategy="oauth_github" icon="Github">
          GitHub
        </OAuthConnection>
      </div>
    </div>
  );
}

import { OAuthConnection } from '@/components/user/OAuthConnection';

export function SignUpForm() {
  return (
    <div>
      {/* OAuth buttons at the top */}
      <div className="grid grid-cols-2 gap-4 mb-6">
        <OAuthConnection strategy="oauth_google" icon="Google">
          Google
        </OAuthConnection>
        <OAuthConnection strategy="oauth_github" icon="Github">
          GitHub
        </OAuthConnection>
      </div>

      <div className="relative my-6">
        <div className="absolute inset-0 flex items-center">
          <span className="w-full border-t" />
        </div>
        <div className="relative flex justify-center text-xs uppercase">
          <span className="bg-background px-2 text-muted-foreground">
            Or sign up with email
          </span>
        </div>
      </div>

      {/* Email/password form */}
    </div>
  );
}

npm run dev

Available OAuth Providers

Clerk supports the following OAuth providers. Enable them in Clerk Dashboard → Social Connections:

• oauth_google - Google
• oauth_github - GitHub
• oauth_microsoft - Microsoft
• oauth_apple - Apple
• oauth_facebook - Facebook
• oauth_linkedin - LinkedIn
• oauth_twitter - Twitter (X)
• oauth_discord - Discord
• oauth_twitch - Twitch
• oauth_gitlab - GitLab
• oauth_bitbucket - Bitbucket

To add a provider:

1. Enable it in Clerk Dashboard → Social Connections
2. Add the OAuth button to your sign-in/sign-up forms:

<OAuthConnection strategy="oauth_microsoft" icon="Microsoft">
  Microsoft
</OAuthConnection>

Customization Options

Change Button Layout

Display OAuth buttons in a single column:

<div className="space-y-3">
  <OAuthConnection strategy="oauth_google" icon="Google">
    Continue with Google
  </OAuthConnection>
  <OAuthConnection strategy="oauth_github" icon="Github">
    Continue with GitHub
  </OAuthConnection>
</div>

OAuth Callback Handling

Plainform includes an OAuth callback page at app/(auth)/sso-callback/page.tsx:

'use client';

import { AuthenticateWithRedirectCallback } from '@clerk/nextjs';

export default function SSOCallback() {
  return <AuthenticateWithRedirectCallback />;
}

This page handles the OAuth redirect and completes the authentication flow. No changes needed unless you want to customize the loading state.

Common Issues

OAuth Button Not Working

• Verify the provider is enabled in Clerk Dashboard
• Check that the strategy name matches exactly (e.g., oauth_google)
• Ensure OAuthConnection component is imported correctly
• Check browser console for errors

OAuth Popup Blocked

• Ensure popups are allowed in browser settings
• Test in incognito mode to rule out extensions
• Check that redirect URLs are configured correctly in Clerk

User Not Created After OAuth

• Verify email verification settings in Clerk Dashboard
• Check that the OAuth provider returns an email address
• Review Clerk Dashboard → Users for pending verifications

Redirect Loop After OAuth

• Check middleware configuration in proxy.ts
• Verify redirect URLs in Clerk Dashboard match your app URLs
• Ensure sso-callback route is accessible (not protected)

Production Setup

When deploying to production:

1. Use Your Own OAuth Credentials

   • Create OAuth apps for each provider
   • Add production redirect URLs
   • Update credentials in Clerk Dashboard

2. Configure Redirect URLs

   • Add your production domain to OAuth app settings
   • Update Clerk Dashboard with production URLs
   • Format: https://yourdomain.com/sso-callback

3. Test OAuth Flow

   • Test each provider in production
   • Verify redirects work correctly
   • Check that users are created in Clerk Dashboard

Best Practices

• Offer Multiple Providers: Give users choice (Google, GitHub, Microsoft)
• Clear Labeling: Use "Continue with [Provider]" for clarity
• Consistent Placement: Put OAuth buttons in the same location on sign-in and sign-up
• Error Handling: Show clear error messages if OAuth fails
• Privacy Policy: Link to your privacy policy near OAuth buttons

Next Steps

• Customize Sign-In - Customize the sign-in page
• Implement Roles - Add role-based access control
• Protect Routes - Secure your application routes

Related Documentation

• Authentication Overview - Learn about Clerk integration
• Setup & Configuration - Configure Clerk
• Troubleshooting - Fix common issues