Adding Login Options

StarterApp arrives with two sign-in paths:

• Google OAuth (enabled when credentials are present)
• Username + password (enabled by default, can be switched off)

This page explains how to configure those options and extend the stack when you need additional providers.

Current setup at a glance

• convex/lib/auth.ts reads environment variables and enables OAuth providers when both the client ID and secret exist.
• The dashboard sign-in page checks those same flags to decide which buttons to show.
• Username/password auth can be disabled globally by setting DISABLE_USERNAME_PASSWORD_AUTH=true.

Enabling Google sign-in

1. Create a Google OAuth client (Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID).

2. Add the callback URLs:

   • http://localhost:3000/api/auth/callback/google
   • Your production domain, e.g. https://app.example.com/api/auth/callback/google

3. Set the environment variables (both locally and in production):

   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   DASHBOARD_BASE_URL=https://app.example.com

If either value is missing, the Google button is hidden and the BetterAuth handler does not attempt to use the provider.

Managing username & password

• Enabled by default and uses BetterAuth’s built-in hashing and validation.
• Set DISABLE_USERNAME_PASSWORD_AUTH=true to remove the form and skip the credential plugin for internal demos or OAuth-only environments.
• Password reset emails currently log a URL to the server console. Replace that log with your email provider before shipping a customer-facing product.

Extending to additional providers

Need GitHub, Azure AD, or anything else? Follow the same pattern:

1. Register the OAuth app and copy the client credentials.
2. Add new environment variables (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, etc.).
3. Update the computeSocialProviders helper in convex/lib/auth.ts to include the new provider when both values exist.
4. Confirm the sign-in page displays the new option and test the full flow end-to-end.

Because BetterAuth handles the heavy lifting, you rarely need to touch the client components beyond adjusting button labels if you want a custom message.

Preflight checklist before launch

• Google credentials present in every environment that should surface the Google button.
• DASHBOARD_BASE_URL and callback URLs use https:// in production.
• DISABLE_USERNAME_PASSWORD_AUTH set appropriately for the experience you want.
• Any additional providers are reflected in both environment configuration and computeSocialProviders.
• Password reset email handler replaced with your delivery service if password auth remains enabled.

Environment variable reference

Related documentation