Social Authentication (OAuth)

Overview

Add social authentication to your TanStack Start app with support for GitHub and Google OAuth. Built on Convex Auth with automatic user profile creation, session management, and protected routes.

Features

GitHub OAuth integration
Google OAuth integration
Automatic user profile creation
Profile pictures from OAuth providers
Session management
Protected routes
Loading states
Error handling
Type-safe

Installation

Install the component

npx shadcn@latest add https://convex-ui.vercel.app/r/social-auth-tanstack

Configure OAuth providers

Set up OAuth apps in provider dashboards:GitHub:

Go to GitHub Settings → Developer settings → OAuth Apps
Create new OAuth app
Set callback URL: https://YOUR_CONVEX_URL/api/auth/callback/github

Google:

Go to Google Cloud Console → APIs & Services → Credentials
Create OAuth 2.0 Client ID
Add authorized redirect URI: https://YOUR_CONVEX_URL/api/auth/callback/google

Add environment variables

In Convex dashboard (Settings → Environment Variables):

AUTH_GITHUB_ID=your_github_client_id
AUTH_GITHUB_SECRET=your_github_client_secret
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret

Start development

npx convex dev

What Gets Installed

Components

login-form.tsx - Social login buttons for GitHub and Google
logout-button.tsx - Sign out button

Routes

routes/auth/login.tsx - Login page with social options
routes/_protected/index.tsx - Example protected route

Backend (Convex)

convex/schema.ts - User schema with OAuth fields
convex/auth.ts - Auth query endpoints
convex/auth.config.ts - OAuth provider configuration
convex/users.ts - User profile queries
convex/http.ts - OAuth callback handlers

Environment Variables

Required (Convex Dashboard)

AUTH_GITHUB_ID

string

GitHub OAuth App Client ID

AUTH_GITHUB_SECRET

string

GitHub OAuth App Client Secret

AUTH_GOOGLE_ID

string

Google OAuth Client ID

AUTH_GOOGLE_SECRET

string

Google OAuth Client Secret

At least one OAuth provider (GitHub or Google) must be configured for authentication to work.

Usage

routes/auth/login.tsx

import { SocialLoginForm } from "@/components/login-form";

export default function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SocialLoginForm />
    </div>
  );
}

Specify Providers

Choose which OAuth providers to display:

import { SocialLoginForm } from "@/components/login-form";

// GitHub only
<SocialLoginForm providers={["github"]} />

// Google only
<SocialLoginForm providers={["google"]} />

// Both (default)
<SocialLoginForm providers={["github", "google"]} />

Protected Routes

Check authentication before rendering protected content:

routes/_protected.tsx

import { createFileRoute, redirect, Outlet } from "@tanstack/react-router";
import { convexQuery, api } from "@/lib/convex/server";

export const Route = createFileRoute("/_protected")(
  beforeLoad: async ({ context }) => {
    const user = await context.queryClient.fetchQuery(
      convexQuery(api.users.current, {})
    );
    
    if (!user) {
      throw redirect({ to: "/auth/login" });
    }
  },
  component: ProtectedLayout,
});

function ProtectedLayout() {
  return <Outlet />;
}

Display User Info

Access authenticated user data:

import { useQuery } from "@tanstack/react-query";
import { convexQuery, api } from "@/lib/convex/server";

export function UserProfile() {
  const { data: user } = useQuery(
    convexQuery(api.users.current, {})
  );

  if (!user) return null;

  return (
    <div>
      <img src={user.image} alt={user.name} />
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

Sign Out

import { LogoutButton } from "@/components/logout-button";

export function Header() {
  return (
    <header>
      <h1>My App</h1>
      <LogoutButton />
    </header>
  );
}

OAuth Flow

User Clicks Provider Button

User clicks “Continue with GitHub” or “Continue with Google”

Redirect to Provider

User is redirected to the OAuth provider’s authorization page

User Grants Permission

User authorizes your app to access their profile

Callback to Convex

Provider redirects to Convex with authorization code

Profile Creation

Convex creates or updates user profile with OAuth data

Session Created

User is signed in and redirected to the app

API Reference

SocialLoginForm Props

interface SocialLoginFormProps {
  providers?: Array<"github" | "google">;
}

providers

array

default:"[\"github\", \"google\"]"

Array of OAuth providers to display. Available options: "github", "google"

Example:

// Show only GitHub
<SocialLoginForm providers={["github"]} />

// Show only Google
<SocialLoginForm providers={["google"]} />

// Show both (default)
<SocialLoginForm />

Auth Actions

Use Convex Auth hooks for programmatic authentication:

import { useAuthActions } from "@convex-dev/auth/react";

function LoginButton() {
  const { signIn } = useAuthActions();

  return (
    <button onClick={() => signIn("github")}>
      Sign in with GitHub
    </button>
  );
}

Check Auth Status

import { Authenticated, Unauthenticated } from "convex/react";

function AuthStatus() {
  return (
    <>
      <Authenticated>
        <p>You are signed in</p>
      </Authenticated>
      <Unauthenticated>
        <p>You are signed out</p>
      </Unauthenticated>
    </>
  );
}

Backend Implementation

User Schema

OAuth providers populate these fields:

convex/schema.ts

import { defineSchema, defineTable } from "convex/server";
import { authTables } from "@convex-dev/auth/server";
import { v } from "convex/values";

export default defineSchema({
  ...authTables,
  users: defineTable({
    name: v.optional(v.string()),
    image: v.optional(v.string()),
    email: v.optional(v.string()),
  }),
});

User Queries

Access user data securely:

convex/users.ts

import { query } from "./_generated/server";
import { getAuthUserId } from "@convex-dev/auth/server";

export const current = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) return null;
    return await ctx.db.get(userId);
  },
});

