OAuth Configuration for Auth Service

This guide explains how to configure OAuth providers (GitHub and Google) for the auth.do.dev unified authentication service.

Required Environment Variables

Add these to your Convex dashboard for the auth deployment (dependable-pika-747):

# Resend (Email OTP)
RESEND_API_KEY=re_xxxxxxxxxxxx
AUTH_RESEND_FROM=auth@notifications.do.dev

# GitHub OAuth
AUTH_GITHUB_ID=xxxxxxxxxxxx
AUTH_GITHUB_SECRET=xxxxxxxxxxxx

# Google OAuth  
AUTH_GOOGLE_ID=xxxxxxxxxxxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=xxxxxxxxxxxx

# JWT Secret (generate a random string)
JWT_SECRET=your-random-jwt-secret-string-here

GitHub OAuth Setup

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Click "New OAuth App"
3. Fill in the application details:
   • Application name: do.dev Auth
   • Homepage URL: https://auth.do.dev (or http://localhost:3030 for dev)
   • Authorization callback URL:
     • Development: http://localhost:3030/api/auth/callback/github
     • Production: https://auth.do.dev/api/auth/callback/github
4. Click "Register application"
5. Copy the Client ID and generate a new Client Secret
6. Add to Convex environment variables:
   • AUTH_GITHUB_ID = Your Client ID
   • AUTH_GITHUB_SECRET = Your Client Secret

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the Google+ API
4. Go to "Credentials" and click "Create Credentials" > "OAuth client ID"
5. Configure the OAuth consent screen first if prompted
6. For Application type, choose "Web application"
7. Add authorized JavaScript origins:
   • http://localhost:3030 (development)
   • https://auth.do.dev (production)
8. Add authorized redirect URIs:
   • http://localhost:3030/api/auth/callback/google (development)
   • https://auth.do.dev/api/auth/callback/google (production)
9. Click "Create"
10. Copy the Client ID and Client Secret
11. Add to Convex environment variables:
    • AUTH_GOOGLE_ID = Your Client ID
    • AUTH_GOOGLE_SECRET = Your Client Secret

Resend Email Setup

1. Sign up for Resend
2. Verify your domain (do.dev)
3. Create an API key
4. Add to Convex environment variables:
   • RESEND_API_KEY = Your API key
   • AUTH_RESEND_FROM = Your verified sender email (e.g., auth@notifications.do.dev)

JWT Secret Generation

Generate a secure random string for JWT signing:

# Using OpenSSL
openssl rand -base64 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Add the generated string as JWT_SECRET in Convex environment variables.

Setting Environment Variables in Convex

1. Go to the Convex dashboard
2. Select your auth project (dependable-pika-747)
3. Go to Settings > Environment Variables
4. Add each variable listed above
5. Save the changes

Testing OAuth Providers

Development Testing

1. Start the auth service:

   cd apps/webs/auth
   pnpm dev

2. Visit http://localhost:3030

3. Try signing in with each provider

4. Check the Convex dashboard logs for any errors

Production Testing

After deploying to production:

1. Visit https://auth.do.dev
2. Test each OAuth provider
3. Verify the redirect flow works correctly
4. Check that sessions are created properly

Troubleshooting

GitHub OAuth Issues

• Error: Redirect URI mismatch: Ensure the callback URL in GitHub matches exactly
• Error: Invalid client: Check that CLIENT_ID and CLIENT_SECRET are correct
• 403 Forbidden: Make sure the OAuth app is not in private mode

Google OAuth Issues

• Error: redirect_uri_mismatch: Add all possible redirect URIs in Google Console
• Error: invalid_client: Verify CLIENT_ID format (should end with .apps.googleusercontent.com)
• Access blocked: Complete the OAuth consent screen configuration

Email OTP Issues

• Emails not sending: Verify domain in Resend dashboard
• From address not accepted: Use a verified domain email
• Rate limiting: Check Resend dashboard for quota limits

Security Best Practices

1. Never commit secrets: Keep all OAuth credentials in environment variables
2. Use HTTPS in production: OAuth requires secure connections
3. Rotate secrets regularly: Update OAuth secrets periodically
4. Limit redirect URIs: Only add necessary redirect URLs
5. Monitor usage: Check OAuth app analytics for suspicious activity