D DOKUBASIS
Dev Blog

Debug di localhost su Android: port forwarding, driver ADB e popup RSA mancante

Un pulsante che si sovrappone ad altri elementi nel browser mobile, un’app Spring Boot protetta da un rigido sistema OAuth e un computer Windows che non riconosce lo smartphone. Quello che sembra un piccolo intervento sul CSS si trasforma rapidamente in un’odissea di debug. Un’analisi approfondita per gli sviluppatori web alle prese con il port forwarding di Chrome, driver ADB difettosi e popup per il debug USB che si rifiutano di comparire.

Chi sviluppa per il web conosce bene il fenomeno: nel browser sul monitor desktop l’applicazione web ha un aspetto impeccabile. Anche la visualizzazione mobile nei Chrome DevTools non mostra errori. Ma quando apri la pagina su un vero smartphone Android, per esempio nel browser Edge o Chrome, alcuni elementi importanti dell’interfaccia scompaiono improvvisamente oppure i pulsanti si sovrappongono.

Il problema: bug CSS, Edge mobile e la trappola di OAuth

Spesso il colpevole viene individuato rapidamente: la proprietà CSS height: 100vh. I browser mobile, soprattutto quelli con una barra degli indirizzi nella parte inferiore come Edge per dispositivi mobili, calcolano spesso questo valore in base all’altezza massima dello schermo. In questo modo ignorano la barra dinamica dei menu, che compare e scompare durante lo scorrimento. Il risultato è che il layout si estende oltre il margine inferiore dell’area visibile.

Oggi la soluzione è generalmente semplice: usare height: 100dvh (Dynamic Viewport Height), che tiene correttamente conto di queste barre.

Ma come puoi verificare questa correzione in locale se l’applicazione è più complessa?

Perché Cloudflare Tunnel spesso non funziona con OAuth

Per i test temporanei su dispositivi mobili, molti sviluppatori ricorrono a servizi come Cloudflare Quick Tunnels (trycloudflare.com). Il problema è che a ogni avvio generano un nuovo sottodominio casuale.

Se la tua applicazione, per esempio un backend Spring Boot, è protetta da un accesso OAuth2 (Google, GitHub, Auth0), il provider richiede un URI di reindirizzamento registrato in modo rigoroso. Un URL Cloudflare casuale provoca un errore «Redirect URI mismatch». Anche disattivare temporaneamente la sicurezza nel codice è spesso impossibile se dati importanti dell’applicazione, come i ruoli utente, vengono caricati direttamente dal profilo OAuth autenticato.

La soluzione più elegante è il port forwarding di Chrome tramite debug USB. Lo smartphone inoltra le proprie richieste attraverso il cavo USB al localhost del computer di sviluppo. Il provider OAuth continua a vedere il reindirizzamento valido e autorizzato verso localhost:8080.

Su Windows, però, arrivare a questo risultato è spesso un percorso a ostacoli.

Ostacolo 1: Gestione dispositivi di Windows e il vuoto dei driver

Il primo passaggio logico conduce alle opzioni sviluppatore del dispositivo Android: attivare il debug USB e collegare il telefono al computer via cavo. Nei Chrome DevTools, all’indirizzo chrome://inspect/#devices, però, non compare assolutamente nulla.

Uno sguardo a Gestione dispositivi di Windows rivela generalmente il problema: lo smartphone viene riconosciuto come dispositivo di archiviazione MTP, ma l’interfaccia di debug è assente oppure è contrassegnata da un punto esclamativo giallo («ADB Interface»). A Windows mancano semplicemente i driver appropriati per il debug di Android.

Installare i driver ADB come amministratore

Per installare correttamente il driver a livello di sistema, devi necessariamente avviare Gestione dispositivi con privilegi di amministratore, altrimenti Windows impedisce l’assegnazione manuale del driver.

  1. Apri il prompt dei comandi come amministratore: premi il tasto Windows, digita cmd, fai clic con il pulsante destro del mouse su «Prompt dei comandi» e seleziona «Esegui come amministratore».
  2. Avvia Gestione dispositivi: digita il comando devmgmt.msc e premi Invio.
  3. Scarica e installa il driver: scarica il driver USB di Google ufficiale ed estrai il file ZIP.
  4. In Gestione dispositivi, fai clic con il pulsante destro del mouse sul «Dispositivo sconosciuto» contrassegnato dal punto esclamativo, seleziona Aggiorna driver, poi Cerca i driver nel computer e scegli la cartella estratta.

Dopo l’installazione, il dispositivo dovrebbe essere elencato correttamente come «Android Composite ADB Interface».

