Aggiungi l'accesso con GitHub

Procedura dettagliata per principianti

Prerequisiti: l'app web in esecuzione in locale e un database migrato per account reali. Serve un account GitHub — va bene quello che possiede il repository. Gratuito, circa 5 minuti per ambiente.

Terminologia rapida: una OAuth App di GitHub è la registrazione che permette a GitHub di autenticare gli utenti per te. A differenza della maggior parte dei provider, una OAuth App consente esattamente una Authorization callback URL — quindi locale (http://localhost:3000/…) e produzione (https://yourdomain.com/…) hanno bisogno ciascuna della propria app. Riutilizzare un'app modificando il suo callback da un lato all'altro rompe un lato ogni volta.

1. Crea una OAuth App locale nelle Developer settings del tuo account. 2. Copia il suo Client ID e genera un Client Secret. 3. Imposta i tre valori di ambiente e riavvia. 4. Ripeti una volta con il tuo dominio reale prima di andare online.

• Mettere online l'app web in 5 minuti
• Configura il database

Creare l'OAuth App locale

1. Apri github.com e accedi. Fai clic sulla tua foto profilo in alto a destra → Settings.

2. Scorri fino in fondo alla barra laterale sinistra e apri Developer settings → OAuth Apps → New OAuth App.

3. Application name: ad esempio supastack local — gli utenti vedono questo nome nella pagina di autorizzazione di GitHub. Homepage URL: http://localhost:3000. Authorization callback URL: http://localhost:3000/api/auth/callback/github. Fai clic su Register application.

4. Nella pagina dell'app copia il Client ID, fai clic su Generate a new client secret e copia subito il segreto — GitHub lo mostra solo una volta, anche se puoi sempre generarne un altro.

Creare l'OAuth App di produzione

Ripeti gli stessi passaggi di New OAuth App con il nome del prodotto, Homepage URL https://yourdomain.com e Authorization callback URL https://yourdomain.com/api/auth/callback/github.

Conserva le credenziali di ogni app nel proprio ambiente: la coppia dell'app locale vive in apps/web/.env.local, quella dell'app di produzione nell'archivio dei segreti del tuo host. Il segreto locale non deve mai raggiungere la configurazione di produzione né viceversa.

Aggiungere i valori all'app

Inserisci le tre righe qui sotto in apps/web/.env.local usando le credenziali dell'app locale. AUTH_GITHUB_ENABLED=true accende il pulsante; la coppia identifica l'OAuth App.

Il client secret resta solo sul server — mai in variabili NEXT_PUBLIC_/EXPO_PUBLIC_ e mai committato. Riavvia il dev server dopo la modifica.

Non riutilizzare i valori GITHUB_APP_* che potresti vedere altrove — appartengono a un'integrazione GitHub App senza relazione, non all'accesso degli utenti. Il docs/github-auth-setup.md del kit percorre l'intero flusso dall'inizio alla fine se vuoi un secondo riferimento.

# apps/web/.env.local — from the LOCAL OAuth App
AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=your-oauth-app-client-id
GITHUB_CLIENT_SECRET=your-oauth-app-secret

Verificare e risolvere i problemi

Apri http://localhost:3000/auth e fai clic sul pulsante GitHub. Autorizza l'app su github.com e conferma che torni con l'accesso effettuato.

Finché AUTH_GITHUB_ENABLED=true non è impostato, l'opzione GitHub su /auth resta visibile ma disabilitata — ricontrolla i nomi del file env e riavvia. Impostare il flag senza GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET fa fallire l'avvio e nomina la variabile mancante.

Un callback non corrispondente è il fallimento abituale: l'Authorization callback URL dell'app deve essere esattamente {APP_URL}/api/auth/callback/github — protocollo, host, porta e percorso. Un errore redirect_uri dopo la distribuzione di solito significa che la richiesta ha toccato le credenziali dell'app locale mentre APP_URL dice produzione, o il contrario.

Riavvia il dev server dopo ogni modifica all'env; i valori vengono letti solo all'avvio.

• Configurare poi il database
• Panoramica dei provider OAuth