Google OAuth

This guide explains how to set up Google OAuth for user authentication in StarterKitPro using Auth.js v5.

Prerequisites

• Database Setup: Ensure you have configured and migrated your database, as Auth.js requires an adapter (like Prisma) to store user and account information. See the Database Setup documentation.

1. Environment Variables

Add the following variables to your .env.local file. Create the file if it doesn't exist.

# Auth.js Core Variables (You might already have these)
AUTH_URL=http://localhost:3000 # Or your production URL like https://your-site.com
AUTH_SECRET= # Generate a strong secret: openssl rand -base64 32
 
# Google Provider Variables (Use these specific names for auto-configuration)
AUTH_GOOGLE_ID=YOUR_GOOGLE_CLIENT_ID
AUTH_GOOGLE_SECRET=YOUR_GOOGLE_CLIENT_SECRET

• AUTH_SECRET: A random string used to encrypt JWTs and session cookies. Use the command openssl rand -base64 32 in your terminal to generate a strong one. Do not commit this file.
• AUTH_URL: Set this to your canonical URL (e.g., http://localhost:3000 for development, https://your-site.com for production).
• Replace the AUTH_GOOGLE_ placeholders with the actual credentials obtained from the Google Cloud Console in the next steps.

2. Google Cloud Console Setup

You need to create a Google Cloud project and configure OAuth credentials.

1. Create/Select Project: Go to the Google Cloud Console and create a new project or select an existing one.
2. APIs & Services: Navigate to "APIs & Services" > "Credentials".
3. Configure Consent Screen:
   • Click [Configure Consent Screen].
   • Choose External unless your app is only for users within your Google Workspace organization.
   • Fill in the required information (App name, User support email, Developer contact information).
   • Scopes: Click [Add or Remove Scopes]. Add the following scopes:
     • .../auth/userinfo.email (Read user's email address)
     • .../auth/userinfo.profile (See basic profile info)
     • openid (Required for OIDC)
   • Click Update.
   • Test Users: Add your own Google account email address as a test user while the app is in "Testing" mode.
   • Review the summary and click [Back to Dashboard].
4. Create OAuth Credentials:
   • Go back to "Credentials".
   • Click [+ Create Credentials] > [OAuth client ID].
   • Select Web application as the Application type.
   • Give it a name (e.g., "StarterKitPro Web App").
   • Authorized JavaScript origins: Add your development and production URLs.
     • http://localhost:3000 (or your local dev port)
     • https://your-domain.com (replace with your actual domain)
   • Authorized redirect URIs: This is where Google sends the user back after authentication. It must match the pattern /api/auth/callback/[provider].
     • http://localhost:3000/api/auth/callback/google
     • https://your-domain.com/api/auth/callback/google
   • Click [Create].
5. Copy Credentials: A modal will appear showing your Client ID and Client Secret. Copy these and paste them into your .env.local file as AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET.

4. Testing and Verification

• Local Testing: Restart your development server (npm run dev). You should now be able to sign in using the Google option on your local machine (http://localhost:3000).
• Production & Verification:
  • For your live application (https://your-domain.com), Google login will work initially but display an "unverified app" screen until you complete the verification process.
  • Go back to the [OAuth Consent Screen] page in Google Cloud Console.
  • Click [Publish App] and follow the steps.
  • You will likely need to verify ownership of your domain (https://your-domain.com) using Google Search Console.
  • Google will review your application, which can take several days. They may email you for more information. Prepare your Terms of Service and Privacy Policy pages.

You can now use Google for authentication in StarterKitPro!