Ajouter Login à votre application Windows Flutter

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

Prérequis :

• SDK Flutter 3.24.0+ et Dart 3.5.0+.
• Windows 10 ou une 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 la disponibilité générale.

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

​

Premiers pas

1. Créer un projet Flutter pour Windows

   Créez un nouveau projet Flutter avec prise en charge de Windows.

   flutter create --platforms=windows my_app
   cd my_app
   

   Vérifiez 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. Installer 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 fichier pubspec.yaml doit contenir :

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

3. Configurer Auth0

   Créez ou configurez une application Auth0 avec les URL de callback 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 :

   • Domaine: {yourDomain}
   • ID client: {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, puis cliquez sur Save Changes.
   8. Copiez les valeurs Domaine et ID client en haut des paramètres de l’application.

   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 aux ressources de Flutter dans pubspec.yaml :

   N’ajoutez jamais votre fichier .env au contrôle de version. Ajoutez-le à .gitignore.

5. Configurer le runner Windows

   Le flux d’authentification sous Windows nécessite la configuration du callback dans le 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 restriction à une seule instance et la redirection des URI.

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

   Ce code :

   • Force l’exécution en instance unique au moyen d’un mutex Windows.
   • Capture les URI auth0flutter://callback transmises comme arguments de ligne de commande.
   • Redirige les URI des lancements secondaires vers l’instance déjà en cours d’exécution au moyen d’un canal nommé.
   • Définit la variable d’environnement PLUGIN_STARTUP_URL que le plugin Auth0 lira.
6. Enregistrez le schéma d’URL personnalisé

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

   Créez un fichier windows/url_scheme.reg :

   Remplacez C:\path\to\your\app.exe par le chemin réel de votre fichier exécutable généré. Pendant le 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 un déploiement en production, enregistrez le schéma d’URL personnalisé par programmation dans le programme d’installation de votre application (MSIX, Inno Setup, etc.) plutôt que 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 se lancer (ou s’afficher au premier plan si elle est déjà ouverte).

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 identifiants. Vous devez stocker manuellement les identifiants si vous avez besoin que les sessions persistent d’un redémarrage de l’application à l’autre.

8. Afficher les renseignements du profil utilisateur

   Créez l’interface utilisateur principale de l’application dans le fichier 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 Log In.
   2. Sélectionnez Log In. Votre 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, le 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 tester. Sinon, le callback du navigateur ne pourra pas joindre votre application.

Vérification

Vous devriez maintenant disposer d’une expérience de connexion Auth0 entièrement fonctionnelle dans votre application Flutter Windows. L’application ouvre le navigateur 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 identifiants.

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 commandes — 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 ancienne instance n’est encore en cours d’exécution dans le Gestionnaire des tâches.
5. Recompilez complètement : flutter clean && flutter run -d windows.

​

L’authentification expire après 5 minutes

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

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

1. L’entrée du registre pointe vers le bon chemin de l’exécutable.
2. Le nom du mutex auth0flutter_single_instance_mutex est cohérent dans main.cpp.
3. Aucun pare-feu ni antivirus ne bloque le pipe nommé.
4. Fermez toutes les anciennes instances et recompilez.

​

Une deuxième instance de l’application se lance au lieu de transférer l’URI

Symptôme : une nouvelle fenêtre s’ouvre au lieu que l’application existante 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 cohérent dans main.cpp.
3. Recompilez avec la commande suivante : flutter clean && flutter run -d windows.

​

WindowsWebAuthentication introuvable

Symptôme : erreur de compilation faisant référence à 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 Callback URL

Symptôme : erreur “redirect_uri_mismatch” renvoyée par Auth0.

Correctif :

1. Vérifiez que Allowed Callback URLs dans Auth0 Dashboard → paramètres de l’application est 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 pas de barre oblique finale ni d’espace superflu.

Utilisation d’un serveur intermédiaire

Lorsque 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 point de terminaison sur le serveur (par exemple, https://your-app.example.com/callback) qui redirige vers auth0flutter://callback?code=...&state=....
2. Dans Auth0 Dashboard → paramètres de l’application, définissez Allowed Callback URLs à 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 “Redirecting…” et se fermer d’elle-même pour une expérience plus propre.

Scopes et Audience personnalisés

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

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