Customization

Custom Button Styles

Modify the login form component:

<Button
  variant="outline"
  size="lg"
  className="w-full bg-black text-white hover:bg-gray-800" // Custom styles
  onClick={() => handleSocialLogin("github")}
>
  <GitHubIcon className="mr-2 h-5 w-5" />
  Continue with GitHub
</Button>

Add More Providers

Convex Auth supports additional OAuth providers. Update convex/auth.config.ts:

import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      domain: process.env.CONVEX_SITE_URL!,
      applicationID: "convex",
    },
    // Add Twitter, Discord, etc.
  ],
} satisfies AuthConfig;

Custom Redirect

Change where users go after login:

const handleSocialLogin = async (provider: "github" | "google") => {
  await signIn(provider);
  navigate({ to: "/dashboard" }); // Custom destination
};

Getting OAuth Credentials

GitHub

Go to GitHub Settings

Navigate to Settings → Developer settings → OAuth Apps

Create New OAuth App

Click “New OAuth App”

Fill in Details

Application name: Your app name
Homepage URL: Your app URL
Callback URL: https://YOUR_CONVEX_URL/api/auth/callback/github

Get Credentials

Copy the Client ID and generate a Client Secret

Google

Go to Google Cloud Console

Visit Google Cloud Console

Create Project

Create a new project or select existing

Enable Google+ API

APIs & Services → Enable APIs and Services → Google+ API

Create OAuth Credentials

APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID

Configure OAuth Consent

Fill in application name and support email

Add Redirect URI

https://YOUR_CONVEX_URL/api/auth/callback/google

Get Credentials

Copy the Client ID and Client Secret

Security

OAuth tokens are never exposed to the client
Callback URLs must be configured in provider dashboards
State parameter prevents CSRF attacks
Sessions are HTTP-only cookies
Tokens expire automatically

Troubleshooting

Redirect URI mismatch

Ensure the callback URL in your OAuth provider settings exactly matches: https://YOUR_CONVEX_URL/api/auth/callback/{provider}

Cannot read properties of undefined (reading 'signIn')

OAuth provider not configured

Verify environment variables are set in the Convex dashboard, not your local .env file.

User data not showing

Check that your OAuth app has permissions to access user email and profile.

Password-Based Auth - Add email/password authentication
Current User Avatar - Display authenticated user
Convex Client Setup - Configure Convex with TanStack Start

Get Started

Next.js Components

React Components

TanStack Components

Social Authentication (OAuth)

Overview

Features

Installation

What Gets Installed

Components

Routes

Backend (Convex)

Environment Variables

Required (Convex Dashboard)

Usage

Specify Providers

Protected Routes

Display User Info

Sign Out

OAuth Flow

API Reference

SocialLoginForm Props

Auth Actions

Check Auth Status

Backend Implementation

User Schema

User Queries

Customization

Custom Button Styles

Add More Providers

Custom Redirect

Getting OAuth Credentials

GitHub

Google

Security

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Next.js Components

React Components

TanStack Components

​Overview

​Features

​Installation

​What Gets Installed

​Components

​Routes

​Backend (Convex)

​Environment Variables

​Required (Convex Dashboard)

​Usage

​Basic Social Login

​Specify Providers

​Protected Routes

​Display User Info

​Sign Out

​OAuth Flow

​API Reference

​SocialLoginForm Props

​Auth Actions

​Check Auth Status

​Backend Implementation

​User Schema

​User Queries

​Customization

​Custom Button Styles

​Add More Providers

​Custom Redirect

​Getting OAuth Credentials

​GitHub

​Google

​Security

​Troubleshooting

​Related Components

Build docs developers (and LLMs) love

Overview

Features

Installation

What Gets Installed

Components

Routes

Backend (Convex)

Environment Variables

Required (Convex Dashboard)

Usage

Basic Social Login

Specify Providers

Protected Routes

Display User Info

Sign Out

OAuth Flow

API Reference

SocialLoginForm Props

Auth Actions

Check Auth Status

Backend Implementation

User Schema

User Queries

Customization

Custom Button Styles

Add More Providers

Custom Redirect

Getting OAuth Credentials

GitHub

Google

Security

Troubleshooting

Related Components