Google OAuth + Next.js + Supabase: Complete Setup Guide

Google OAuth drives 72% of OpenMyPro's sign-ups because it eliminates the biggest friction point in healthcare: creating yet another username and password. Here is the complete setup for Google OAuth with Next.js and Supabase, including the PKCE flow, callback handling, and production configuration that handles independent founders.

Why Google OAuth for Healthcare

Healthcare patients already have too many accounts. Insurance portals, patient portals for each provider, pharmacy accounts, lab results portals — the last thing they want is another password to remember. Google OAuth lets patients sign in with one click using an account they already have open in their browser.

The conversion impact is massive. Our A/B test showed that removing the email/password form and leading with Google OAuth increased sign-up conversion by 34%. When we added the option back as a secondary method, the Google OAuth rate stabilized at 72% of all sign-ups.

Supabase Auth Google Provider Setup

Supabase supports Google OAuth natively through its Auth configuration. In the Supabase dashboard, enable the Google provider, enter the OAuth client ID and secret from Google Cloud Console, and configure the redirect URL. Supabase handles the entire OAuth flow — token exchange, user creation, session management — without custom server code.

The Supabase client library provides a signInWithOAuth method that redirects the user to Google's consent screen. After the user approves, Google redirects back to your callback URL with an authorization code. Supabase exchanges this code for tokens, creates or updates the user record, and establishes a session.

PKCE Flow for Security

We use the PKCE (Proof Key for Code Exchange) flow instead of the implicit flow. PKCE prevents authorization code interception attacks by binding the code to the client that requested it. When initiating the OAuth flow, the client generates a random code verifier and sends its hash (code challenge) with the authorization request. The callback includes the original verifier, which Supabase validates against the hash.

Next.js handles PKCE automatically through the @supabase/ssr package. The code verifier is stored in an HTTP-only cookie during the OAuth redirect, ensuring it survives the page navigation to Google and back. This is more secure than storing it in localStorage or sessionStorage, which are vulnerable to XSS attacks.

The Auth Callback Route

The callback route is a critical piece. After Google redirects back with the authorization code, our /auth/callback route handler exchanges the code for a session using Supabase's exchangeCodeForSession method. This server-side handler runs on the server, keeping the code exchange secure and setting HTTP-only session cookies.

Error handling in the callback is important for user experience. If the code exchange fails — expired code, invalid state, network error — we redirect to the sign-in page with an error parameter that displays a user-friendly message. We never show raw OAuth errors to patients.

Session Management

Supabase sessions use two tokens: an access token (JWT) with a 1-hour expiration and a refresh token with a 7-day expiration. The @supabase/ssr package manages these tokens in HTTP-only cookies, automatically refreshing the access token when it expires. Users stay signed in for up to 7 days without re-authenticating.

Our Next.js middleware reads the session cookie on every request to protected routes. If the access token is expired, middleware calls supabase.auth.getSession() which automatically uses the refresh token to get a new access token. This happens transparently — the user never sees a loading state or sign-in redirect unless their refresh token has also expired.

Production Configuration

In production, several additional configurations are critical. The Google OAuth consent screen must be set to "production" mode to allow any Google account to sign in (vs testing mode which limits to test users). The authorized redirect URI must exactly match your production callback URL including https and www if applicable. Rate limiting on the callback endpoint prevents token exchange abuse.

We also configure the OAuth scope to request only the minimum information needed: email and profile. We do not request access to Google Drive, Calendar, or any other Google service. The minimum necessary principle from HIPAA applies to OAuth scopes too — only request what you actually need.

User Profile Enrichment

When a new user signs in via Google OAuth, we receive their name, email, and profile photo URL. We store these in the Supabase user metadata and use them to pre-populate the patient profile. This reduces the profile completion steps from five fields to two (adding phone number and location preference), further reducing onboarding friction.