Clerk: autenticazione e OAuth dallo sviluppo alla produzione

Panoramica

La tua app ora ha bisogno di utenti: persone che si iscrivono, si connettono e hanno i loro dati. Questa e l'autenticazione, ed e un posto dove un piccolo errore fa trapelare ogni password cliente che tieni. La mossa giusta nel 2026 e inequivocabile: non costruirla da solo, usa un servizio. Clerk e quel servizio per la maggior parte dei builder a cui si rivolge questo corso. Questa lezione spiega l'unico concetto che devi capire (OAuth), porta Clerk nella tua app, poi ti guida attraverso la parte che tutti trovano delicata - passare dalle chiavi di development a una vera istanza di produzione con Google login sul tuo dominio.

Cosa imparerai

Imparerai cos'e OAuth in parole chiare, perche l'auth fatta in casa e una trappola in cui cadono persino le grandi societa, come Clerk si integra alla tua app, la differenza cruciale tra un'istanza di development e un'istanza di produzione, e i passi esatti per attivare Google OAuth in produzione, incluso il consent screen Google, le credential e i DNS record che lo fanno girare sul tuo dominio.

Prerequisiti

Un'app funzionante dal Corso 1 e la mappa d'architettura della lezione precedente, perche l'auth vive lato app, non lato sito marketing. Hai anche bisogno della disciplina dei segreti del Corso 1: le chiavi di auth sono altamente sensibili e non devono mai essere committate. La prossima lezione sui segreti va oltre, ma la regola di base (chiavi in .env, .env in .gitignore) deve gia essere un riflesso.

Il problema

Costruire l'auth da soli suona come una sfida di bravura. E in realta un campo minato. Devi hashare e salare le password correttamente, gestire le sessioni e i token, trattare i reset di password, difenderti dal credential stuffing e dal brute force, memorizzare tutto in sicurezza e seguire in eterno le nuove tecniche d'attacco. Manca un dettaglio e fai trapelare dati clienti, il che e una catastrofe giuridica e reputazionale. Nel frattempo, i tuoi concorrenti hanno pubblicato il login con Clerk in un pomeriggio e sono passati a costruire il loro vero prodotto. Non c'e nessun premio per la versione fatta in casa. E un problema risolto, e il tuo job e usare la soluzione, non reinventarla.

Cos'e realmente OAuth

OAuth e il protocollo dietro ogni pulsante "Sign in with Google" o "Sign in with GitHub". L'idea centrale e la delega, senza condividere la tua password. Quando un utente clicca "Sign in with Google", la tua app non vede mai la sua password Google. Invece, la tua app lo rimanda a Google, Google conferma chi e e gli chiede di approvare la condivisione della sua e-mail e del suo nome con la tua app, e Google rimanda un token che prova "si, e davvero lui". La tua app si fida della parola di Google. E tutto il concetto: un terzo di fiducia si fa garante dell'utente, perche tu non debba mai memorizzare o verificare la sua password. E piu sicuro (non tieni password), piu pratico (un click, nessun nuovo account) ed e cio che gli utenti si aspettano. Clerk gestisce tutta la danza OAuth per te - tu attivi semplicemente i provider che vuoi.

• OAuth = lasciare che un provider di fiducia (Google, GitHub, Apple) si faccia garante dell'utente, perche tu non tocchi mai la sua password.
• La tua app riceve un token che prova l'identita, piu info di profilo di base che l'utente ha approvato di condividere.
• Piu sicuro per te (nessuna password memorizzata), piu pratico per loro (un click).
• Clerk pilota il flusso OAuth; tu attivi un provider e aggiungi le sue credential.

Aggiungere Clerk alla tua app

Clerk ti da componenti drop-in per l'iscrizione, il login, il profilo utente e la gestione di sessione, piu i pezzi backend per proteggere le tue route. Installi il suo pacchetto, aggiungi le tue chiavi al tuo ambiente, avvolgi la tua app con il suo provider e deponi i componenti pronti all'uso. Le chiavi arrivano in due gusti: una publishable key (sicura nel codice frontend, identifica solo la tua app) e una secret key (solo backend). I percorsi di import esatti dipendono dal tuo framework, quindi segui la documentazione di Clerk per le righe precise.

# .env.local - dev keys, never committed (.env* is gitignored)
VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxx
CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx

