Ajoutez la connexion à votre application Flutter pour Windows

Ce guide explique comment intégrer Auth0 à une application de bureau Flutter pour Windows à l’aide de l’Auth0 Flutter SDK (bêta).

Prérequis :

• Flutter SDK 3.24.0+ et Dart 3.5.0+.
• Windows 10 ou version ultérieure.
• Visual Studio 2022 avec la charge de travail Desktop development with C++.
• Compte Auth0 — inscrivez-vous gratuitement.

Cette fonctionnalité est en bêta (auth0_flutter 2.1.0-beta.1). L’API pourrait changer avant sa disponibilité générale.

Ce guide vous montre comment ajouter la connexion, la déconnexion et l’affichage du profil utilisateur à une application de bureau Windows avec Flutter à l’aide du SDK auth0_flutter et d’OAuth 2.0 Flux du code d’autorisation + PKCE.

​

Pour commencer

1. Créer un projet Flutter pour Windows

   Créez un nouveau projet Flutter compatible avec la plateforme Windows.

   flutter create --platforms=windows my_app
   cd my_app
   

   Assurez-vous que Windows est disponible :

   flutter devices
   

   Vous devriez voir un appareil Windows de bureau dans la liste.

   Exécutez flutter doctor pour vérifier que votre environnement est correctement configuré et que Visual Studio 2022 avec les outils de développement d’applications de bureau en C++ est détecté.

2. Installez le SDK Auth0 Flutter

   Ajoutez la version bêta du SDK qui prend en charge Windows :

   flutter pub add auth0_flutter:2.1.0-beta.1
   flutter pub add flutter_dotenv
   

   Votre pubspec.yaml doit inclure :

   Le SDK Auth0 Flutter nécessite Flutter 3.24.0+ et Dart 3.5.0+. La plateforme Windows nécessite également Visual Studio 2022 avec la charge de travail de développement d’applications de bureau en C++.

3. Configurer Auth0

   Créez ou configurez une application Auth0 avec les URL de rappel requises pour l’authentification d’une application de bureau Windows.

   Configuration rapide

   Créez une application Native dans votre Auth0 Dashboard avec les paramètres suivants :

   Champ	Valeur
   Allowed Callback URLs	auth0flutter://callback
   Allowed Logout URLs	auth0flutter://callback

   Vos identifiants :

   • Domain: {yourDomain}
   • Client ID: {yourClientId}

   CLI

   auth0 apps create \
     --name "My Flutter Windows App" \
     --type native \
     --callbacks "auth0flutter://callback" \
     --logout-urls "auth0flutter://callback"
   

   Dashboard

   1. Accédez à Auth0 Dashboard → Applications > Applications.
   2. Sélectionnez Create Application.
   3. Donnez-lui le nom “My Flutter Windows App” et choisissez Native comme type d’application.
   4. Accédez à l’onglet Settings de votre nouvelle application.
   5. Définissez Allowed Callback URLs sur auth0flutter://callback.
   6. Définissez Allowed Logout URLs sur auth0flutter://callback.
   7. Faites défiler la page vers le bas et cliquez sur Save Changes.
   8. Copiez les valeurs Domain et Client ID en haut de la page Application Settings.

   L’URL auth0flutter://callback est un schéma personnalisé qui redirige le callback du navigateur vers votre application de bureau une fois l’authentification terminée.

4. Configurer les variables d’environnement

   Créez un fichier .env à la racine de votre projet :

   Ajoutez le fichier .env à vos ressources Flutter dans pubspec.yaml :

   Ne mettez jamais votre fichier .env dans le contrôle de version. Ajoutez-le à .gitignore.

5. Configurer le runner Windows

   Le flux d’authentification Windows nécessite d’intégrer le callback au runner de votre application. Le plugin Flutter ne reçoit pas automatiquement les activations de schéma de protocole du système d’exploitation — vous devez donc ajouter la gestion d’une instance unique et la transmission des URI.

   Remplacez le contenu de windows/runner/main.cpp :

   Ce code :

   • Force l’exécution en instance unique à l’aide d’un mutex Windows.
   • Récupère les URI auth0flutter://callback passées en arguments de ligne de commande.
   • Transmet les URI des lancements secondaires à l’instance déjà en cours d’exécution au moyen d’un canal nommé.
   • Définit la variable d’environnement PLUGIN_STARTUP_URL pour que le plugin Auth0 puisse la lire.
6. Enregistrez le schéma d’URL personnalisé

   Enregistrez auth0flutter comme schéma d’URL personnalisé pour que Windows achemine les URI de rappel vers votre application.

   Créez un fichier windows/url_scheme.reg :

   Remplacez C:\path\to\your\app.exe par le chemin réel de l’exécutable généré. En développement, il s’agit généralement de :

   build\windows\x64\runner\Debug\my_app.exe
   

   Double-cliquez sur le fichier .reg pour l’importer dans le Registre de Windows.

   Pour une version de production, enregistrez le schéma d’URL personnalisé par programmation dans le programme d’installation de votre application (MSIX, Inno Setup, etc.) au lieu de vous fier à un fichier .reg.

   Vérifiez que le schéma fonctionne :

   Ouvrez l’invite de commandes et exécutez :

   start auth0flutter://test
   

   Votre application devrait s’ouvrir (ou revenir au premier plan si elle est déjà en cours d’exécution).

