If you've tried to add Google OAuth to a SPA or a Next.js app, you've probably run into the same friction: Google's documentation is comprehensive but dense, most tutorials are incomplete, and the parts that matter most — like exactly why you need PKCE, or what access_type=offline actually does — are buried.
This is the walkthrough I wish had existed when I built the auth layer for OvertimeIQ.
By the end you'll understand:
- Why PKCE exists and why it's the correct flow for SPAs
- How to implement the full code exchange from scratch (no OAuth libraries)
- How to get a
refresh_token(most tutorials quietly skip this) - How to do silent token refresh mid-session without any UI
- How to feed the Google
id_tokeninto Supabase for a second independent auth session
Why PKCE, and why not the alternatives
The implicit flow (the original OAuth approach for SPAs) returned the access token directly in the URL fragment after redirect. This has a known problem: browser history, referrer headers, and intermediate servers can all see that token. It's deprecated by the OAuth Security BCP. Don't use it.
Authorization code flow without PKCE requires a client secret — a value that must stay secret. In a server application, this is fine. In a SPA, there is no place to put a secret. It ships in your JavaScript bundle, which any user can read. This makes the "secret" worthless.
PKCE (Proof Key for Code Exchange) was designed specifically for this scenario. Instead of a static secret, you generate a fresh random value for every authorization request, derive a challenge from it, and prove you hold the original value when you exchange the code. There's nothing static to leak.
The PKCE flow, step by step
Here's what actually happens:
Browser Google
| |
|-- (1) Generate code_verifier -----------> |
|-- (2) Derive code_challenge |
|-- (3) Redirect to Google auth URL ------> |
| <-- (4) User consents --|
|<-- (5) Redirect with code --------------- |
|-- (6) Exchange code + verifier ---------> |
|<-- (7) Receive tokens ------------------- |
The code_verifier is a random string you generate in the browser and store in sessionStorage. The code_challenge is base64url(SHA256(verifier)) — a hash you can send to Google without revealing the original. When you exchange the code in Step 6, you send the original verifier. Google hashes it and verifies it matches what you sent in Step 3. An intercepted authorization code is useless without the verifier.
Implementation
Step 1: Generate the code verifier and challenge
// lib/auth.js
function generateRandomString(length) {
const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'
const array = new Uint8Array(length)
crypto.getRandomValues(array)
return Array.from(array).map(byte => chars[byte % chars.length]).join('')
}
export function generateVerifier() {
return generateRandomString(64) // Must be 43–128 chars
}
export async function generateChallenge(verifier) {
const encoder = new TextEncoder()
const data = encoder.encode(verifier)
const digest = await crypto.subtle.digest('SHA-256', data)
// base64url encode (different from regular base64 — no +, /, or = chars)
return btoa(String.fromCharCode(...new Uint8Array(digest)))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '')
}
Step 2: Build the authorization URL
export async function buildAuthURL() {
const verifier = generateVerifier()
const challenge = await generateChallenge(verifier)
// Store verifier for later — must survive the redirect
sessionStorage.setItem('pkce_verifier', verifier)
const params = new URLSearchParams({
client_id: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID,
redirect_uri: `${window.location.origin}/auth/callback`,
response_type: 'code',
scope: 'openid email profile https://www.googleapis.com/auth/drive.file',
code_challenge: challenge,
code_challenge_method: 'S256',
access_type: 'offline', // ← Required to receive a refresh_token
prompt: 'consent', // ← Required to actually receive the refresh_token (see below)
login_hint: invitedEmail, // ← Optional: pre-fills the email field
})
return `https://accounts.google.com/o/oauth2/v2/auth?${params}`
}
Critical: access_type=offline and prompt=consent
This is where most tutorials go wrong. access_type=offline tells Google you want a refresh token. But Google won't issue a new refresh token if the user has already authorized your app previously — it caches the consent. prompt=consent forces the consent screen to appear every time, which guarantees a fresh refresh token on every login.
If you omit either parameter, you'll get an access token (valid for ~1 hour) and nothing else. Your app will break when the token expires.
The downside: users see the Google consent screen on every login, even if they've used the app before. For most use cases, this is acceptable. For OvertimeIQ specifically, Drive access is central enough to the product that re-confirming consent feels appropriate rather than annoying.
Step 3: Handle the callback
After the user consents, Google redirects to /auth/callback?code=AUTHORIZATION_CODE. You exchange this code for tokens server-side. Even in a mostly client-side app, do this step on the server — the code exchange reveals your client ID and your verifier, and you want to receive the tokens in a server response, not a URL fragment.
In a Next.js app:
// app/auth/callback/route.js
import { NextResponse } from 'next/server'
export async function GET(request) {
const { searchParams } = new URL(request.url)
const code = searchParams.get('code')
const error = searchParams.get('error')
if (error || !code) {
return NextResponse.redirect(new URL('/auth-error', request.url))
}
// Get the verifier from the cookie (set during the redirect step)
// We'll cover how to pass this from browser to server below
const verifier = request.cookies.get('pkce_verifier')?.value
if (!verifier) {
return NextResponse.redirect(new URL('/auth-error', request.url))
}
const tokens = await exchangeCode(code, verifier, request)
// Clean up the verifier cookie
const response = NextResponse.redirect(new URL('/log', request.url))
response.cookies.delete('pkce_verifier')
// Store the access_token in a session cookie (short-lived)
response.cookies.set('g_access_token', tokens.access_token, {
httpOnly: true,
secure: true,
maxAge: 3600
})
// The refresh_token and id_token need further handling — see below
return response
}
async function exchangeCode(code, verifier, request) {
const response = await fetch('https://oauth2.googleapis.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
code,
client_id: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID,
client_secret: process.env.GOOGLE_CLIENT_SECRET, // Used server-side only
redirect_uri: `${new URL(request.url).origin}/auth/callback`,
grant_type: 'authorization_code',
code_verifier: verifier,
})
})
if (!response.ok) throw new Error('Token exchange failed')
return response.json()
// Returns: { access_token, refresh_token, id_token, expires_in, token_type }
}
Passing the verifier from browser to server callback: The verifier is generated in the browser, but the callback happens on the server. The cleanest approach is to store the verifier in a cookie before the redirect:
// In your sign-in button handler
export async function startSignIn() {
const verifier = generateVerifier()
const challenge = await generateChallenge(verifier)
// Set as a cookie so the server callback can read it
document.cookie = `pkce_verifier=${verifier}; path=/; secure; samesite=lax; max-age=300`
const authUrl = await buildAuthURL(verifier, challenge)
window.location.href = authUrl
}
The three tokens and what to do with each
After a successful exchange, you have three tokens:
access_token — Use this for all API calls (Google Drive, Google user info). Valid for ~1 hour. Store in sessionStorage or memory — never in localStorage (it's short-lived, and localStorage survives browser restarts). In an SSR app, an httpOnly cookie is the cleanest option.
refresh_token — Use this to get new access tokens when the current one expires. This is long-lived (until the user revokes access). For OvertimeIQ, I store it in the SQLite database on the user's Google Drive — it's as private as the rest of their data, and it never leaves their device or Drive storage.
id_token — A JWT containing the user's Google identity (sub, email, name, picture). Use this to bootstrap a Supabase session (see below), then discard it. It doesn't need to be persisted.
Feeding the id_token to Supabase
If you're using Supabase alongside Google OAuth (as OvertimeIQ does), you can use the Google id_token to create a Supabase session without running a separate OAuth flow:
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
)
// After token exchange — pass the id_token to Supabase
const { data, error } = await supabase.auth.signInWithIdToken({
provider: 'google',
token: googleIdToken,
})
This creates a Supabase session for the user. From this point, you have two independent auth lifecycles:
-
Google OAuth manages Drive access (via
access_token+refresh_token) - Supabase Auth manages app identity (user profile, subscription state, invite status) The two never need to communicate again after the initial bootstrap. If the Supabase session expires, the user re-logs in through the same Google flow that refreshes both.
Silent token refresh
The access token expires in one hour. You need to refresh it transparently, without interrupting the user.
// lib/auth.js
export async function refreshAccessToken() {
// Read the refresh token from SQLite settings
const refreshToken = db.getOne(
'SELECT google_refresh_token FROM settings WHERE id = 1'
)?.google_refresh_token
if (!refreshToken) {
// No refresh token — user needs to sign in again
redirectToSignIn()
return null
}
const response = await fetch('https://oauth2.googleapis.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
refresh_token: refreshToken,
client_id: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID,
grant_type: 'refresh_token',
})
})
if (!response.ok) {
// Refresh token revoked — show reconnect banner, don't break the app
showReconnectBanner()
return null
}
const { access_token } = await response.json()
// Store in memory (or sessionStorage) for Drive calls
setAccessToken(access_token)
return access_token
}
Schedule this to run ~55 minutes after login (5 minutes before the 1-hour expiry), and also intercept any Drive API 401 response as a signal to refresh immediately:
async function driveApiCall(url, options) {
let accessToken = getAccessToken()
let response = await fetch(url, {
...options,
headers: { ...options.headers, Authorization: `Bearer ${accessToken}` }
})
if (response.status === 401) {
// Token expired — try to refresh
accessToken = await refreshAccessToken()
if (!accessToken) return null // Couldn't refresh, user needs to reconnect
// Retry the original request with the new token
response = await fetch(url, {
...options,
headers: { ...options.headers, Authorization: `Bearer ${accessToken}` }
})
}
return response
}
If the refresh fails (user revoked access, network offline), show a persistent "Reconnect to Drive" banner. The app should remain fully usable — all data is in localStorage/SQLite, all features that don't need Drive continue to work. The banner gives the user a path back without breaking their workflow.
The login_hint trick
If you know in advance which email the user should be signing in with — for example, an invite system where you've emailed a specific address — you can pre-fill the Google consent screen:
const params = new URLSearchParams({
// ... other params
login_hint: 'invited-user@gmail.com'
})
This doesn't lock the user into that email — Google still lets them choose a different account — but it surfaces the correct account first. For an invite-only app, this significantly reduces the chance of a user signing in with the wrong Google account and then wondering why their invite doesn't work.
Common mistakes
Missing access_type=offline: You'll get an access token, no refresh token. Your app breaks after 1 hour.
Missing prompt=consent: You'll get a refresh token on the first login but not on subsequent logins (Google caches the consent). If a user signs out and signs back in, they lose the ability to silently refresh tokens.
Storing the access token in localStorage: It's short-lived, so there's minimal security benefit to persisting it across sessions. sessionStorage or memory is fine. If you need it to survive page refreshes, store the refresh token instead and get a fresh access token on load.
Validating the id_token client-side: You can decode a JWT without verification (base64 decode the payload), but you shouldn't trust it for access control without verifying the signature. Use Supabase's signInWithIdToken or Google's tokeninfo endpoint for validation.
Using the client secret in frontend code: The PKCE flow doesn't require a client secret. If you're adding one to your client-side code, you're either using the wrong flow or exposing something you shouldn't.
The scope choice
I'm using https://www.googleapis.com/auth/drive.file — the scope that grants access only to files created by this specific app. It cannot read or modify any other files in the user's Drive.
For most personal data applications, this is the right choice. It's the minimal permission footprint, it's easier to explain to users ("this app can only access files it created"), and it passes Google's app verification requirements more easily than broader scopes.
The alternative — https://www.googleapis.com/auth/drive — gives full Drive access. Don't use it unless you genuinely need it. Most apps don't.
This is part of an ongoing series on building OvertimeIQ — a personal overtime tracker where your data lives on your own Google Drive. The previous article in the series covers the SQLite-in-browser setup and Google Drive sync in detail. The first article covers the overall architecture.