Nota i prefissi test. Un'istanza di development emette chiavi che cominciano con pk_test e sk_test; un'istanza di produzione emette pk_live e sk_live. Questo prefisso e la tua verifica a colpo d'occhio dell'ambiente a cui appartiene una chiave, ed e di gran lunga il piu spesso confuso. Una volta poste le tue chiavi, avvolgi la tua app con il provider di Clerk e usi i suoi componenti.

// A protected page: only signed-in users see the content.
import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/clerk-react'

export function AppShell() {
  return (
    <header>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <UserButton />
      </SignedIn>
    </header>
  )
}

Istanza di development contro istanza di produzione

Clerk separa il tuo progetto in due istanze totalmente indipendenti. L'istanza di development e per costruire: usa chiavi test, gira su un dominio condiviso fornito da Clerk e viene con impostazioni allentate perche tu possa iterare in fretta. Non e destinata a veri utenti. L'istanza di produzione e la cosa vera: chiavi live, il tuo dominio, sicurezza piu stretta e il posto dove veri clienti si connettono. Le due non condividono ne utenti ne impostazioni - sono mondi separati. L'errore dei principianti e trattare l'istanza di development come sufficiente e puntarvi veri utenti, o pubblicare con chiavi pk_test ancora nel loro ambiente di produzione. Il flusso pulito e: costruire e testare tutto sull'istanza di development, poi creare l'istanza di produzione, configurarla (incluso un dominio personalizzato e OAuth) e commutare le tue variabili d'ambiente in deploy verso le chiavi pk_live e sk_live.

• Istanza di development: chiavi pk_test / sk_test, dominio Clerk condiviso, impostazioni allentate, per costruire soltanto.
• Istanza di produzione: chiavi pk_live / sk_live, il tuo dominio, impostazioni strette, per veri utenti.
• Sono mondi separati - utenti e configurazione non si trasferiscono automaticamente.
• Passare in live = creare l'istanza di produzione, configurarla, commutare le env var in deploy verso le chiavi live.

Percorso Google OAuth di produzione

Sull'istanza di development, Clerk ti lascia attivare il Google login con credential dev condivise, perche tu possa testare subito. Per la produzione, Google esige che tu usi le tue credential Google e un consent screen verificato, perche i tuoi utenti vedano il nome della tua app (non quello di Clerk) quando si connettono. E la parte che fa inciampare le persone, quindi ecco l'ordine che funziona. Le etichette esatte dei pulsanti nella Google Cloud Console si spostano col tempo, quindi fidati del flusso e segui la documentazione aggiornata di Clerk e Google per i click precisi.

• Crea (o scegli) un progetto per la tua app nella Google Cloud Console.
• Configura l'OAuth consent screen: poni il nome dell'app, l'e-mail di supporto e il tuo dominio. Aggiungi gli scope e-mail e profilo. Pubblicalo perche non resti in modalita test.
• Crea credential OAuth di tipo "OAuth client ID" per un'applicazione web. Google ti da un Client ID e un Client Secret.
• Aggiungi la redirect URI autorizzata che Clerk ti mostra nelle sue impostazioni di provider Google - e li che Google rimanda l'utente dopo l'approvazione.
• Incolla il Google Client ID e il Client Secret nelle impostazioni di provider Google di Clerk sulla tua istanza di produzione e attivalo.
• Test: connettiti con Google sul tuo dominio di produzione. Gli utenti dovrebbero vedere il nome della tua app sul consent screen Google, non uno generico.

Una trappola sottile: la redirect URI deve corrispondere esattamente, incluso https e senza differenza di slash finale. Se il login fallisce con un errore redirect_uri_mismatch, questa corrispondenza esatta e quasi sempre la causa. Copia l'URI parola per parola da Clerk.

Dominio personalizzato e DNS record

Un'istanza Clerk di produzione gira sul tuo dominio, perche l'auth abbia luogo per esempio ad accounts.yoursite.com o clerk.yoursite.com invece di un URL Clerk generico. Perche cio funzioni, aggiungi DNS record che Clerk ti da presso il tuo fornitore di dominio (o Cloudflare, del Corso 1). Sono soprattutto CNAME record che puntano un sottodominio verso i server di Clerk, perche Clerk possa servire e mettere in sicurezza quel sottodominio. Li aggiungi, attendi la propagazione DNS, e Clerk li verifica ed emette i certificati. Ecco la forma di cio che aggiungi - i tuoi veri valori vengono dal dashboard Clerk.