7. Implémenter la connexion et la déconnexion

   Créez lib/auth_service.dart pour gérer l’authentification Windows :

   Le SDK Flutter Windows d’Auth0 ne prend actuellement pas en charge la gestion des informations d’authentification. Vous devez enregistrer manuellement les informations d’authentification si vous voulez conserver les sessions après le redémarrage de l’application.

8. Afficher les renseignements du profil de l’utilisateur

   Créez l’interface principale de l’application dans lib/main.dart :

9. Lancez votre application

   Compilez et exécutez l’application :

   flutter run -d windows
   

   Flux attendu :

   1. L’application se lance avec un bouton Se connecter.
   2. Sélectionnez Se connecter. Le navigateur système ouvre la page Auth0 Universal Login.
   3. Terminez l’authentification dans le navigateur.
   4. Le navigateur redirige vers auth0flutter://callback → votre application revient à l’avant-plan.
   5. Le nom, l’adresse courriel et la photo de profil de l’utilisateur s’affichent.

   Assurez-vous que le schéma d’URL personnalisé est enregistré (étape 6) avant de faire le test. Sans cela, l’URL de rappel du navigateur ne peut pas ouvrir votre application.

Checkpoint

Vous devriez maintenant avoir une expérience de connexion Auth0 entièrement fonctionnelle dans votre application Flutter pour Windows. L’application ouvre le navigateur du système pour Auth0 Universal Login, reçoit le callback au moyen du schéma d’URL personnalisé et affiche le profil de l’utilisateur authentifié.

---

​

Dépannage et utilisation avancée

Problèmes courants et solutions

​

Le navigateur s’ouvre, mais l’application ne reçoit pas le callback

Symptôme : la connexion Auth0 réussit dans le navigateur, mais l’application ne reçoit jamais les informations d’authentification.

Correctif :

1. Ouvrez l’Éditeur du Registre → HKEY_CURRENT_USER\Software\Classes\auth0flutter\shell\open\command et confirmez le chemin vers votre fichier .exe.
2. Testez avec start auth0flutter://test dans l’invite de commande — votre application devrait se lancer.
3. Assurez-vous que windows/runner/main.cpp inclut le code du serveur de pipe et du mutex.
4. Vérifiez qu’aucune instance résiduelle n’est en cours d’exécution dans le Gestionnaire des tâches.
5. Recompilez complètement : flutter clean && flutter run -d windows.

​

L’authentication expire après 5 minutes

Symptôme : la connexion semble figée et finit par échouer.

Correctif : L’application n’a jamais reçu l’URI de callback. Vérifiez :

1. Que l’entrée du registre pointe vers le bon chemin de l’exécutable.
2. Que le nom du mutex auth0flutter_single_instance_mutex est identique dans main.cpp.
3. Qu’aucun pare-feu ou antivirus ne bloque le pipe nommé.
4. Fermez toutes les instances résiduelles et recompilez.

​

Une deuxième instance de l’application se lance au lieu de transmettre l’URI

Symptôme : une nouvelle fenêtre s’ouvre au lieu que l’application déjà ouverte reçoive le callback.

Correctif :

1. Fermez toutes les instances en cours d’exécution dans le Gestionnaire des tâches.
2. Assurez-vous que le nom du mutex est identique dans main.cpp.
3. Recompilez avec la commande suivante : flutter clean && flutter run -d windows.

​

WindowsWebAuthentication est introuvable

Symptôme : erreur de compilation mentionnant windowsWebAuthentication.

Correctif : Assurez-vous que votre pubspec.yaml précise la version bêta :

dependencies:
  auth0_flutter: 2.1.0-beta.1

Exécutez flutter pub get pour mettre à jour.

​

Erreur de non-correspondance de l’URL de callback

Symptôme : Error “redirect_uri_mismatch” provenant d’Auth0.

Correctif :

1. Vérifiez que Allowed Callback URLs dans Auth0 Dashboard → Application Settings correspond exactement à auth0flutter://callback.
2. Assurez-vous que le paramètre appCustomURL dans votre code correspond à : 'auth0flutter://callback'.
3. Vérifiez qu’il n’y a ni barre oblique finale ni espace.

Utiliser un serveur intermédiaire

Quand Auth0 redirige directement vers un schéma personnalisé, le navigateur peut afficher une invite ou laisser un onglet vide. Pour une expérience plus fluide, utilisez un serveur HTTPS intermédiaire :

1. Configurez un endpoint sur le serveur (p. ex. https://your-app.example.com/callback) qui redirige vers auth0flutter://callback?code=...&state=....
2. Dans Auth0 Dashboard → Application Settings, définissez Allowed Callback URLs sur https://your-app.example.com/callback.
3. Passez les deux URL à la méthode de connexion :

final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  redirectUrl: 'https://your-app.example.com/callback',
);

La page du serveur peut afficher “Redirection…” et se fermer d’elle-même pour une expérience plus propre.

Scopes personnalisés et audience

Demandez des scopes supplémentaires ou une audience d’API :

final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  scopes: {'openid', 'profile', 'email', 'read:messages'},
  audience: 'https://your-api.example.com',
);

Configurez l’API dans Auth0 Dashboard → Applications > APIs avant d’utiliser le paramètre audience.

---

​

Prochaines étapes

• Auth0 Flutter SDK sur GitHub — code source et suivi des problèmes.
• Auth0 Flutter SDK sur pub.dev — référence de l’API.
• Quickstart Flutter (Android, iOS, macOS, Web) — guides pour d’autres plateformes.
• Bonnes pratiques de stockage des jetons — gestion sécurisée des identifiants.
• Auth0 Universal Login — personnaliser l’expérience de connexion.