Overview

This guide will walk you through setting up Google OAuth authentication for your Convex application. By the end of this setup, your users will be able to sign in using their Google accounts.

Prerequisites

Before starting, ensure you have:

• A Google developer account (create one at Google for Developers)
• A Convex project set up and deployed
• Access to your Convex deployment's HTTP Actions URL

Step 1: Create or Open a Google Cloud Project

1. Navigate to the Google Auth Platform overview
2. Select an existing project or create a new one by clicking "New Project"
3. If creating a new project, provide a project name and click "Create"

Step 2: Configure OAuth Consent Screen

Initial Setup

1. In your Google Cloud Console, navigate to APIs & Services > OAuth consent screen
2. Click the "GET STARTED" button on the Overview page
3. Fill in the required information:
   • App name: Enter the name that will be displayed to users during authentication
   • User support email: Select an email address for user support
4. Click "NEXT"

Choose App Type

1. Select your app type:
   • Internal: For apps used within your organization only
   • External: For public applications (recommended for most use cases)
2. Click "NEXT"

Contact Information

1. Enter email addresses for Contact Information (required for external apps)
2. Click "NEXT"
3. Review the User Data Policy and check the agreement box
4. Click "CONTINUE"
5. Click "CREATE"

Configure Test Users (External Apps Only)

If you chose External app type:

1. Click "Test users" in the left navigation menu
2. Click "ADD USERS"
3. Add email addresses of users who should be able to test your authentication
4. Click "SAVE"

Step 3: Create OAuth Client Credentials

Create OAuth Client

1. Navigate to APIs & Services > Credentials
2. Click "CREATE CREDENTIALS" and select "OAuth client ID"
3. Choose "Web application" as the application type
4. Enter a name for your OAuth client (for organizational purposes only)

Configure Authorized Origins and Redirect URIs

Authorized JavaScript Origins

For development:

http://localhost:3000

For production, add your actual domain:

https://yourdomain.com

Authorized Redirect URIs

1. Find your Convex HTTP Actions URL:

   • Open your Convex dashboard
   • Navigate to Settings > URL & Deploy Key > Show development credentials
   • Note your HTTP Actions URL (ends with .site, not .cloud)

2. Configure the redirect URI:

   • Format: {HTTP_ACTIONS_URL}/api/auth/callback/google
   • Example: If your actions URL is https://fast-horse-123.convex.site, then your redirect URI is:

   https://fast-horse-123.convex.site/api/auth/callback/google
   

3. Click "CREATE" to save your OAuth client

Step 4: Set Convex Environment Variables

Retrieve OAuth Credentials

1. From the Credentials page, click on your newly created OAuth client
2. Copy the Client ID and Client secret values

Configure Environment Variables

You can set environment variables either via the Convex CLI or through the dashboard.

Option 1: Using Convex CLI (Recommended)

Open your terminal in your Convex application directory and run:

Copy# Set Google OAuth Client ID
npx convex env set AUTH_GOOGLE_ID your_google_client_id_here
 
# Set Google OAuth Client Secret
npx convex env set AUTH_GOOGLE_SECRET your_google_client_secret_here

Option 2: Using Convex Dashboard

1. Open your Convex dashboard
2. Navigate to Settings > Environment Variables
3. Add the following variables:
   • Variable Name: AUTH_GOOGLE_ID, Value: Your Google Client ID
   • Variable Name: AUTH_GOOGLE_SECRET, Value: Your Google Client Secret

Common Issues and Solutions

"Error 400: redirect_uri_mismatch"

• Verify your redirect URI exactly matches the format: {HTTP_ACTIONS_URL}/api/auth/callback/google
• Ensure you're using the correct HTTP Actions URL (ends with .site)

Environment Variables Not Found

• Ensure environment variables are set correctly
• Restart your Convex deployment after setting new environment variables

Security Best Practices

• Regularly rotate your OAuth client secrets
• Monitor your Google Cloud Console for any suspicious activity
• Use HTTPS in production environments
• Consider implementing additional security measures like rate limiting

Support

For additional help:

• Convex Auth Documentation
• Google OAuth Documentation

Secure authentication made simple with Convex Auth! 🚀