luzadev/ketopath
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ketopath/docs/runbooks/google-oauth-setup.md
T
lucianoandClaude Opus 4.7 646b98cccf feat(auth): hide Google button when OAuth env is missing 
- Export enabledSocialProviders from @ketopath/auth: ['google'] when
  GOOGLE_CLIENT_ID/SECRET are both set, [] otherwise
- sign-in and sign-up pages read enabledSocialProviders server-side and pass
  googleEnabled to their forms; the divider and button disappear when false
- No changes to the Better Auth instance — the Google provider is still
  conditionally registered, this just keeps the UI honest about it

docs/runbooks/google-oauth-setup.md walks through the Google Cloud Console
flow end-to-end (project, consent screen, credentials, redirect URIs, env
injection, verification, troubleshooting, prod considerations).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 13:55:04 +02:00

4.7 KiB
Raw Permalink Blame History

Runbook — Configurazione Google OAuth

Procedura per abilitare il login "Continua con Google" su KetoPath.

Prerequisiti

Passo 1 — Creare il progetto Google Cloud

  1. Apri https://console.cloud.google.com/
  2. In alto a sinistra, dropdown progetto → New Project
  3. Nome progetto: KetoPath (o nome interno equivalente)
  4. Crea — il progetto diventa attivo automaticamente

Passo 2 — Configurare l'OAuth consent screen

  1. Dal menu laterale: APIs & Services → OAuth consent screen
  2. Tipo utente: External (necessario per consentire login a chiunque, non solo al tuo workspace Google)
  3. Compila:
    • App name: KetoPath
    • User support email: la tua email
    • App logo: opzionale per ora, obbligatorio per la pubblicazione
    • App domain → Application home page: https://ketopath.it (placeholder per dev)
    • Authorized domains: aggiungi ketopath.it e qualunque dominio di produzione
    • Developer contact email: la tua email
  4. Save and continue
  5. Scopes: aggiungi email, profile, openid (sono i tre default per OAuth 2.0)
  6. Save and continue
  7. Test users: aggiungi le email di chi farà i test fino al go-live (massimo 100)
  8. Save and continue → Back to dashboard

Finché lo stato è "Testing" solo i test users possono accedere. Dopo il lancio pubblico, sottoponi l'app a verifica Google (se chiedi scope sensibili, può richiedere settimane). Per email/profile/openid la verifica è automatica.

Passo 3 — Creare le credenziali OAuth

  1. Menu laterale: APIs & Services → Credentials
  2. Create credentials → OAuth client ID
  3. Application type: Web application
  4. Name: KetoPath Web Client
  5. Authorized redirect URIs — aggiungi tutte le seguenti:
    • http://localhost:3000/api/auth/callback/google (sviluppo locale)
    • https://staging.ketopath.it/api/auth/callback/google (staging, se previsto)
    • https://app.ketopath.it/api/auth/callback/google (produzione)
  6. Create
  7. Copia Client ID e Client Secret dalla dialog che appare. Il secret non sarà più recuperabile dopo questa schermata — se lo perdi devi rigenerarlo.

Passo 4 — Iniettare le credenziali nei .env

Aggiungi le seguenti righe a entrambi i file (devono essere identici):

apps/web/.env:

GOOGLE_CLIENT_ID=il-client-id-copiato.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=il-client-secret-copiato

apps/api/.env:

GOOGLE_CLIENT_ID=il-client-id-copiato.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=il-client-secret-copiato

I file .env non vanno mai committati. Sono già in .gitignore.

Passo 5 — Riavviare i dev server

pnpm dev:web   # in un terminale
pnpm dev:api   # in un altro

L'istanza Better Auth in @ketopath/auth rileva automaticamente la presenza delle env vars e attiva il provider. La costante enabledSocialProviders diventa ['google'] e il bottone "Continua con Google" appare nelle pagine sign-in/sign-up.

Passo 6 — Verifica

  1. Apri http://localhost:3000/sign-up nel browser
  2. Verifica che il bottone "Continua con Google" sia visibile
  3. Cliccalo → vieni reindirizzato a accounts.google.com
  4. Scegli un account dalla lista test users
  5. Autorizza l'app
  6. Vieni reindirizzato a http://localhost:3000/ con l'utente loggato
  7. Tabella users in Postgres ha una nuova riga; tabella accounts ha una riga con provider_id = 'google' e account_id = <google sub>.

Troubleshooting

  • Error: redirect_uri_mismatch: il redirect URI nei tuoi .env non corrisponde esattamente a quelli configurati in Google Cloud. Includere protocollo, hostname, porta e path: http://localhost:3000/api/auth/callback/google.
  • Error: access_denied: l'utente non è nei "test users" della consent screen. Aggiungilo dalla dashboard.
  • Bottone non visibile: enabledSocialProviders valuta entrambe le env vars al boot. Controlla che il server sia stato riavviato dopo aver scritto i .env.
  • Sessione non condivisa tra web e api: BETTER_AUTH_SECRET deve essere identico in entrambi i .env. Cambiarlo invalida tutte le sessioni esistenti.

Produzione

Per il deploy:

  • Imposta GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET come secrets in Vercel (web) e Render/Fly.io (api).
  • BETTER_AUTH_URL deve essere l'URL pubblico del web (es. https://app.ketopath.it).
  • Aggiungi i redirect URI di produzione in Google Cloud Console prima del deploy, altrimenti il primo login fallirà.
  • Pubblica la consent screen quando l'app è pronta per uscire dalla modalità Testing.
Reference in new issue View Git Blame Copy Permalink