Google OAuth Setup

1. Create / choose a Google Cloud project#

1. 1

   Open console.cloud.google.com

   Open the console, top-left project selector → NEW PROJECT. Name it e.g. saas-starter-kit, keep the default location, and Create.

   

2. OAuth consent screen (Google Auth Platform)#

Google moves this screen's layout now and then. Depending on when you open the console it lives under “APIs & Services → OAuth consent screen”, or under “Google Auth Platform → Branding / Audience”. The fields are the same regardless of layout.

1. 1

   Choose the user type (audience)

   “External” is the right choice for a starter kit you intend to sell or deploy publicly — any Gmail address can sign in. “Internal” appears only inside a paid Google Workspace organization and lists your own domain users exclusively; pick it only if you deploy to your own company's Workspace.

2. 2

   App name and support email

   Enter the application name shown to users at sign-in (e.g. “My SaaS App”) and a support/development contact email — buyers should put their own address here, not the seller's.

3. 3

   Authorized domains (when required)

   “localhost” does not go here. For production add your deployed domains (e.g. yourapp.com). In publishing/testing with only local hosts you may often skip this field.

4. 4

   Add test users while in Testing mode

   A consent screen in “Testing” status only admits accounts listed in Test users. Add the Google address you will log in with, or you will meet “Access blocked” with error 403: access_denied.

   

5. 5

   Scopes

   Default scope set (openid, userinfo.profile, userinfo.email) requires no extra configuration — the backend requests exactly those.

3. Create the OAuth client#

1. 1

   Credentials → Create Credentials → OAuth client ID

   In the left menu choose Credentials, click Create Credentials → “OAuth client ID”, and set Application type = Web application — this matches the backend implementation (a confidential web client using code + PKCE).

2. 2

   Authorized JavaScript origins

   Add the frontend origin WITHOUT any path: for local development http://localhost:3000 (or the tunnel domain). Google uses this list only as an extra guard for token requests made from browser JavaScript.

3. 3

   Authorized redirect URIs — must match GOOGLE_CALLBACK_URL exactly

   Add the backend callback path character-for-character (development): http://localhost:5000/api/v1/auth/google/callback\n\nNo trailing slash, no /google-callback spelling variant. backend/.env defines its own GOOGLE_CALLBACK_URL which POSTs the identical string with the authorization request — Google only allows redirect targets that appear here.

   

4. 4

   Create, then copy the credentials securely

   Click Create. A dialog shows the Client ID and Client Secret — copy both immediately and store them ONLY in backend/.env (or your secret manager later). Never paste them into issues, screenshots or chat.

5. 5

   Add the values to the backend environment

   Edit backend/.env — the backend validates the GOOGLE_* trio (any of them present as empty strings is tolerated by design, OAuth then reports “not configured”):

   GOOGLE_CLIENT_ID=your_google_client_id
   GOOGLE_CLIENT_SECRET=your_google_client_secret
   GOOGLE_CALLBACK_URL=http://localhost:5000/api/v1/auth/google/callback

4. Test the login flow#

1. Frontend running with NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1 in frontend/.env.local (restart the frontend after adding it).
2. Open http://localhost:3000/login → click Continue with Google.
3. Choose the test user on Google's account picker and accept the consent screen.
4. The browser then visits /auth/verify-otp. No session cookies are issued by the OAuth callback: a 6-digit code is emailed through Resend, and only entering that code creates the session and opens the dashboard. For an existing email, the Google account is LINKED to that user; for a new address the account is created after the OTP succeeds.

If the first attempt shows Google “Access blocked”, re-check consent-screen test users — that is a Google-side audience rule, not a kit bug.

5. Production domains and redirect URIs#

Google treats each scheme://host:port as distinct. When you deploy: add the production origins (https://yourapp.com) and production redirect URI (https://api.yourapp.com/api/v1/auth/google/callback) as NEW entries alongside the localhost ones, update backend/.env GOOGLE_CALLBACK_URL and FRONTEND_URL to the production values, and set the consent screen's authorized domain. Localhost entries do not need removal.

OAuth Error Reference#

Completion Checklist#

Tick each row after you verified it — progress is remembered in your browser (localStorage, item ids only, no personal data). If anything fails, the Troubleshooting page lists verified fixes for each error.