; DNS records you add at your provider (example shape - copy real values from Clerk)
; Type   Name (host)              Value (target)
CNAME    clerk                    frontend-api.clerk.services
CNAME    accounts                 accounts.clerk.services
CNAME    clkmail                  mail.xxxxx.clerk.services
CNAME    clk._domainkey           dkim1.xxxxx.clerk.services
CNAME    clk2._domainkey          dkim2.xxxxx.clerk.services

Se gestisci il DNS tramite Cloudflare, aggiungi questi in DNS-only (nuvola grigia, non proxato) salvo indicazione contraria di Clerk - proxare i sottodomini di auth puo rompere l'handshake TLS. Dopo aver salvato i record, la verifica puo impiegare da qualche minuto a qualche ora. Non e rotto, il DNS e solo lento, esattamente come hai imparato connettendo un dominio nel Corso 1.

Errori frequenti

I classici: pubblicare con chiavi pk_test ancora poste in produzione, cosicche veri utenti atterrano sulla tua istanza di development; dimenticare di pubblicare il consent screen Google, cosicche resta in modalita test dove solo gli account autorizzati possono connettersi; un redirect_uri_mismatch dovuto a una redirect URI che differisce di uno slash o di http contro https; proxare i DNS record Clerk tramite Cloudflare e rompere i certificati; e il piu profondo di tutti, voler costruire l'auth da zero "per imparare" e pubblicare un buco di sicurezza. Usa il servizio, verifica i tuoi prefissi di chiave, copia le redirect URI parola per parola.

ROI business

L'auth e puro rischio al ribasso quando la costruisci, e pura leva quando la compri. Una tabella di password trapelata e un incubo giuridico sotto il GDPR e le leggi di protezione dei dati statunitensi, piu una catastrofe di fiducia che puo uccidere un prodotto giovane. Clerk toglie tutta questa categoria di rischio per un costo mensile moderato e ti da il social login che aumenta in modo misurabile la conversione all'iscrizione, perche gli utenti detestano creare ancora una password. Pubblichi il login in un pomeriggio invece di due settimane, dormi la notte, e il tuo funnel d'iscrizione converte meglio. Non esiste nessuna versione del calcolo in cui l'auth fatta in casa vince per un fondatore che costruisce con gli agenti.

Checklist

Sei pronto ad andare avanti quando tutto questo e vero in una vera app, non solo in teoria.

• Sai spiegare OAuth in una frase: un provider di fiducia si fa garante dell'utente, perche tu non tenga mai la sua password.
• Clerk e installato, le chiavi sono in .env (gitignored), e l'UI connesso / disconnesso funziona.
• Conosci la differenza tra pk_test e pk_live e l'ambiente a cui ciascuno appartiene.
• Google OAuth funziona sul tuo dominio di produzione con il tuo consent screen e i giusti DNS record.

Risorse

Tieni aperti la documentazione di Clerk e la guida OAuth della Google Cloud Console mentre fai il setup di produzione - entrambe cambiano la loro UI esatta col tempo, e la documentazione e sempre aggiornata. Le pagine dei fondamenti su cos'e OAuth e cos'e il DNS sostengono i due concetti piu delicati qui. Poi, dai ai tuoi utenti connessi qualcosa da fare: veri dati con Convex.

La tua missione

Aggiungi Clerk a un'app di test sull'istanza di development e fai funzionare il login, poi attiva il Google login. Se possiedi un dominio, vai un gradino piu in la: crea un'istanza di produzione, metti in atto il consent screen Google e le credential, aggiungi i DNS record e conferma che un vero Google login sul tuo dominio funziona con il nome della tua app sul consent screen. Percorrere il cammino di produzione una volta toglie la paura per ogni app che costruisci in seguito.

Prossima lezione

Gli utenti possono connettersi. La prossima lezione da loro dei dati con Convex, un database reattivo e type-safe dove la tua logica backend e la tua UI restano sincronizzate automaticamente, e dove impari anche il pattern soft delete che ti lascia annullare un errore d'utente, invece di perdere dati per sempre.