Come aggiungere l'autenticazione a due fattori alla tua app

Per aggiungere l'autenticazione a due fattori (2FA) alla tua app, permetti agli utenti di collegare un'app di autenticazione scansionando un codice QR, chiedi il codice a sei cifre che mostra dopo la password, e crea una sessione completa sul server solo quando quel codice è corretto. Assegna a ogni utente codici di recupero monouso quando attiva la 2FA, limita quanti codici qualcuno può indovinare, e richiedi la password più un codice attuale prima di poter disattivare la 2FA. Se usi un provider di autenticazione ospitato, attiva la sua opzione multi-fattore integrata invece di costruirne una tua.

Questa guida descrive le scelte, il flusso esatto, i prompt da dare a un builder IA e gli errori che fanno sembrare la 2FA presente quando in realtà non fa nulla. Se il concetto è nuovo, parti da cos'è l'autenticazione a due fattori.

Prima di iniziare: ti serve un login funzionante

La 2FA si appoggia su un accesso già esistente. Ti serve prima uno di questi:

• Un login tuo, con utenti e password sottoposte ad hash memorizzati nel database della tua app.
• Un provider di autenticazione ospitato che gestisce gli utenti per te.

Se non ne hai ancora nessuno, inizia da come aggiungere il login alla tua app. Il resto di questa guida presuppone che un passaggio con la password funzioni già.

Scegli il secondo fattore

TOTP significa time-based one-time password, lo standard (RFC 6238) usato dalle app di autenticazione. Il tuo server e il telefono dell'utente condividono un segreto; entrambi generano lo stesso codice breve a partire da quel segreto e dall'ora attuale, che di solito cambia ogni 30 secondi. Non serve una connessione di rete né un provider SMS.

Le passkey sostituiscono o affiancano le password con una chiave crittografica memorizzata sul dispositivo dell'utente. Sono più forti ma più impegnative da costruire da soli, quindi molte app partono dal TOTP e aggiungono le passkey in seguito, oppure le ottengono da un provider di autenticazione.

Costruirla o attivarla?

Verifica la documentazione attuale del tuo provider per sapere quali fattori supporta e con quali piani. In ogni caso, non scrivere mai da solo la matematica per generare i codici; usa una libreria molto diffusa.

Decidi prima la politica

Rispondi a queste domande prima di scrivere il prompt, perché cambiano il design:

1. Chi deve usarla? Facoltativa per tutti, obbligatoria per amministratori e staff, o obbligatoria per tutti. Richiederla a chiunque abbia poteri di amministrazione è comune. Vedi controllo degli accessi basato sui ruoli.
2. Con che frequenza gli utenti reinseriscono un codice? A ogni login, oppure una volta per dispositivo per 30 giorni ("ricorda questo dispositivo").
3. Quali azioni richiedono una nuova verifica? Cambiare l'email, i dati di pagamento o disattivare la 2FA sono buoni candidati. Si chiama autenticazione step-up.
4. Qual è il processo per il telefono perso? Codici di recupero, più un ripiego manuale che sei disposto a gestire.

Passo dopo passo: 2FA con TOTP sul tuo login

1. Memorizza i campi giusti

Ogni utente ha bisogno di: se la 2FA è attiva, il segreto TOTP (cifrato a riposo, non in chiaro), il momento in cui è stata attivata, e un elenco di codici di recupero memorizzati con hash, come le password. Aggiungi un punto dove contare i tentativi falliti.

2. Registrazione

1. L'utente apre le Impostazioni e clicca Attiva l'autenticazione a due fattori.
2. Il server genera un nuovo segreto e lo restituisce come QR code, più la versione testuale per chi non può scansionare.
3. L'utente lo scansiona in un'app di autenticazione e digita il codice attuale.
4. Il server verifica il codice. Solo se è corretto salva il segreto e segna la 2FA come attiva.
5. L'app mostra 8–10 codici di recupero una sola volta e chiede all'utente di salvarli.

Il passo 4 è importante: attivare la 2FA prima di confermare un codice blocca chiunque abbia sbagliato la scansione.

3. Login con un secondo passaggio

1. L'utente invia email e password. Il server le verifica.
2. Se la 2FA è attiva, il server non crea una sessione completa. Crea invece uno stato "secondo fattore in attesa" di breve durata.
3. L'app mostra la schermata del codice. Il server verifica il codice, concedendo una piccola finestra per lo scostamento dell'orologio.
4. Solo ora il server emette la sessione vera.

Ogni route protetta ed endpoint API deve rifiutare lo stato in attesa. Una schermata 2FA che nasconde le pagine solo nel browser può essere saltata chiamando direttamente l'API.

4. Limiti e avvisi

