Authentication Guide

Learn how to enable and configure authentication methods in your Next.js and Supabase boilerplate.

This boilerplate supports:

• Email & password
• Magic links (passwordless)
• OAuth providers (Google, GitHub, etc.)

Overview

Your boilerplate uses Supabase Auth for secure, scalable authentication.
All auth flows are pre-integrated with the front-end UI, server-side sessions, and database policies.

1. Email & Password Authentication

Perfect for: Traditional login with credentials.

Enable in Supabase Dashboard

1. Go to Authentication → Providers in your Supabase project.
2. Find Email and toggle it ON.
3. Configure:
   • ✅ Enable email confirmations
   • ✅ Enable email change confirmations
   • Site URL:
     • Local Development: Set to http://localhost:3000
     • Cloud/Deployed: Set to your deployed domain (e.g., https://your-app.vercel.app)

💡 Ensure the Site URL matches your environment to avoid redirect errors.

Email Templates

Email templates are located in /supabase/templates/ in your repo.
To customize:

1. Open Supabase Dashboard → Authentication → Email → Templates.
2. Copy the relevant template from your project and paste it into the dashboard.
3. Modify the HTML or plain text as needed.
4. Save changes.

💡 Test email templates thoroughly in both local and cloud environments to ensure links and branding are correct.

2. Magic Link (Passwordless)

Perfect for: Simplified signup/login without remembering passwords.

Enable in Supabase Dashboard

1. Go to Authentication → Providers → Email.
2. Configure:
   • ✅ Enable email confirmations
   • ✅ Enable email change confirmations
   • Site URL:
     • Local Development: http://localhost:3000
     • Cloud/Deployed: Your deployed domain (e.g., https://your-app.vercel.app)
3. Save settings.

How It Works in This Boilerplate

• Users enter their email in the sign-in form.
• Supabase sends a link to their inbox.
• Clicking the link automatically signs them in and redirects them to your app.
• The redirect URL is determined by the Site URL set in the Supabase dashboard.

💡 For local testing, ensure your local server is running at http://localhost:3000. For cloud, verify the deployed URL is correctly set.

3. OAuth Providers

Perfect for: Fast sign-ups using accounts from Google, GitHub, etc.

Enabling an OAuth Provider

1. Go to Authentication → Providers in Supabase.
2. Choose a provider (e.g., Google, GitHub, LinkedIn).
3. Enter the Client ID and Client Secret from the provider’s developer console.

URL Configuration

Set the Authorized redirect URI in the provider’s developer console:

• Local Development: http://localhost:3000/auth/callback
• Cloud/Deployed: https://your-app.vercel.app/auth/callback

Example: Google OAuth

1. Visit Google Cloud Console.
2. Create a project → Enable OAuth 2.0 Client IDs.
3. Set Authorized redirect URI:
   • Local Development: http://localhost:3000/auth/callback
   • Cloud/Deployed: https://your-app.vercel.app/auth/callback
4. Click Create.
5. Copy the Client ID and Client Secret and paste them into the Google provider section in your Supabase dashboard.

Local OAuth Setup with toml.yml

For local development, configure OAuth by adding provider details to a toml.yml file in your project root:

1. Create a toml.yml file if it doesn’t exist.
2. Add the OAuth provider configuration, for example:

[auth.external.google]
enabled = true
client_id = "env(GOOGLE_AUTH_CLIENT_ID)"
# DO NOT commit your OAuth provider secret to git. Use environment variable substitution instead:
secret = "env(GOOGLE_AUTH_CLIENT_SECRET)"
# Overrides the default auth redirectUrl.
redirect_uri = "http://127.0.0.1:56321/auth/v1/callback"
# Overrides the default auth provider URL. Used to support self-hosted gitlab, single-tenant Azure,
# or any other third-party OIDC providers.
url = ""

3. Ensure your Next.js app loads the toml.yml configuration for local OAuth flows. Update your Supabase client initialization to reference these values if necessary.
4. Restart your local server (npm run dev or yarn dev) after updating toml.yml.

💡 Ensure the redirect_uri in toml.yml matches the Authorized redirect URI in the provider’s console and Supabase settings.

4. Environment Variables

For OAuth, add provider credentials to your .env.local (for local development) and .env (for cloud deployment) files:

# Supabase keys (already set from setup guide)
SUPABASE_URL=your-supabase-url
SUPABASE_ANON_KEY=your-supabase-anon-key

# OAuth Example - Google
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Local Development

• Create a .env.local file in the root of your project.
• Add the above variables with values specific to your local setup.
• Ensure your Next.js app is restarted after updating .env.local.

Cloud Deployment

• Add the same variables to your deployment platform’s environment variables (e.g., Vercel, Netlify).
• For Vercel:
  1. Go to your project in the Vercel dashboard.
  2. Navigate to Settings → Environment Variables.
  3. Add each variable (SUPABASE_URL, SUPABASE_ANON_KEY, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET).
  4. Redeploy your app to apply changes.

💡 Keep environment variables secure and never commit them to version control. Use .gitignore for .env.local, .env, and toml.yml.

5. Testing Authentication

Local Testing

1. Run your Next.js app locally with npm run dev or yarn dev.
2. Navigate to http://localhost:3000 and test:
   • Email & password login/signup.
   • Magic link flow (check your inbox).
   • OAuth provider buttons (e.g., Google, GitHub).
3. Verify redirects and session persistence, ensuring the toml.yml configuration is correctly applied for OAuth.

Cloud Testing

1. Deploy your app to your hosting platform (e.g., Vercel).
2. Test the same flows as above on the deployed URL (e.g., https://your-app.vercel.app).
3. Ensure email links and OAuth redirects point to the correct deployed URL.
4. Check Supabase logs (Authentication → Logs) for any errors.

💡 Use Supabase’s Authentication → Users section to monitor user signups and debug issues in both environments.