Sign in with Google (OAuth)

Four parties: user, browser, your server, Google

What happens when someone clicks "Sign in with Google":

1. Your server redirects the browser to a Google URL with your client ID and a callback URL.
2. Google asks the user "do you want to let this app see your email?" The user clicks Allow.
3. Google redirects the browser back to your callback URL with a temporary authorization code.
4. Your server takes that code, POSTs it back to Google with your client secret, and gets back an ID token — a JWT containing the user's email, name, Google user ID, etc.
5. Your server verifies the JWT signature (proving it actually came from Google), creates a session, sets a cookie, redirects to your app.

The client secret never leaves your server. The authorization code is one-time-use. The session cookie is what your app uses going forward. Each piece has a specific security property.

console.cloud.google.com

Sign in to the Google Cloud Console. Create a new project (top-left "Select a project" → "New project"). Name it after your app. The project is the container for everything related to it on Google Cloud.

You don't need to enable billing for OAuth — only paid Google APIs need billing. Sign-in is free.

What users see when granting permission

In the project, APIs & Services → OAuth consent screen. Pick External user type (Internal is only for Google Workspace domains). Configure:

• App name: what users see ("Sign in to AppName").
• User support email: a real address you check.
• Authorized domains: your production domain (e.g., yourapp.com).
• Developer contact email: usually you.
• Scopes: for basic sign-in, request email, profile, and openid. Don't request more than you need.

Initially the app is in Testing status — only listed test users can sign in. You can add up to 100 test users in the OAuth consent screen settings. For production, you'll move to "In Production" (Step 8).

The client ID and client secret

APIs & Services → Credentials → Create Credentials → OAuth client ID.

• Application type: Web application.
• Name: internal; users don't see this.
• Authorized JavaScript origins: your app's URLs. For dev: http://localhost:3000. For production: https://yourapp.com. Add all environments.
• Authorized redirect URIs: where Google sends the code back. Typically http://localhost:3000/api/auth/callback/google for dev, https://yourapp.com/api/auth/callback/google for production. Must match exactly — trailing slashes, http vs https, port numbers all matter.

Click Create. Google shows your Client ID (long string ending in .apps.googleusercontent.com) and Client Secret (shorter, starts with GOCSPX-). Copy both into your backend's env file:

GOOGLE_CLIENT_ID=...apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

NextAuth / Auth.js / Passport / clerk — pick one

You can implement OAuth manually with HTTP calls, but you almost certainly shouldn't. The standard libraries handle the state parameter (anti-CSRF), JWT verification, session management, and dozens of edge cases. For most stacks:

• Next.js: next-auth (now Auth.js). Configure providers in one file.
• Express / Node: Passport.js with the passport-google-oauth20 strategy.
• Django: django-allauth.
• Rails: omniauth + omniauth-google-oauth2.
• Anything modern: Clerk, Auth0, Supabase Auth — auth-as-a-service that handles Google plus a dozen other providers.

For Auth.js in Next.js, the configuration is roughly:

import GoogleProvider from "next-auth/providers/google";

export const authOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    }),
  ],
};

That plus the standard Auth.js route handler is enough. Twenty lines of code; a working sign-in button.

First sign-in creates; subsequent sign-ins look up

When the OAuth callback succeeds, you have a verified email and a Google user ID. The logic in your handler:

1. Look up a user in your DB by Google ID. If they exist, that's the session user.
2. If not, check by email. If they exist, link the Google account to that user (this handles "they signed up with email/password first, then later switched to Google").
3. If neither matches, create a new user record with the email, name, and Google ID.

Store the Google user ID separately from the email. Email addresses can theoretically change at Google; the Google ID never does.

Use the test-user list while developing

With the consent screen in Testing status, only emails added to the Test Users list can sign in. Add your own Google account; you can now click "Sign in with Google" on your local dev server and complete the flow.

Google's first-time consent screen shows your app name, the scopes requested, and a "This app isn't verified" warning (in Testing mode). Click "Advanced → Go to AppName (unsafe)" to proceed. Real users won't see this once you publish; until then, every test user sees it.

The "unsafe" warning is for testing only

To remove the unverified-app warning for real users, submit your app for verification. From the OAuth consent screen, click Publish App → Submit for verification. Google reviews your homepage, privacy policy, and the scopes you've requested.

For basic scopes (email, profile, openid) the verification is automatic — usually instant. For sensitive scopes (Gmail access, Drive access, etc.) verification can take weeks and requires a security assessment. Stick to basic scopes unless you have a real product reason for more.

Once verified, "unsafe" goes away, the user-cap of 100 testers lifts, and any Google user worldwide can sign in.