D DOKUBASIS
Blog Dev

Débogage localhost sur Android : redirection de ports, pilotes ADB et fenêtre RSA absente

Un bouton qui en chevauche un autre dans le navigateur mobile, une application Spring Boot derrière une couche OAuth stricte et un ordinateur Windows qui ne reconnaît pas le smartphone. Ce qui ressemble à une petite correction CSS se transforme rapidement en odyssée de débogage. Une analyse approfondie destinée aux développeurs web confrontés à la redirection de ports de Chrome, à des pilotes ADB défectueux et à des fenêtres de débogage USB qui refusent de s’afficher.

Les développeurs web connaissent bien ce phénomène : l’application web s’affiche parfaitement dans le navigateur sur l’écran d’un ordinateur. La vue mobile des Chrome DevTools ne révèle elle non plus aucune erreur. Pourtant, dès que vous ouvrez la page sur un véritable smartphone Android, dans Edge ou Chrome par exemple, des éléments importants de l’interface disparaissent soudainement ou des boutons se chevauchent.

Le problème : bugs CSS, Edge mobile et piège OAuth

Le coupable est souvent vite identifié : la propriété CSS height: 100vh. Les navigateurs mobiles, en particulier ceux dont la barre d’adresse se trouve en bas comme Edge mobile, calculent souvent cette valeur à partir de la hauteur maximale de l’écran. Ils ignorent alors la barre de menu dynamique qui apparaît et disparaît pendant le défilement. Conséquence : le bas de la mise en page dépasse de la zone visible.

Aujourd’hui, la solution est généralement triviale : utiliser height: 100dvh (Dynamic Viewport Height), qui tient correctement compte de ces barres.

Mais comment tester cette correction en local lorsque l’application est plus complexe ?

Pourquoi Cloudflare Tunnel échoue souvent avec OAuth

Pour effectuer des tests mobiles temporaires, de nombreux développeurs se tournent vers des services tels que Cloudflare Quick Tunnels (trycloudflare.com). Le problème : à chaque démarrage, ceux-ci génèrent un nouveau sous-domaine aléatoire.

Si votre application, par exemple un backend Spring Boot, est protégée par une connexion OAuth2 (Google, GitHub, Auth0), le fournisseur exige une URI de redirection strictement enregistrée. Une URL Cloudflare aléatoire provoque une erreur « Redirect URI mismatch ». Même désactiver temporairement la sécurité dans le code est souvent impossible lorsque des données essentielles de l’application, telles que les rôles utilisateur, sont chargées directement depuis le profil OAuth authentifié.

La solution la plus élégante est la redirection de ports de Chrome via le débogage USB. Le smartphone transfère ses requêtes par le câble USB vers le localhost du PC de développement. Le fournisseur OAuth voit toujours la redirection propre et autorisée vers localhost:8080.

Mais sous Windows, le chemin pour y parvenir est souvent semé d’embûches.

Obstacle 1 : le Gestionnaire de périphériques Windows et l’absence de pilote

La première étape logique consiste à ouvrir les options pour les développeurs de l’appareil Android, à activer le débogage USB et à connecter le téléphone au PC par câble. Mais dans les Chrome DevTools, à l’adresse chrome://inspect/#devices, aucun appareil n’apparaît.

Un coup d’œil dans le Gestionnaire de périphériques Windows révèle généralement le problème : le smartphone est bien reconnu comme périphérique de stockage MTP, mais l’interface de débogage est absente ou accompagnée d’un point d’exclamation jaune (« ADB Interface »). Il manque tout simplement à Windows les pilotes nécessaires au débogage Android.

Installer les pilotes ADB en tant qu’administrateur

Pour installer correctement le pilote à l’échelle du système, vous devez impérativement lancer le Gestionnaire de périphériques avec des droits d’administrateur. Sinon, Windows refuse l’attribution manuelle du pilote.

  1. Ouvrez l’invite de commandes en tant qu’administrateur : appuyez sur la touche Windows, saisissez cmd, faites un clic droit sur « Invite de commandes », puis sélectionnez « Exécuter en tant qu’administrateur ».
  2. Forcez l’ouverture du Gestionnaire de périphériques : saisissez la commande devmgmt.msc, puis appuyez sur Entrée.
  3. Téléchargez et installez le pilote : téléchargez le pilote USB de Google officiel et décompressez le fichier ZIP.
  4. Dans le Gestionnaire de périphériques, faites un clic droit sur le « Périphérique inconnu » accompagné du point d’exclamation, sélectionnez Mettre à jour le pilote, puis Parcourir mon ordinateur pour rechercher des pilotes, et choisissez le dossier décompressé.

