// docs / baas security / clerk hardening

Checklist di sicurezza Clerk: 20 elementi

Clerk gestisce auth, sessioni e organizzazioni per la tua app — il che significa che un'integrazione Clerk mal configurata è un bypass di auth, un vettore di session-fixation o un percorso di leak tra org. Questa checklist è un audit di 20 elementi attraverso chiavi, configurazione di sessione, webhook, organizzazioni, template JWT e monitoraggio continuo. Gli strumenti di codifica IA cablano Clerk rapidamente con default ragionevoli; questa lista cattura gli elementi che lasciano sul tavolo.

Per il contesto sul perché le configurazioni errate a livello di auth sono un punto debole degli strumenti IA, vedi Perché gli strumenti di codifica IA lasciano lacune di sicurezza. Per la checklist parallela su Auth0, vedi Checklist di sicurezza Auth0.

Chiavi d'ambiente e allowlist di origine

Clerk emette due chiavi distinte per progetto. Mescolarle o farle trapelare è la prima modalità di fallimento.

Usa la chiave pubblicabile (pk_live_* in produzione, pk_test_* in dev) nel browser; usa la chiave segreta (sk_live_* / sk_test_*) solo sul server. La chiave pubblicabile è sicura in NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY; la chiave segreta non deve mai portare un prefisso env pubblico e non deve mai apparire in un componente client.
Verifica che l'app di produzione usi pk_live_*, non pk_test_*. Le istanze di test permettono indirizzi email non verificati e MFA disabilitato — spedire test mode in produzione è un bypass di auth.
Configura le origini permesse nella dashboard Clerk. Settings → Domains → Allowed origins deve elencare esattamente il tuo dominio di produzione. Liste di origini vuote o con wildcard permettono agli attaccanti di creare frontend Clerk fasulli che parlano al tuo backend.
Ruota la chiave segreta a ogni partenza o leak sospetto. Dashboard → API Keys → Reset. La vecchia chiave viene invalidata; rideploya il codice lato server con il nuovo valore prima di ruotare.

Configurazione di sessione

La scadenza della sessione e i timeout di inattività sono la differenza tra una sessione rubata che diventa un incidente di 10 minuti o di 30 giorni.

Imposta il timeout di inattività di sessione a 30 minuti o meno per app SaaS che gestiscono dati sensibili. Dashboard → Sessions → Inactivity timeout. App banking-tier dovrebbero usare 5-10 minuti; SaaS standard 30-60 minuti; app consumer 1-7 giorni. Default è 7 giorni.
Abilita la revoca di sessione al cambio password, cambio email e iscrizione MFA. Dashboard → Sessions → Revoke on. Sono eventi di sicurezza iniziati dall'utente; le sessioni esistenti su altri dispositivi dovrebbero essere terminate.
Verifica le sessioni lato server su ogni rotta protetta, non solo al sign-in. In Next.js: const { userId } = await auth(); in un componente server / rotta API legge il JWT dal cookie e lo valida. Non fidarti mai solo di un controllo cookie.
Imposta SameSite=Lax (default) o Strict sul cookie di sessione. Verifica in DevTools → Application → Cookies. SameSite=None è un vettore CSRF — non usarlo mai a meno che tu non abbia esplicitamente configurato un setup auth cross-dominio.

Verifica dei webhook

I webhook Clerk si attivano su eventi del ciclo di vita dell'utente (created, updated, deleted, session.ended). Sono il meccanismo di sincronizzazione per il tuo database — e un webhook falsificato è una primitiva di scrittura database.

Verifica la firma Svix su ogni webhook. I webhook Clerk sono firmati da Svix. Usa new Webhook(secret).verify(body, headers). Rifiuta con 401 se la verifica fallisce.
Memorizza il segreto del webhook in una variabile d'ambiente, mai nel codice. Il segreto ruota a ogni rigenerazione dalla dashboard — il tuo deploy deve leggerlo dall'env, non da una costante.
Idempotenza su ogni handler. Le consegne di webhook possono ripetersi. Usa l'header svix-id come chiave primaria in una tabella webhook_events per deduplicare. Avvolgi il cambio di stato e l'inserimento di idempotenza nella stessa transazione.
Su user.deleted, hard-delete o anonimizza PII entro 24 ore. GDPR / CCPA lo richiedono. Audita il percorso di cancellazione: quali tabelle contengono i dati di questo utente? Usa FK ON DELETE CASCADE dove puoi.

Organizzazioni e permessi

Se usi Clerk Organizations, il confine dell'org è il tuo isolamento di tenant. Ogni query lato server deve filtrare per esso.

Su ogni rotta API, leggi sia userId che orgId da auth() e filtra le query del database per entrambi. WHERE org_id = $orgId AND user_id = $userId. Non fidarti mai di un org_id dal body della richiesta.
<strong>Use Clerk role checks for privileged operations, not boolean checks against the user object.</strong> <code>has({ role: 'org:admin' })</code> reads the role from the verified JWT. A user can spoof a boolean on a stale client object; they cannot spoof a JWT claim.
Testa l'isolamento cross-org con due account org reali. Crea Org A, popola dati, accedi a Org B in un altro browser, prova a leggere i dati di Org A via API. La risposta deve essere 403 o 404.

Template JWT e integrazioni esterne

I template JWT spingono l'identità Clerk in Supabase, Firebase e altri servizi downstream. I template mal configurati condividono claim in eccesso o espongono dati che non intendevi.

Per ogni template JWT, elenca ogni claim e conferma che è necessario. Dashboard → JWT Templates. Un template che spedisce email e phone a Supabase espone PII a chiunque legga il JWT nel browser.
Imposta scadenza breve sui template JWT usati per chiamate downstream client-side. 60 secondi per richieste API downstream è lo standard. I JWT di vita più lunga vengono rubati e rigiocati.
Verifica il claim audience (aud) sul lato ricevente. Supabase, Firebase, ecc. dovrebbero controllare che aud corrisponda all'identificatore di servizio atteso. Senza questo, un JWT emesso per il servizio A può autenticarsi al servizio B.

Monitoraggio operativo

Auth è la sorgente di log a più alto segnale che hai. Osservala.

Allerta su picchi di login falliti per IP / per account. Un tasso di fallimento 50× il normale è un attacco di credential stuffing. Clerk emette questi eventi a webhook; instradali al tuo SIEM.
Revisione trimestrale della deriva delle impostazioni di sessione e istanza. I default cambiano con gli aggiornamenti Clerk; le "vecchie configurazioni" diventano silenziosamente sbagliate nel tempo. Confronta l'export JSON della dashboard con la tua ultima copia known-good.

Prossimi passi

Esegui una scansione FixVibe contro la tua URL di produzione — il check baas.clerk-auth0 segnala chiavi pubblicabili Clerk, chiavi di test in produzione e chiavi segrete nel bundle. Per la checklist equivalente su Auth0, vedi Checklist di sicurezza Auth0. Per la panoramica sui provider BaaS, leggi Scanner di configurazioni errate BaaS.