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';
import { useClerk } from '@clerk/nextjs';

export function SignInForm() {
  const { client } = useClerk();
  const lastStrategy = client?.lastAuthenticationStrategy;

  return (
    <div>
      {/* OAuth buttons */}
      <div className="w-full flex flex-col gap-4">
        <OAuthConnection
          strategy="oauth_google"
          lastUsed={lastStrategy}
          icon="Google"
        >
          Continue with Google
        </OAuthConnection>
        
        <OAuthConnection
          lastUsed={lastStrategy}
          strategy="oauth_github"
          icon="GitHub"
        >
          Continue with GitHub
        </OAuthConnection>
      </div>

      {/* Separator */}
      <div className="flex gap-3 items-center text-neutral-foreground">
        <Separator className="shrink" />
        Or continue with email
        <Separator className="shrink" />
      </div>

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

import { OAuthConnection } from '@/components/user/OAuthConnection';
import { useClerk } from '@clerk/nextjs';

export function SignUpForm() {
  const { client } = useClerk();
  const lastStrategy = client?.lastAuthenticationStrategy;

  return (
    <div>
      {/* OAuth buttons at the top */}
      <div className="w-full flex flex-col gap-4">
        <OAuthConnection
          isSignedUp
          strategy="oauth_google"
          lastUsed={lastStrategy}
          icon="Google"
        >
          Continue with Google
        </OAuthConnection>
        
        <OAuthConnection
          isSignedUp
          lastUsed={lastStrategy}
          strategy="oauth_github"
          icon="GitHub"
        >
          Continue with GitHub
        </OAuthConnection>
      </div>

      {/* Separator */}
      <div className="flex gap-3 items-center text-neutral-foreground">
        <Separator className="shrink" />
        Or sign up with email
        <Separator className="shrink" />
      </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 OAuthConnection component to your sign-in/sign-up forms with the required props:

<OAuthConnection
  strategy="oauth_microsoft"  // Required: Must match Clerk's strategy name
  icon="Microsoft"             // Required: Icon name from SvgFinder
  lastUsed={lastStrategy}      // Optional: For "Last used" badge
>
  Continue with Microsoft       {/* Required: Button text */}
</OAuthConnection>

Important: The strategy prop must exactly match Clerk's OAuth strategy names (e.g., oauth_google, not google or oauth-google).

Customization Options

Change Button Layout

Display OAuth buttons in a single column (default in Plainform):

<div className="w-full flex flex-col gap-4">
  <OAuthConnection
    strategy="oauth_google"
    lastUsed={lastStrategy}
    icon="Google"
  >
    Continue with Google
  </OAuthConnection>
  
  <OAuthConnection
    lastUsed={lastStrategy}
    strategy="oauth_github"
    icon="GitHub"
  >
    Continue with GitHub
  </OAuthConnection>
</div>

Or use a grid layout for multiple providers:

<div className="grid grid-cols-2 gap-4">
  <OAuthConnection strategy="oauth_google" lastUsed={lastStrategy} icon="Google">
    Google
  </OAuthConnection>
  <OAuthConnection strategy="oauth_github" lastUsed={lastStrategy} icon="GitHub">
    GitHub
  </OAuthConnection>
  <OAuthConnection strategy="oauth_microsoft" lastUsed={lastStrategy} icon="Microsoft">
    Microsoft
  </OAuthConnection>
  <OAuthConnection strategy="oauth_apple" lastUsed={lastStrategy} icon="Apple">
    Apple
  </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. The OAuthConnection component automatically redirects to this page with:

async function signInWith(strategy: OAuthStrategy) {
  setLoadingProvider(strategy);

  try {
    return signIn?.authenticateWithRedirect({
      strategy,
      redirectUrl: '/sso-callback',
      redirectUrlComplete: '/',
    });
  } catch (error) {
    return error;
  }
}

async function signUpWith(strategy: OAuthStrategy) {
  setLoadingProvider(strategy);

  try {
    return signUp?.authenticateWithRedirect({
      strategy,
      redirectUrl: '/sso-callback',
      redirectUrlComplete: '/',
    });
  } catch (error) {
    return error;
  }
}

No changes needed unless you want to customize the loading state or redirect behavior.

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 Redirect Fails

• Check that redirect URLs are configured correctly in Clerk
• Verify the provider is enabled and configured in Clerk Dashboard
• Test in incognito mode to rule out extension or cookie issues

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