{"id":196,"date":"2026-06-17T21:02:42","date_gmt":"2026-06-17T21:02:42","guid":{"rendered":"https:\/\/shattered.io\/it\/2026\/06\/17\/oauth2-openid-connect-nodejs\/"},"modified":"2026-06-17T21:06:56","modified_gmt":"2026-06-17T21:06:56","slug":"oauth2-openid-connect-nodejs","status":"publish","type":"post","link":"https:\/\/shattered.io\/it\/2026\/06\/17\/oauth2-openid-connect-nodejs\/","title":{"rendered":"OAuth 2.0 e OpenID Connect in Node.js: 12 Step, 30 Min [2026]"},"content":{"rendered":"\n

Ogni volta che un utente clicca su “Accedi con Google” o “Accedi con GitHub”, entra in azione OAuth 2.0. Il protocollo gestisce miliardi di autenticazioni ogni giorno, ma implementarlo correttamente in Node.js richiede pi\u00f9 di una semplice installazione di passport<\/code>. Bisogna capire PKCE, la rotazione dei refresh token, il pinning degli algoritmi e la corretta gestione dei cookie. Questa guida copre tutti e 12 gli step in 30 minuti.<\/p>\n\n\n\n

Cos’\u00e8 OAuth 2.0 e Perch\u00e9 Usarlo<\/h2>\n\n\n\n

OAuth 2.0 (RFC 6749) \u00e8 un framework di autorizzazione che permette a un’applicazione di ottenere accesso limitato a un account utente su un servizio di terze parti, senza che l’utente condivida le proprie credenziali. OpenID Connect (OIDC) \u00e8 uno strato di identit\u00e0 costruito sopra OAuth 2.0: aggiunge l’autenticazione vera e propria tramite un ID token<\/em> in formato JWT.<\/p>\n\n\n\n

La differenza pratica: OAuth 2.0 risponde alla domanda “posso accedere a questa risorsa?”, OIDC risponde a “chi sei?”. Nelle applicazioni moderne, i due protocolli vengono usati insieme. L’authorization server<\/em> (Google, GitHub, Keycloak, Auth0) emette un access token<\/em> per le API e un ID token<\/em> per l’identit\u00e0.<\/p>\n\n\n\n

Il flusso pi\u00f9 sicuro nel 2026 \u00e8 l’Authorization Code Flow con PKCE<\/strong> (RFC 7636). PKCE, pronunciato “pixy”, risolve il rischio di intercettazione del codice di autorizzazione nei client pubblici (SPA, app mobile), rendendo ogni richiesta crittograficamente legata a un verificatore segreto generato localmente. RFC 9700 (OAuth 2.0 Security Best Current Practice) pubblicato nel 2025 raccomanda PKCE per tutti i tipi di client, senza eccezioni.<\/p>\n\n\n\n

\n\n
Flusso OAuth 2.0<\/th>Caso d’uso<\/th>PKCE richiesto<\/th>Livello di sicurezza<\/th><\/tr><\/thead>\n
Authorization Code + PKCE<\/td>Web app, SPA, mobile<\/td>Si<\/td>Alto<\/td><\/tr>\n
Authorization Code (senza PKCE)<\/td>Web app server-side legacy<\/td>No (sconsigliato)<\/td>Medio<\/td><\/tr>\n
Client Credentials<\/td>M2M, microservizi<\/td>No<\/td>Alto (per M2M)<\/td><\/tr>\n
Device Authorization<\/td>Smart TV, CLI<\/td>No<\/td>Medio<\/td><\/tr>\n
Implicit Flow<\/td>Deprecato dal 2019<\/td>N\/A<\/td>Basso (non usare)<\/td><\/tr>\n<\/tbody>\n<\/table><\/figure>\n\n\n\n

Prerequisiti e Versioni<\/h2>\n\n\n\n

Prima di iniziare, verifica di avere le versioni corrette installate. Il progetto usa Node.js LTS: la versione 22.x (LTS attivo) o 24.x (LTS corrente). A gennaio 2026 il team Node.js ha rilasciato patch di sicurezza per tutte le linee attive, risolvendo 2 vulnerabilit\u00e0 ad alta severit\u00e0 per versione, tra cui CVE-2026-21637 (HashDoS in V8 tramite collisioni hash su stringhe integer-like). Il 17 giugno 2026, data di pubblicazione di questa guida, \u00e8 uscita un’ulteriore tornata di patch per 26.x, 24.x e 22.x.<\/p>\n\n\n\n

node -v      # >= 20.20.2 oppure >= 22.22.2 oppure >= 24.14.1\nnpm -v       # >= 10.x\n<\/code><\/pre>\n\n\n\n
Pacchetti necessari con versioni minime:<\/p>\n\n\n\n
\n\n
Pacchetto<\/th>Versione<\/th>Scopo<\/th><\/tr><\/thead>\n
express<\/td>^5.x<\/td>Framework HTTP<\/td><\/tr>\n
passport<\/td>^0.7.x<\/td>Middleware autenticazione<\/td><\/tr>\n
passport-google-oauth20<\/td>^2.0.x<\/td>Strategy OAuth2 Google<\/td><\/tr>\n
express-session<\/td>^1.18.x<\/td>Gestione sessioni lato server<\/td><\/tr>\n
connect-redis<\/td>^8.x<\/td>Store sessioni Redis<\/td><\/tr>\n
jose<\/td>^6.x<\/td>Verifica JWT e ID token OIDC<\/td><\/tr>\n
dotenv<\/td>^16.x<\/td>Variabili d’ambiente<\/td><\/tr>\n
crypto (built-in)<\/td>N\/A<\/td>Generazione PKCE code verifier<\/td><\/tr>\n<\/tbody>\n<\/table><\/figure>\n\n\n\n
Ti serve anche un account Google Cloud<\/strong> con un progetto configurato in Google Cloud Console e le credenziali OAuth2 (Client ID e Client Secret). La sezione Step 3 mostra la procedura esatta. Per i test locali, puoi usare anche GitHub come provider alternativo con il pacchetto passport-github2<\/code>, che segue lo stesso schema di configurazione.<\/p>\n\n\n\n
Panoramica del Flusso Authorization Code con PKCE<\/h2>\n\n\n\n
Prima di scrivere codice, capire il flusso evita molti errori di implementazione. Con PKCE, la sequenza tra browser, server Node.js e authorization server segue 6 passaggi distinti:<\/p>\n\n\n\n
    \n
  1. Il server genera un code_verifier<\/code> casuale (32 byte, 256 bit di entropia) e ne calcola il code_challenge<\/code> con SHA-256.<\/li>\n
  2. Il server reindirizza l’utente all’authorization server inviando code_challenge<\/code> e code_challenge_method=S256<\/code>.<\/li>\n
  3. L’utente si autentica e l’authorization server rilascia un codice di autorizzazione monouso.<\/li>\n
  4. Il browser invia il codice di autorizzazione al server Node.js tramite il redirect URI.<\/li>\n
  5. Il server Node.js scambia il codice con i token inviando anche il code_verifier<\/code> originale.<\/li>\n
  6. L’authorization server verifica il verifier contro il challenge e rilascia access_token<\/code>, refresh_token<\/code> e (con OIDC) id_token<\/code>.<\/li>\n<\/ol>\n\n\n\n
    Il punto critico: il code_verifier<\/code> non lascia mai il server. Se un attaccante intercetta il codice di autorizzazione al passo 3, non pu\u00f2 scambiarlo senza il verifier. Questo neutralizza il classico attacco CSRF sull’endpoint di callback OAuth2.<\/p>\n\n\n\n
    Step 1: Inizializza il Progetto Node.js<\/h2>\n\n\n\n
    Crea una cartella per il progetto e inizializza npm. Il progetto usa ES modules per avere import<\/code>\/export<\/code> nativi, coerenti con le best practice Node.js 2026. CommonJS (require()<\/code>) funziona ancora ma molti pacchetti moderni sono ora ESM-only.<\/p>\n\n\n\n
    mkdir oauth2-oidc-nodejs && cd oauth2-oidc-nodejs\nnpm init -y\n# Abilita ES modules\nnpm pkg set type=module\n<\/code><\/pre>\n\n\n\n
    Crea la struttura del progetto. Separare le route dalle utility di autenticazione facilita i test e riduce il coupling:<\/p>\n\n\n\n
    oauth2-oidc-nodejs\/\n\u251c\u2500\u2500 src\/\n\u2502   \u251c\u2500\u2500 app.js           # Entry point Express\n\u2502   \u251c\u2500\u2500 auth\/\n\u2502   \u2502   \u251c\u2500\u2500 passport.js  # Configurazione Passport e strategy\n\u2502   \u2502   \u2514\u2500\u2500 pkce.js      # Utility PKCE per provider custom\n\u2502   \u251c\u2500\u2500 middleware\/\n\u2502   \u2502   \u2514\u2500\u2500 requireAuth.js\n\u2502   \u2514\u2500\u2500 routes\/\n\u2502       \u251c\u2500\u2500 auth.js      # \/auth\/google, \/auth\/google\/callback, \/auth\/logout\n\u2502       \u2514\u2500\u2500 profile.js   # Route protette\n\u251c\u2500\u2500 .env                 # Non committare mai\n\u251c\u2500\u2500 .env.example         # Template pubblico senza segreti\n\u2514\u2500\u2500 package.json\n<\/code><\/pre>\n\n\n\n
    Step 2: Installa le Dipendenze<\/h2>\n\n\n\n
    Installa tutti i pacchetti in un unico comando, poi esegui npm audit<\/code> subito dopo. Nell’ecosistema Node.js del 2026, le dipendenze di terze parti rimangono la principale superficie di attacco per le supply chain. Il blog ha gi\u00e0 documentato come nel 2025 oltre 1,2 milioni di pacchetti malevoli siano stati caricati su npm.<\/p>\n\n\n\n
    npm install express passport passport-google-oauth20   express-session connect-redis jose dotenv helmet\n\nnpm install --save-dev nodemon\n\n# Verifica zero vulnerabilit\u00e0 critiche prima di procedere\nnpm audit\n<\/code><\/pre>\n\n\n\n
    Se npm audit<\/code> segnala vulnerabilit\u00e0 high o critical nelle dipendenze dirette, risolvi prima di andare avanti. Per le vulnerabilit\u00e0 nelle dipendenze transitive, valuta se il percorso di codice \u00e8 effettivamente raggiungibile nella tua applicazione. Il comando npm audit --json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d[‘metadata’][‘vulnerabilities’])\"<\/code> mostra il conteggio per severit\u00e0.<\/p>\n\n\n\n
    Step 3: Configura le Credenziali OAuth2 su Google Cloud<\/h2>\n\n\n\n
    Vai su console.cloud.google.com<\/a>, crea un progetto nuovo (o usa uno esistente), poi segui questo percorso: API e servizi > Credenziali > Crea credenziali > ID client OAuth 2.0<\/strong>. Seleziona “Applicazione web”. In “URI di reindirizzamento autorizzati” aggiungi i due endpoint:<\/p>\n\n\n\n
    http:\/\/localhost:3000\/auth\/google\/callback   # sviluppo locale\nhttps:\/\/tuodominio.com\/auth\/google\/callback  # produzione\n<\/code><\/pre>\n\n\n\n
    Scarica il JSON con Client ID e Client Secret. Crea il file .env<\/code> nella root del progetto:<\/p>\n\n\n\n
    GOOGLE_CLIENT_ID=123456789-abcdefghijk.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxx\nSESSION_SECRET=una_stringa_casuale_di_almeno_32_caratteri_generata_con_openssl_rand\nREDIS_URL=redis:\/\/localhost:6379\nBASE_URL=http:\/\/localhost:3000\nNODE_ENV=development\n<\/code><\/pre>\n\n\n\n
    Pitfall critica:<\/strong> il file .env<\/code> deve essere nel .gitignore<\/code> prima del primo commit. Una chiave OAuth2 esposta su GitHub viene rilevata dai bot entro minuti e porta alla revoca forzata delle credenziali da parte di Google. Aggiungi subito: echo \".env\" >> .gitignore<\/code>. Genera il SESSION_SECRET con openssl rand -hex 32<\/code>: serve almeno 256 bit di entropia.<\/p>\n\n\n\n
    Step 4: Crea il Server Express con Session Store Redis<\/h2>\n\n\n\n
    Il session store in memoria di Express funziona solo in sviluppo: perde tutte le sessioni al riavvio del server e produce memory leak in produzione. Redis risolve entrambi i problemi e scala orizzontalmente per pi\u00f9 istanze. Il file src\/app.js<\/code>:<\/p>\n\n\n\n
    import 'dotenv\/config';\nimport express from 'express';\nimport helmet from 'helmet';\nimport session from 'express-session';\nimport { createClient } from 'redis';\nimport { RedisStore } from 'connect-redis';\nimport passport from 'passport';\nimport '.\/auth\/passport.js';\nimport authRouter from '.\/routes\/auth.js';\nimport profileRouter from '.\/routes\/profile.js';\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\n\/\/ Sicurezza header HTTP con Helmet\napp.use(helmet({\n  contentSecurityPolicy: {\n    directives: {\n      defaultSrc: [\"'self'\"],\n      scriptSrc: [\"'self'\"],\n      connectSrc: [\"'self'\", 'https:\/\/accounts.google.com'],\n      frameSrc: [\"'none'\"],\n      objectSrc: [\"'none'\"]\n    }\n  },\n  hsts: {\n    maxAge: 31536000,\n    includeSubDomains: true,\n    preload: true\n  }\n}));\n\n\/\/ Client Redis con gestione errori\nconst redisClient = createClient({ url: process.env.REDIS_URL });\nredisClient.on('error', (err) => console.error('Redis error:', err));\nawait redisClient.connect();\n\n\/\/ Sessione con Redis store\napp.use(session({\n  store: new RedisStore({ client: redisClient }),\n  secret: process.env.SESSION_SECRET,\n  resave: false,\n  saveUninitialized: false,\n  cookie: {\n    httpOnly: true,\n    secure: process.env.NODE_ENV === 'production',\n    sameSite: 'lax',\n    maxAge: 24 * 60 * 60 * 1000  \/\/ 24 ore\n  }\n}));\n\napp.use(express.json());\napp.use(express.urlencoded({ extended: false }));\napp.use(passport.initialize());\napp.use(passport.session());\n\napp.use('\/auth', authRouter);\napp.use('\/profile', profileRouter);\n\napp.get('\/', (req, res) => {\n  res.json({ authenticated: req.isAuthenticated(), user: req.user || null });\n});\n\napp.listen(PORT, () => console.log(`Server avviato su http:\/\/localhost:${PORT}`));\n<\/code><\/pre>\n\n\n\n
    Le tre flag del cookie, httpOnly<\/code>, secure<\/code> e sameSite<\/code>, lavorano in sinergia. httpOnly<\/code> impedisce a JavaScript (inclusi script XSS) di leggere il cookie di sessione. secure<\/code> garantisce che il cookie viaggi solo su HTTPS. sameSite: 'lax'<\/code> blocca le richieste cross-site non intenzionali senza rompere i link normali da email o siti esterni. In produzione con requisiti di sicurezza elevati, considera sameSite: 'strict'<\/code>, ma attenzione: rompe il reindirizzamento OAuth2 quando arriva da una pagina esterna.<\/p>\n\n\n\n
    Step 5: Configura Passport.js con Google OAuth2<\/h2>\n\n\n\n
    Passport.js usa il concetto di “strategy”: ogni provider ha la propria. La strategy GoogleStrategy<\/code> implementa l’intero flusso Authorization Code con PKCE. Il file src\/auth\/passport.js<\/code>:<\/p>\n\n\n\n
    import passport from 'passport';\nimport { Strategy as GoogleStrategy } from 'passport-google-oauth20';\n\npassport.use(new GoogleStrategy({\n  clientID: process.env.GOOGLE_CLIENT_ID,\n  clientSecret: process.env.GOOGLE_CLIENT_SECRET,\n  callbackURL: `${process.env.BASE_URL}\/auth\/google\/callback`,\n  scope: ['openid', 'profile', 'email'],\n  pkce: true,   \/\/ PKCE abilitato (passport-google-oauth20 v2.0+)\n  state: true   \/\/ Protezione CSRF tramite state parameter\n}, async (accessToken, refreshToken, idTokenData, profile, done) => {\n  \/\/ Normalizza il profilo utente\n  const user = {\n    id: profile.id,\n    email: profile.emails?.[0]?.value,\n    name: profile.displayName,\n    picture: profile.photos?.[0]?.value\n    \/\/ Non salvare accessToken in database non cifrato\n  };\n\n  if (!user.email) {\n    return done(new Error('Nessuna email associata all account Google'));\n  }\n\n  \/\/ In produzione: cerca o crea l'utente nel database\n  \/\/ const dbUser = await upsertUser(user);\n  \/\/ return done(null, dbUser);\n\n  return done(null, user);\n}));\n\n\/\/ Serializzazione: salva solo l'ID nella sessione, non l'intero profilo\npassport.serializeUser((user, done) => {\n  done(null, user.id);\n});\n\n\/\/ Deserializzazione: ricostruisce l'utente a ogni richiesta autenticata\npassport.deserializeUser(async (id, done) => {\n  \/\/ In produzione: const user = await getUserById(id);\n  done(null, { id });\n});\n<\/code><\/pre>\n\n\n\n
    La deserializzazione chiama il database a ogni richiesta autenticata. Con migliaia di utenti concorrenti, aggiungi un cache layer Redis con TTL di 5 minuti per i dati utente non critici. La serializzazione deve salvare il minimo indispensabile: solo l’ID, non l’intero profilo con email e foto. Meno dati in sessione, minore la superficie esposta in caso di session hijacking.<\/p>\n\n\n\n
    Step 6: Implementa le Route di Autenticazione<\/h2>\n\n\n\n
    Le route di autenticazione coprono quattro endpoint: avvio del flusso OAuth2, callback di Google, logout e status. Il file src\/routes\/auth.js<\/code>:<\/p>\n\n\n\n
    import express from 'express';\nimport passport from 'passport';\n\nconst router = express.Router();\n\n\/\/ Avvia il flusso OAuth2 con PKCE\nrouter.get('\/google', passport.authenticate('google', {\n  scope: ['openid', 'profile', 'email'],\n  accessType: 'offline',   \/\/ Richiede refresh_token da Google\n  prompt: 'consent'        \/\/ Forza il consenso per ottenere refresh_token\n}));\n\n\/\/ Callback di Google dopo autenticazione\nrouter.get('\/google\/callback',\n  passport.authenticate('google', {\n    failureRedirect: '\/?error=auth_failed',\n    failureMessage: true\n  }),\n  (req, res) => {\n    \/\/ Rigenera l'ID sessione dopo il login (prevenzione session fixation)\n    req.session.regenerate((err) => {\n      if (err) return res.redirect('\/?error=session_error');\n      req.session.user = req.user;\n      req.session.save((err) => {\n        if (err) return res.redirect('\/?error=session_save');\n        res.redirect('\/profile');\n      });\n    });\n  }\n);\n\n\/\/ Logout sicuro con distruzione sessione\nrouter.post('\/logout', (req, res, next) => {\n  req.logout((err) => {\n    if (err) return next(err);\n    req.session.destroy((err) => {\n      if (err) return next(err);\n      res.clearCookie('connect.sid');\n      res.json({ success: true });\n    });\n  });\n});\n\n\/\/ Stato autenticazione per il frontend\nrouter.get('\/status', (req, res) => {\n  res.json({\n    authenticated: req.isAuthenticated(),\n    user: req.user ? { id: req.user.id, email: req.user.email } : null\n  });\n});\n\nexport default router;\n<\/code><\/pre>\n\n\n\n
    La rigenerazione dell’ID sessione dopo il login con req.session.regenerate()<\/code> previene il session fixation attack<\/em>: un attaccante potrebbe fissare un ID sessione noto prima del login e usarlo per accedere all’account dopo l’autenticazione. Senza regenerate()<\/code>, l’ID sessione rimane lo stesso prima e dopo il login, rendendo possibile l’attacco. Authgear classifica questa come pratica obbligatoria per le app Node.js nel 2026.<\/p>\n\n\n\n
    Step 7: Protezione delle Route con Middleware<\/h2>\n\n\n\n
    Il file src\/middleware\/requireAuth.js<\/code> definisce due middleware riutilizzabili per la protezione delle route:<\/p>\n\n\n\n
    \/\/ Blocca le richieste non autenticate\nexport function requireAuth(req, res, next) {\n  if (req.isAuthenticated()) return next();\n\n  \/\/ Per richieste API: risponde con 401 JSON\n  if (req.headers.accept?.includes('application\/json')) {\n    return res.status(401).json({ error: 'Authentication required' });\n  }\n\n  \/\/ Per richieste web: salva la destinazione e reindirizza al login\n  req.session.returnTo = req.originalUrl;\n  res.redirect('\/auth\/google');\n}\n\n\/\/ Reindirizza gli utenti gi\u00e0 autenticati (es. pagina di login)\nexport function requireGuest(req, res, next) {\n  if (!req.isAuthenticated()) return next();\n  res.redirect('\/profile');\n}\n<\/code><\/pre>\n\n\n\n
    Il file src\/routes\/profile.js<\/code> applica il middleware alle route protette:<\/p>\n\n\n\n
    import express from 'express';\nimport { requireAuth } from '..\/middleware\/requireAuth.js';\n\nconst router = express.Router();\n\nrouter.get('\/', requireAuth, (req, res) => {\n  res.json({\n    message: 'Profilo protetto',\n    user: {\n      id: req.user.id,\n      email: req.user.email,\n      name: req.user.name\n    }\n  });\n});\n\n\/\/ Endpoint API protetta per dati sensibili\nrouter.get('\/api\/data', requireAuth, async (req, res) => {\n  try {\n    res.json({ data: 'Dati riservati', userId: req.user.id });\n  } catch (error) {\n    console.error('Errore profile\/api\/data:', error);\n    \/\/ Non esporre stack trace nelle risposte di errore\n    res.status(500).json({ error: 'Internal server error' });\n  }\n});\n\nexport default router;\n<\/code><\/pre>\n\n\n\n
    Step 8: Verifica dell’ID Token OIDC con jose<\/h2>\n\n\n\n
    Quando il provider supporta OpenID Connect, ricevi un id_token<\/code> oltre all’access_token<\/code>. Questo JWT contiene le claims<\/em> sull’identit\u00e0 dell’utente. La libreria jose<\/code> v6 permette di verificarlo controllando firma, issuer, audience e scadenza. Crea il file src\/auth\/oidc.js<\/code>:<\/p>\n\n\n\n
    import { createRemoteJWKSet, jwtVerify } from 'jose';\n\n\/\/ Chiavi pubbliche di Google per la verifica delle firme\nconst GOOGLE_JWKS = createRemoteJWKSet(\n  new URL('https:\/\/www.googleapis.com\/oauth2\/v3\/certs')\n);\n\nexport async function verifyGoogleIdToken(idToken) {\n  const { payload } = await jwtVerify(idToken, GOOGLE_JWKS, {\n    issuer: 'https:\/\/accounts.google.com',\n    audience: process.env.GOOGLE_CLIENT_ID\n    \/\/ jose verifica automaticamente la scadenza (exp claim)\n  });\n\n  \/\/ Verifica claims obbligatorie OIDC Core 1.0\n  if (!payload.sub) throw new Error('ID token privo di sub claim');\n  if (!payload.email_verified) throw new Error('Email non verificata dal provider');\n\n  return {\n    sub: payload.sub,\n    email: payload.email,\n    name: payload.name,\n    picture: payload.picture,\n    issuedAt: payload.iat,\n    expiresAt: payload.exp\n  };\n}\n<\/code><\/pre>\n\n\n\n
    Due punti critici sulla verifica. Primo: specifica sempre l’issuer<\/code> e l’audience<\/code> nella chiamata jwtVerify()<\/code>. Un token emesso per un’altra applicazione non deve essere accettato dalla tua. Secondo: la libreria jose<\/code> v6 rifiuta automaticamente alg: none<\/code> e gli algoritmi simmetrici su chiavi asimmetriche, eliminando la categoria di algoritm confusion attacks. Il pinning degli algoritmi, raccomandato dalla guida di Authgear 2026, \u00e8 gi\u00e0 integrato nel comportamento di default di jose quando usi JWKS remoti.<\/p>\n\n\n\n
    Step 9: Implementa PKCE Manuale per Provider Custom<\/h2>\n\n\n\n
    Se integri un provider personalizzato (Keycloak, Auth0 con piano gratuito, Okta) che non ha una Passport strategy pronta, implementa PKCE con il modulo crittografico nativo di Node.js. Il file src\/auth\/pkce.js<\/code>:<\/p>\n\n\n\n
    import { randomBytes, createHash } from 'node:crypto';\n\n\/\/ Genera un code_verifier casuale (RFC 7636: 43-128 caratteri URL-safe)\nexport function generateCodeVerifier() {\n  return randomBytes(32).toString('base64url');\n}\n\n\/\/ Calcola il code_challenge (SHA-256 del verifier)\nexport function generateCodeChallenge(verifier) {\n  return createHash('sha256').update(verifier).digest('base64url');\n}\n\n\/\/ Costruisce l'URL di autorizzazione con PKCE e state anti-CSRF\nexport function buildAuthorizationUrl(config) {\n  const verifier = generateCodeVerifier();\n  const challenge = generateCodeChallenge(verifier);\n  const state = randomBytes(16).toString('hex');\n\n  const params = new URLSearchParams({\n    response_type: 'code',\n    client_id: config.clientId,\n    redirect_uri: config.redirectUri,\n    scope: config.scope,\n    state,\n    code_challenge: challenge,\n    code_challenge_method: 'S256'\n  });\n\n  return {\n    url: `${config.authorizationEndpoint}?${params}`,\n    verifier,  \/\/ Salvare in sessione lato server\n    state\n  };\n}\n<\/code><\/pre>\n\n\n\n
    Il code_verifier<\/code> deve essere salvato nella sessione del server, non passato al browser in nessuna forma. Il browser vede solo il code_challenge<\/code>, un hash SHA-256 irreversibile. Quando arriva il callback con il codice di autorizzazione, il server recupera il verifier dalla sessione e lo invia al token endpoint. Il formato base64url<\/code>, senza padding e senza caratteri +<\/code> o \/<\/code>, \u00e8 obbligatorio per RFC 7636.<\/p>\n\n\n\n
    Step 10: Gestione Sicura dei Refresh Token<\/h2>\n\n\n\n
    Gli access token Google scadono dopo 3600 secondi (1 ora). Il refresh token permette di ottenerne uno nuovo senza chiedere all’utente di riautenticarsi. La refresh token rotation<\/em> invalida il token usato ogni volta che viene scambiato, limitando la finestra di abuso se viene rubato. Crea il file src\/auth\/tokenRefresh.js<\/code>:<\/p>\n\n\n\n
    export async function refreshAccessToken(refreshToken) {\n  const response = await fetch('https:\/\/oauth2.googleapis.com\/token', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\/x-www-form-urlencoded' },\n    body: new URLSearchParams({\n      client_id: process.env.GOOGLE_CLIENT_ID,\n      client_secret: process.env.GOOGLE_CLIENT_SECRET,\n      grant_type: 'refresh_token',\n      refresh_token: refreshToken\n    })\n  });\n\n  if (!response.ok) {\n    const error = await response.json();\n    \/\/ invalid_grant = token revocato o scaduto\n    if (error.error === 'invalid_grant') {\n      throw Object.assign(new Error('SESSION_EXPIRED'), { code: 'INVALID_GRANT' });\n    }\n    throw new Error(`Token refresh fallito: ${error.error}`);\n  }\n\n  const tokens = await response.json();\n  return {\n    accessToken: tokens.access_token,\n    expiresAt: Date.now() + (tokens.expires_in * 1000),\n    \/\/ Google non sempre emette un nuovo refresh_token\n    refreshToken: tokens.refresh_token || refreshToken\n  };\n}\n<\/code><\/pre>\n\n\n\n
    Dove salvare i token? Non nel database in chiaro. Le opzioni sicure nel 2026 sono: cifratura AES-256-GCM<\/strong> prima della persistenza, con la chiave master in un secrets manager (AWS Secrets Manager, HashiCorp Vault), oppure mantenerli solo in Redis cifrato con TTL. Non usare mai localStorage<\/code> per i token: qualsiasi script XSS pu\u00f2 leggerlo. Il pattern BFF (Backend for Frontend) \u00e8 la soluzione ottimale per le SPA: il backend gestisce tutti i token e il browser interagisce solo tramite cookie httpOnly<\/code>.<\/p>\n\n\n\n
    Step 11: Logout Sicuro con Revoca Token<\/h2>\n\n\n\n
    Un logout parziale (solo lato client) lascia il refresh token valido anche dopo che l’utente ha cliccato “Esci”. Per un logout sicuro completo bisogna: revocare i token lato authorization server, chiamare req.logout()<\/code>, distruggere la sessione Redis e cancellare il cookie. Aggiorna la route logout in src\/routes\/auth.js<\/code>:<\/p>\n\n\n\n
    router.post('\/logout', async (req, res, next) => {\n  const accessToken = req.session?.accessToken;\n\n  try {\n    \/\/ 1. Revoca il token su Google\n    if (accessToken) {\n      await fetch(`https:\/\/oauth2.googleapis.com\/revoke?token=${encodeURIComponent(accessToken)}`, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application\/x-www-form-urlencoded' }\n      });\n    }\n\n    \/\/ 2. Logout Passport (rimuove req.user)\n    await new Promise((resolve, reject) => {\n      req.logout((err) => err ? reject(err) : resolve());\n    });\n\n    \/\/ 3. Distruggi la sessione Redis\n    await new Promise((resolve, reject) => {\n      req.session.destroy((err) => err ? reject(err) : resolve());\n    });\n\n    \/\/ 4. Cancella il cookie lato client\n    res.clearCookie('connect.sid', {\n      httpOnly: true,\n      secure: process.env.NODE_ENV === 'production',\n      sameSite: 'lax'\n    });\n\n    res.json({ success: true, message: 'Logout effettuato correttamente' });\n\n  } catch (error) {\n    console.error('Errore durante il logout:', error.message);\n    next(error);\n  }\n});\n<\/code><\/pre>\n\n\n\n
    Step 12: Test Funzionale e Checklist di Sicurezza<\/h2>\n\n\n\n
    Prima del deploy, esegui questi test manuali nell’ordine indicato. Ogni passo verifica un aspetto distinto del flusso:<\/p>\n\n\n\n
    # Avvia il server in modalit\u00e0 sviluppo\nnpm run dev\n\n# Test 1: verifica endpoint non autenticato\ncurl http:\/\/localhost:3000\/auth\/status\n# Atteso: {\"authenticated\":false,\"user\":null}\n\n# Test 2: verifica protezione route senza sessione\ncurl -X GET http:\/\/localhost:3000\/profile -H \"Accept: application\/json\"\n# Atteso: {\"error\":\"Authentication required\"}\n\n# Test 3: avvia il flusso OAuth2 (apri nel browser)\n# Naviga su: http:\/\/localhost:3000\/auth\/google\n# Accedi con un account Google di test\n\n# Test 4: verifica sessione attiva dopo login\ncurl -b \"connect.sid=COOKIE_VALUE\" http:\/\/localhost:3000\/auth\/status\n# Atteso: {\"authenticated\":true,\"user\":{\"id\":\"...\",\"email\":\"...\"}}\n\n# Test 5: verifica accesso alla route protetta\ncurl -b \"connect.sid=COOKIE_VALUE\" http:\/\/localhost:3000\/profile\n# Atteso: {\"message\":\"Profilo protetto\",\"user\":{...}}\n\n# Test 6: logout e verifica invalidazione\ncurl -X POST -b \"connect.sid=COOKIE_VALUE\" http:\/\/localhost:3000\/auth\/logout\ncurl -b \"connect.sid=COOKIE_VALUE\" http:\/\/localhost:3000\/auth\/status\n# Atteso dopo logout: {\"authenticated\":false,\"user\":null}\n<\/code><\/pre>\n\n\n\n
    Usa Chrome DevTools (scheda Network, poi Application > Cookies) per verificare i cookie: il cookie di sessione deve avere i flag HttpOnly<\/code> e SameSite: Lax<\/code>, e Secure<\/code> in produzione su HTTPS. Se uno di questi manca, c’\u00e8 un problema nella configurazione di express-session<\/code>. Per un test di sicurezza pi\u00f9 approfondito del flusso OAuth2, usa Burp Suite come proxy per intercettare e ispezionare ogni richiesta del flusso come mostrato nel nostro tutorial Burp Suite<\/a>.<\/p>\n\n\n\n
    Errori Comuni e Come Evitarli<\/h2>\n\n\n\n
    Questi sono gli 8 errori pi\u00f9 frequenti nelle implementazioni OAuth2 in Node.js, raccolti da revisioni di codice su progetti in produzione:<\/p>\n\n\n\n
      \n
    1. Salvare i token in localStorage.<\/strong> JavaScript in qualsiasi script della pagina (inclusi script di terze parti) pu\u00f2 leggere localStorage<\/code>. Un XSS anche minimo espone tutti i token. Usa sempre cookie httpOnly<\/code>.<\/li>\n
    2. Non validare il parametro state<\/code>.<\/strong> Il parametro state<\/code> previene i CSRF sull’endpoint di callback. Se non lo confronti con quello salvato in sessione, un attaccante pu\u00f2 innescare un login con il proprio codice di autorizzazione e dirottare la sessione della vittima (login CSRF).<\/li>\n
    3. Non specificare l’algoritmo nella verifica JWT.<\/strong> L’attacco “alg:none” e la confusion attack tra HS256\/RS256 sono documentati da anni. Usa librerie che fanno il pinning automaticamente, come jose<\/code> v6.<\/li>\n
    4. Usare il session store in memoria in produzione.<\/strong> MemoryStore<\/code> di express-session non \u00e8 adatto alla produzione: perde dati al riavvio e produce memory leak sotto carico. Usa sempre Redis o un database persistente.<\/li>\n
    5. Non rigenerare l’ID sessione dopo il login.<\/strong> La session fixation \u00e8 un attacco noto. Chiama sempre req.session.regenerate()<\/code> dopo l’autenticazione riuscita.<\/li>\n
    6. Richiedere scope eccessivi.<\/strong> Se la tua app ha bisogno solo dell’email, richiedi solo openid email<\/code>. Scope aggiuntivi come gmail.readonly<\/code> senza necessit\u00e0 espongono l’app a rischi maggiori e riducono i tassi di conversione.<\/li>\n
    7. Non gestire la revoca del refresh token.<\/strong> Un utente pu\u00f2 revocare l’accesso dalla sua Google Account. Il server deve gestire invalid_grant<\/code> e forzare un nuovo login invece di andare in loop di retry.<\/li>\n
    8. Logare il valore completo dei token.<\/strong> Un token di accesso nei log \u00e8 un token esposto. Logga solo metadata: presenza\/assenza, scadenza, user ID associato. Mai il valore del token.<\/li>\n<\/ol>\n\n\n\n
      Risoluzione dei Problemi: 8 Scenari Frequenti<\/h2>\n\n\n\n
      \n\n
      Errore \/ Sintomo<\/th>Causa pi\u00f9 probabile<\/th>Soluzione<\/th><\/tr><\/thead>\n
      redirect_uri_mismatch<\/code><\/td>URI nella richiesta diverso da quello registrato su Google Cloud Console<\/td>Verifica che BASE_URL in .env corrisponda esattamente all’URI registrato, incluso protocollo e porta<\/td><\/tr>\n
      invalid_client<\/code><\/td>Client ID o Client Secret errato o scaduto<\/td>Rigenera le credenziali su Google Cloud Console e aggiorna il file .env<\/td><\/tr>\n
      invalid_grant<\/code> al refresh<\/td>Refresh token revocato dall’utente o scaduto<\/td>Cattura il codice INVALID_GRANT<\/code>, cancella i token salvati e reindirizza al login<\/td><\/tr>\n
      Sessione persa al riavvio server<\/td>MemoryStore in uso invece di Redis<\/td>Configura connect-redis<\/code> come store nella configurazione della sessione<\/td><\/tr>\n
      Loop di redirect al login<\/td>Cookie non impostato per problema SameSite o CORS<\/td>In sviluppo: usa sameSite: 'lax'<\/code>; verifica che il callback URL non venga da un dominio diverso<\/td><\/tr>\n
      passport.authenticate<\/code> non esegue il callback<\/td>Mancata registrazione di serializeUser<\/code> o deserializeUser<\/code><\/td>Controlla che entrambi siano registrati in passport.js<\/code> prima dell’importazione delle route<\/td><\/tr>\n
      ID token con firma invalida<\/td>Chiavi JWKS scadute in cache o algoritmo non supportato<\/td>Usa createRemoteJWKSet<\/code> di jose per aggiornamento automatico; verifica che il provider usi RS256<\/td><\/tr>\n
      Cannot read properties of undefined (reading 'emails')<\/code><\/td>Profilo Google senza email (account senza verifica)<\/td>Aggiungi guardia: if (!profile.emails?.length) return done(new Error('No email'))<\/code><\/td><\/tr>\n<\/tbody>\n<\/table><\/figure>\n\n\n\n
      Debug del Flusso OAuth2 Passo per Passo<\/h3>\n\n\n\n
      Se non riesci a capire dove il flusso si rompe, abilita il debug di Passport con la variabile d’ambiente DEBUG=passport:*<\/code> prima di avviare il server:<\/p>\n\n\n\n
      DEBUG=passport:* node src\/app.js\n\n# Output esempio:\n# passport:authenticate google +0ms\n# passport:strategy:google attempting to authenticate +1ms\n# passport:strategy:google redirecting to https:\/\/accounts.google.com\/o\/oauth2\/...\n\n# Per ispezionare la sessione Redis:\nredis-cli\n127.0.0.1:6379> KEYS sess:*\n127.0.0.1:6379> GET sess:abc123\n# Mostra il JSON della sessione (incluso lo stato dell'autenticazione)\n<\/code><\/pre>\n\n\n\n
      Consigli Avanzati per la Produzione<\/h2>\n\n\n\n
      Una volta che il flusso base funziona, questi accorgimenti portano l’implementazione al livello enterprise:<\/p>\n\n\n\n
      Rate Limiting sugli Endpoint Auth<\/h3>\n\n\n\n
      Gli endpoint OAuth2 sono bersagli di abuso. Applica rate limiting specifico sul path \/auth\/*<\/code>, pi\u00f9 restrittivo di quello globale dell’applicazione. Una configurazione ragionevole: massimo 10 richieste per IP ogni 15 minuti. L’articolo Rate Limiting in Node.js<\/a> mostra l’implementazione completa con Redis e sliding window. Aggiungi anche logging degli IP che superano il limite per identificare pattern di bot.<\/p>\n\n\n\n
      Validazione con Zod prima del Database<\/h3>\n\n\n\n
      Prima di passare i dati del profilo OAuth2 al database, validali con Zod. Un profilo Google pu\u00f2 contenere campi inaspettati o valori fuori range. La validazione con schema previene mass assignment e injection nei layer ORM:<\/p>\n\n\n\n
      import { z } from 'zod';\n\nconst UserProfileSchema = z.object({\n  id: z.string().min(1).max(255),\n  email: z.string().email().max(255),\n  name: z.string().max(255).optional(),\n  picture: z.string().url().optional()\n});\n\n\/\/ Nel callback Passport:\nconst parsed = UserProfileSchema.safeParse(user);\nif (!parsed.success) {\n  return done(new Error('Profilo OAuth2 non valido'));\n}\nconst safeUser = parsed.data;\n<\/code><\/pre>\n\n\n\n
      Multi-provider e account linking.<\/strong> Se permetti login sia con Google che con GitHub, due account possono avere la stessa email. Decidi in anticipo se trattarli come la stessa identit\u00e0 (link account per email) o identit\u00e0 separate. L’approccio pi\u00f9 sicuro \u00e8 richiedere conferma esplicita all’utente prima di collegare due account con la stessa email, per prevenire account takeover tramite provider compromise.<\/p>\n\n\n\n
      Logging strutturato degli eventi di sicurezza.<\/strong> Logga ogni evento di autenticazione, login riuscito, login fallito, logout, refresh token, con user ID, IP sorgente e timestamp. Non loggare mai il valore dei token. Usa un formato JSON strutturato per poterli analizzare con SIEM (Splunk, Elastic SIEM). Un login riuscito da un’IP mai vista prima merita un alert automatico.<\/p>\n\n\n\n
      Confronto: Storage Token per le SPA nel 2026<\/h2>\n\n\n\n
      \n\n
      Metodo di Storage<\/th>Resistenza XSS<\/th>Resistenza CSRF<\/th>Scalabilit\u00e0<\/th>Raccomandazione 2026<\/th><\/tr><\/thead>\n
      localStorage<\/td>Nulla<\/td>Alta<\/td>Alta<\/td>Non usare per token<\/td><\/tr>\n
      sessionStorage<\/td>Nulla<\/td>Alta<\/td>Alta<\/td>Non usare per token<\/td><\/tr>\n
      Cookie httpOnly lax<\/td>Alta<\/td>Media<\/td>Alta<\/td>Buono per web app<\/td><\/tr>\n
      Cookie httpOnly + CSRF token doppio<\/td>Alta<\/td>Alta<\/td>Alta<\/td>Ottimale per web app<\/td><\/tr>\n
      Memoria RAM (SPA in-memory)<\/td>Alta<\/td>Alta<\/td>Bassa (perde al refresh)<\/td>Solo per SPA con silent refresh<\/td><\/tr>\n
      BFF con cookie httpOnly<\/td>Alta<\/td>Alta<\/td>Alta<\/td>Ottimale per SPA enterprise<\/td><\/tr>\n<\/tbody>\n<\/table><\/figure>\n\n\n\n
      Il pattern BFF (Backend for Frontend)<\/strong> \u00e8 la soluzione pi\u00f9 robusta per le SPA nel 2026: il backend Node.js gestisce tutta la logica OAuth2 e i token non raggiungono mai il browser in forma leggibile. La SPA interagisce solo con il BFF tramite cookie di sessione httpOnly<\/code>. Questa architettura elimina l’intera categoria di rischi XSS sui token e semplifica la gestione del refresh, ma aggiunge un componente server-side che le SPA pure evitano.<\/p>\n\n\n\n
      Copertura Correlata<\/h2>\n\n\n\n
      Articoli sul Tema Sicurezza in Node.js<\/h3>\n\n\n\n