Skip to content

OAuth Provider Setup Guide

This guide covers OAuth configuration for the multi-environment deployment setup.

Understanding OAuth with Supabase Branches

Since we use a single Supabase project with branches, OAuth configuration is at the project level:

  • All branches (main, develop, pr-*) share the same OAuth apps
  • The callback URL is the same for all branches
  • You need separate OAuth apps only for local development

Required OAuth Apps

1. Production OAuth Apps (Supabase Dashboard)

These are configured in Supabase Dashboard and used by ALL remote branches.

GitHub OAuth App

  1. Go to GitHub → Settings → Developer Settings → OAuth Apps → New OAuth App
  2. Configure: 
    Application name: YourApp (Production)
Homepage URL: https://your-domain.com
Authorization callback URL: https://<project-id>.supabase.co/auth/v1/callback
  3. Copy Client ID and Client Secret
  4. In Supabase Dashboard → Authentication → Providers → GitHub:
  5. Enable GitHub provider
  6. Paste Client ID and Client Secret

Google OAuth App

  1. Go to Google Cloud Console → APIs & Services → Credentials → Create OAuth Client ID
  2. Configure: 
    Application type: Web application
Name: YourApp (Production)
Authorized JavaScript origins: https://your-domain.com
Authorized redirect URIs: https://<project-id>.supabase.co/auth/v1/callback
  3. Copy Client ID and Client Secret
  4. In Supabase Dashboard → Authentication → Providers → Google:
  5. Enable Google provider
  6. Paste Client ID and Client Secret

2. Local Development OAuth Apps

These are used only for local development with supabase start.

GitHub OAuth App (Local)

  1. Create a separate OAuth app for local development: 
    Application name: YourApp (Local Dev)
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:54321/auth/v1/callback
  2. Add to your .env.local: 
    GITHUB_CLIENT_ID=your-local-github-client-id
GITHUB_CLIENT_SECRET=your-local-github-client-secret

Google OAuth App (Local)

  1. Create a separate OAuth client for local development: 
    Application type: Web application
Name: YourApp (Local Dev)
Authorized JavaScript origins: http://localhost:3000
Authorized redirect URIs: http://localhost:54321/auth/v1/callback
  2. Add to your .env.local: 
    GOOGLE_CLIENT_ID=your-local-google-client-id
GOOGLE_CLIENT_SECRET=your-local-google-client-secret

Configuration Files

supabase/config.toml (Local Development Only)

[auth.external.github]
enabled = true
client_id = "env(GITHUB_CLIENT_ID)"
secret = "env(GITHUB_CLIENT_SECRET)"

[auth.external.google]
enabled = true
client_id = "env(GOOGLE_CLIENT_ID)"
secret = "env(GOOGLE_CLIENT_SECRET)"

Note: This config is ONLY used for local development with supabase start. Remote environments use the Supabase Dashboard configuration.

.env.local

# Local OAuth credentials (for supabase start)
GITHUB_CLIENT_ID=your-local-github-client-id
GITHUB_CLIENT_SECRET=your-local-github-client-secret
GOOGLE_CLIENT_ID=your-local-google-client-id
GOOGLE_CLIENT_SECRET=your-local-google-client-secret

Environment Matrix

Environment OAuth Config Location Callback URL
Production (main) Supabase Dashboard https://<project>.supabase.co/auth/v1/callback
Staging (develop) Supabase Dashboard https://<project>.supabase.co/auth/v1/callback
Preview (pr-*) Supabase Dashboard https://<project>.supabase.co/auth/v1/callback
Local config.toml + .env.local http://localhost:54321/auth/v1/callback

Important Notes

  1. Single Project = Single OAuth: All Supabase branches share the same OAuth configuration from the Dashboard.

  2. Callback URL is Project-Level: The OAuth callback URL (https://<project>.supabase.co/auth/v1/callback) is the same regardless of which branch the user is testing.

  3. Local Needs Separate Apps: Local development (localhost) requires separate OAuth apps because:

  4. Callback URL is different (localhost:54321)

  5. Most OAuth providers don't allow mixing localhost with production URLs

  6. Frontend URLs Matter Too: If your frontend is on different domains per environment: 

    Production: https://app.yoursite.com
Staging: https://staging.yoursite.com
    You may need to add these as authorized origins in your OAuth app settings.

Separating Production and Staging OAuth (Optional)

If you want completely isolated OAuth for staging (e.g., different user pools), you would need:

  1. Separate Supabase Projects (not branches)
  2. Separate OAuth Apps per project
  3. Separate callback URLs

This is NOT the current architecture (we use branches for cost efficiency), but may be desired for enterprise setups.

Troubleshooting

"redirect_uri_mismatch" Error

The callback URL in your OAuth app doesn't match. Verify: - Supabase Dashboard shows the correct callback URL - OAuth provider has the exact URL registered (no trailing slashes)

OAuth Works in Production but Not Locally

You need separate OAuth apps for local development. The callback URL for local is: 

http://localhost:54321/auth/v1/callback

OAuth Works Locally but Not in Production

Check that: 1. Production OAuth credentials are set in Supabase Dashboard (not just config.toml) 2. Callback URL in OAuth provider matches Supabase project URL