Une fois l’installation terminée, l’appareil devrait apparaître correctement sous le nom « Android Composite ADB Interface ».

Obstacle 2 : « Offline » - pourquoi la fenêtre de débogage USB ne s’affiche pas

Les pilotes sont installés et le téléphone est connecté, mais à l’adresse chrome://inspect, Chrome indique toujours que l’appareil est hors connexion. Avec cette précision fatidique : « Authentification en attente : veuillez accepter la session de débogage sur l’appareil. »

À cet instant, la fenêtre RSA devrait normalement s’afficher sur le smartphone : « Autoriser le débogage USB ? L’empreinte de la clé RSA de cet ordinateur est… » Sans cette confirmation cryptographique, Android bloque catégoriquement l’accès du PC. Mais rien n’apparaît à l’écran. Même révoquer les autorisations de débogage USB ou essayer un autre smartphone ne change rien.

Le conflit entre Chrome et le démon ADB

L’explication se trouve dans l’architecture de Chrome. Le navigateur intègre sa propre routine de détection USB. Celle-ci s’appuie en arrière-plan sur une communication avec le démon ADB (adb.exe, Android Debug Bridge). Mais si ce service d’arrière-plan ne fonctionne pas sur le PC, s’est bloqué ou ne peut pas être correctement déclenché par Chrome faute de droits suffisants, la négociation RSA indispensable n’est jamais envoyée via le port USB.

Le smartphone attend une demande d’autorisation que le PC n’envoie jamais.

La correction : forcer manuellement la négociation ADB

Lorsque Chrome échoue, vous devez initialiser manuellement la connexion matérielle depuis l’invite de commandes. Pour cela, il vous faut les outils bruts et officiels de Google.

Procédure de résolution étape par étape

  1. Téléchargez les Platform-Tools : téléchargez les Android Platform-Tools. Aucune installation n’est nécessaire. Décompressez simplement le fichier ZIP dans un dossier, par exemple sur le Bureau.
  2. Vérifiez le mode MTP du smartphone (important !) : pour des raisons de sécurité, notamment pour se protéger du « juice jacking » sur les bornes de recharge publiques, les versions modernes d’Android bloquent les lignes de données lorsque l’appareil est réglé sur « Recharge uniquement ». Dans les paramètres USB du téléphone, sélectionnez impérativement « Transfert de fichiers » (MTP).
  3. Démarrez ADB manuellement : ouvrez l’Explorateur de fichiers Windows dans le dossier où vous avez décompressé les Platform-Tools. Cliquez sur la barre d’adresse en haut, saisissez cmd, puis appuyez sur Entrée. Le terminal s’ouvre directement dans ce répertoire.
  4. La commande décisive : saisissez la commande suivante, puis appuyez sur Entrée :
adb devices

Ce qui se passe en arrière-plan : le système indique alors : * daemon not running; starting now at tcp:5037. Le démon ADB démarre de force et analyse activement les ports USB. Il utilise le pilote Windows précédemment réparé et lance la négociation RSA avec le smartphone.

Le résultat : à l’instant précis où la commande s’exécute, la fenêtre tant attendue « Autoriser le débogage USB ? » apparaît sur l’écran du smartphone.

Dernière étape : activer et tester la redirection de ports

Une fois que vous avez coché « Toujours autoriser sur cet ordinateur » et validé la fenêtre sur le téléphone, la configuration est terminée :

  1. Dans Chrome, revenez à l’adresse chrome://inspect/#devices. Le message « Hors connexion » a disparu et l’appareil figure désormais parmi les périphériques actifs.
  2. À côté de l’appareil, cliquez sur « Redirection de port… ».
  3. Saisissez 8080, ou le port de votre application Spring Boot, comme port.
  4. Saisissez localhost:8080 comme adresse de destination.
  5. Cochez « Activer la redirection de port », puis validez.

Ouvrez maintenant Edge ou Chrome sur le smartphone et saisissez http://localhost:8080 dans la barre d’adresse. Le trafic est acheminé en toute sécurité par le câble USB vers votre PC. L’application se charge, la redirection OAuth vers localhost fonctionne parfaitement, les rôles sont correctement récupérés depuis la base de données et vous pouvez enfin vous consacrer à la correction du bug CSS initial.

Conclusion : lorsque des technologies web comme OAuth et CSS rencontrent des interfaces matérielles comme ADB et les protocoles USB, les symptômes sont souvent difficiles à interpréter. Une fenêtre RSA qui reste muette indique rarement un smartphone défectueux : le responsable est le plus souvent un démon ADB qui ne s’est pas lancé. Garder la commande adb devices et le mode administrateur du Gestionnaire de périphériques Windows dans votre boîte à outils vous épargnera des heures de recherches infructueuses.