Ostacolo 2: «Offline» - perché il popup per il debug USB non compare

I driver sono installati e il telefono è collegato, ma all’indirizzo chrome://inspect Chrome continua a indicare il dispositivo soltanto come Offline. A complicare la situazione compare il messaggio: «Autenticazione in sospeso: accetta la sessione di debug sul dispositivo.»

A questo punto sullo smartphone dovrebbe comparire il cosiddetto popup RSA: «Consentire debug USB? L’impronta digitale della chiave RSA del computer è…» Senza questa conferma crittografica, Android blocca categoricamente l’accesso del computer. Eppure sullo schermo non compare nulla. Nemmeno reimpostare le autorizzazioni di debug o provare un altro smartphone risolve il problema.

Il conflitto tra Chrome e il daemon ADB

La risposta risiede nell’architettura di Chrome. Il browser include una propria procedura integrata per il rilevamento USB, che si basa sulla comunicazione in background con il daemon ADB (adb.exe, Android Debug Bridge). Se questo servizio in background non è in esecuzione sul computer, si è bloccato oppure Chrome non dispone dei permessi necessari per attivarlo correttamente, l’handshake RSA richiesto non viene mai inviato attraverso la porta USB.

Lo smartphone resta in attesa di una richiesta di autorizzazione che il computer non invia mai.

La soluzione: forzare manualmente l’handshake ADB

Quando Chrome non riesce nell’operazione, devi inizializzare manualmente la connessione hardware tramite il prompt dei comandi. Per farlo servono gli strumenti ufficiali essenziali di Google.

Procedura dettagliata per risolvere il problema

  1. Scarica i Platform-Tools: scarica gli Android Platform-Tools. Non richiedono alcuna installazione. Ti basta estrarre il file ZIP in una cartella, per esempio sul desktop.
  2. Controlla la modalità MTP sullo smartphone (importante!): per motivi di sicurezza, per esempio per proteggere dal «juice jacking» presso le stazioni di ricarica pubbliche, le versioni moderne di Android bloccano le linee dati quando il dispositivo è impostato su «Solo ricarica». Nelle impostazioni USB del telefono, seleziona obbligatoriamente «Trasferimento dati» (MTP).
  3. Avvia ADB manualmente: apri Esplora file di Windows nella cartella in cui hai estratto i Platform-Tools. Fai clic sulla barra degli indirizzi in alto, digita cmd e premi Invio. Il terminale si apre esattamente in questa directory.
  4. Il comando decisivo: digita il comando seguente e premi Invio:
adb devices

Cosa accade in background: il sistema segnala ora: * daemon not running; starting now at tcp:5037. Il daemon ADB viene avviato forzatamente ed esegue una scansione attiva delle porte USB. Utilizza il driver Windows appena corretto e avvia l’handshake RSA con lo smartphone.

Il risultato: proprio nel momento in cui esegui il comando, sullo schermo dello smartphone compare finalmente il tanto atteso popup «Consentire debug USB?».

Il passaggio finale: attivare e verificare il port forwarding

Dopo aver confermato il popup sul telefono selezionando «Consenti sempre da questo computer», la configurazione è completa:

  1. Torna in Chrome all’indirizzo chrome://inspect/#devices. Il messaggio «Offline» è scomparso e il dispositivo risulta attivo nell’elenco.
  2. Accanto al dispositivo, fai clic su «Inoltro porte…».
  3. Inserisci come porta 8080 oppure la porta della tua applicazione Spring Boot.
  4. Inserisci come indirizzo di destinazione localhost:8080.
  5. Seleziona «Attiva inoltro porte» e conferma.

Ora apri Edge o Chrome sullo smartphone e digita http://localhost:8080 nella barra degli indirizzi. Il traffico viene instradato in modo sicuro attraverso il cavo USB verso il tuo computer. L’applicazione viene caricata, il reindirizzamento OAuth verso localhost funziona alla perfezione, i ruoli vengono caricati correttamente dal database e puoi finalmente dedicarti alla correzione del bug CSS iniziale.

Conclusione: Quando tecnologie web come OAuth e CSS incontrano interfacce hardware come ADB e protocolli USB, spesso è difficile interpretare l’origine degli errori. Un popup RSA che non compare raramente indica uno smartphone difettoso: nella maggior parte dei casi, il problema è un daemon ADB inattivo. Avere nel proprio arsenale il comando adb devices e la modalità amministratore di Gestione dispositivi di Windows permette di risparmiare ore di inutili tentativi.