Un codice a sei cifre ha un milione di combinazioni, quindi è indovinabile senza limiti. Limita i tentativi, blocca il secondo passaggio per un periodo dopo ripetuti errori, e invia un'email all'utente quando succede. Vedi rate limiting e inviare email dalla tua app.

5. Recupero e disattivazione

• Un codice di recupero funziona una sola volta, poi viene eliminato.
• Disattivare la 2FA richiede la password e un codice attuale o un codice di recupero.
• Rigenerare i codici di recupero invalida il vecchio set.
• Invia un'email all'utente ogni volta che la 2FA viene attivata o disattivata.

Prompt da dare al tuo builder IA

Inizia dal flusso principale:

Aggiungi l'autenticazione a due fattori opzionale con app di autenticazione (TOTP) al nostro login esistente con email e password. Usa una libreria TOTP molto diffusa, non scrivere tu l'algoritmo. Nelle Impostazioni, mostra un QR code e il segreto in testo, e attiva la 2FA solo dopo che l'utente inserisce un codice valido. Memorizza il segreto cifrato e non mostrarlo più dopo la configurazione. Mostra 10 codici di recupero monouso una sola volta e memorizzali con hash.

Poi l'applicazione, che è dove il codice generato spesso non basta:

Applica la 2FA sul server. Dopo una password corretta, gli utenti con la 2FA attiva ottengono uno stato in attesa di breve durata, non una sessione completa. Ogni pagina ed endpoint API protetto deve rifiutare lo stato in attesa. Limita i tentativi del codice a 5, poi blocca il secondo passaggio per 15 minuti e invia un'email all'utente.

Poi la politica:

Richiedi la 2FA per gli account amministratore: un amministratore senza 2FA viene mandato alla configurazione e non può accedere alla dashboard finché non la completa. Richiedi la password e un codice attuale per disattivare la 2FA o cambiare l'email dell'account. Invia un'email all'utente quando la 2FA viene attivata o disattivata.

Infine, chiedi all'agente di spiegare cosa ha costruito:

Elenca ogni route che verifica il completamento del secondo fattore, dove sono memorizzati il segreto TOTP e i codici di recupero, e come sono protetti.

Errori comuni

• Sessione emessa dopo la password. Il bug più grave. Se la sessione completa esiste prima che il codice venga verificato, la 2FA è solo decorazione. Testa chiamando un'API protetta dopo il solo passaggio della password.
• Nessun limite ai tentativi. Tentativi illimitati rendono il codice vulnerabile a un attacco a forza bruta.
• Segreti o codici di recupero in chiaro. Una fuga dal database consegna a chiunque il secondo fattore di tutti.
• Attivare prima di verificare. Gli utenti che hanno scansionato male vengono bloccati al login successivo.
• Nessun percorso di recupero. Ogni telefono perso diventa un ticket di supporto o un cliente perso.
• Disattivazione facile. Se una sessione rubata può disattivare la 2FA senza un codice, la protezione è finita.
• Codici nei log. Assicurati che codici e segreti non compaiano mai nei log del server o nei messaggi di errore.
• Controllo solo nella pagina di login. Il reset della password, l'accesso con "magic link" e qualsiasi login social devono rispettare anch'essi la 2FA, altrimenti diventano un modo per aggirarla.

Checklist di test

• La registrazione si completa solo dopo un codice valido
• Il login con una password corretta ma senza codice non dà accesso a nessuna pagina o API protetta
• Un codice errato viene rifiutato; errori ripetuti attivano il blocco e un'email
• Un codice di qualche minuto fa viene rifiutato
• Ogni codice di recupero funziona esattamente una volta
• Disattivare la 2FA richiede la password e un codice attuale
• Il reset della password non aggira la 2FA
• Gli amministratori senza 2FA non possono accedere alle pagine di amministrazione (se è richiesta)
• Segreti e codici di recupero sono cifrati o sottoposti ad hash nel database
• Nessun codice o segreto compare nei log

Esegui anche la checklist di sicurezza per le app create con l'IA completa prima del lancio.

Aggiungere la 2FA in Mythex

Mythex non include un sistema di login integrato per gli utenti finali della tua app, quindi la 2FA fa parte dell'approccio di autenticazione che scegli: il tuo login con email e password che usa il database del progetto, oppure un provider ospitato con supporto multi-fattore. Descrivi ciò che vuoi in chat con prompt come quelli sopra, e le chiavi dei provider vanno nei segreti del progetto (tramite /secrets, le impostazioni del progetto o la scheda dei segreti che l'agente mostra) invece che nel campo del messaggio. La ricetta della documentazione Aggiungere il login alla tua app contiene un prompt di partenza, e Sicurezza per le app che crei copre le buone abitudini su chiavi e permessi. Dopo che l'agente ha finito, testa ogni voce della checklist nell'Anteprima prima di pubblicare.

Domande