Ajouter la connexion à votre application Flutter

Ce guide montre comment intégrer Auth0 à toute application Flutter à l’aide du SDK Auth0 Flutter.

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant de codage IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide d’Agent Skills.

Installer :

npx skills add auth0/agent-skills --skill auth0

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my Flutter app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les informations d’identification, ajoutera la dépendance du SDK auth0_flutter, configurera les URL de rappel Android et iOS, et implémentera la connexion/déconnexion Web Auth avec un stockage sécurisé des informations d’identification. Documentation complète sur Agent Skills →

Ce guide montre comment intégrer Auth0 à une application Flutter à l’aide du Auth0 Flutter SDK. Il couvre la configuration des plateformes Android, iOS et macOS.

Le Auth0 Flutter SDK prend également en charge Web et Windows (bêta). Des Quickstarts sont offerts pour ces plateformes :

• Quickstart Flutter Web — pour les applications Flutter destinées au navigateur
• Quickstart Flutter Windows — pour les applications de bureau Flutter sur Windows (bêta)

​

Commencer

1. Créer un nouveau projet Flutter

   Créez un nouveau projet Flutter pour ce Quickstart.

   Dans votre terminal :

   1. Accédez à votre répertoire de travail
   2. Exécutez : flutter create auth0_flutter_sample
   3. Accédez au répertoire du projet : cd auth0_flutter_sample
   4. Ouvrez-le dans votre IDE :
      • VS Code: code .
      • Android Studio: open -a "Android Studio" .

   # Créer un nouveau projet Flutter
   flutter create auth0_flutter_sample
   
   # Accéder au répertoire du projet
   cd auth0_flutter_sample
   
   # Ouvrir dans VS Code
   code .
   

   Cela crée une application Flutter moderne avec la structure de projet la plus récente. Exécutez flutter doctor pour vous assurer que votre environnement est correctement configuré.

2. Installer le SDK Auth0 Flutter

   Ajoutez le SDK Auth0 Flutter à votre projet à l’aide de la CLI Flutter.

   flutter pub add auth0_flutter
   

   Cela ajoutera auth0_flutter aux dépendances de votre pubspec.yaml :

   pubspec.yaml

   dependencies:
     auth0_flutter: ^2.0.0-beta.1
   

   Le SDK Auth0 Flutter nécessite Flutter 3.24.0+ et Dart 3.5.0+. Exécutez flutter doctor pour vérifier que votre environnement répond à ces exigences.

3. Configurez votre Auth0 App

   L’étape suivante consiste à créer une nouvelle application dans votre tenant Auth0 et à configurer les URL de rappel.

   1. Accédez au Auth0 Dashboard
   2. Cliquez sur Applications > Applications > Create Application
   3. Dans la fenêtre contextuelle, saisissez un nom pour votre application, sélectionnez Native comme type d’application, puis cliquez sur Create
   4. Ouvrez l’onglet Settings sur la page des détails de l’application
   5. Prenez en note les valeurs Domain et Client ID; vous en aurez besoin plus tard

   Dans l’onglet Settings, configurez les URL suivantes selon la ou les plateformes cibles :

   Allowed Callback URLs:

   Android

   https://{yourDomain}/android/{yourPackageName}/callback
   

   iOS

   https://{yourDomain}/ios/{yourBundleIdentifier}/callback,
   {yourBundleIdentifier}://{yourDomain}/ios/{yourBundleIdentifier}/callback
   

   macOS

   https://{yourDomain}/macos/{yourBundleIdentifier}/callback,
   {yourBundleIdentifier}://{yourDomain}/macos/{yourBundleIdentifier}/callback
   

   Allowed Logout URLs:

   Ajoutez au champ Allowed Logout URLs les mêmes URL que celles indiquées ci-dessus pour la configuration des URL de rappel.

   Les Allowed Callback URLs constituent une mesure de sécurité essentielle pour garantir que les utilisateurs sont redirigés de façon sécuritaire vers votre application après l’authentication. Sans URL correspondante, le processus de connexion échouera.

   Les Allowed Logout URLs sont essentielles pour offrir une expérience utilisateur fluide au moment de la déconnexion. Sans URL correspondante, les utilisateurs ne seront pas redirigés vers votre application après la déconnexion.

   Par exemple, si votre Auth0 domain est example.us.auth0.com et que votre nom de package Android est com.example.myapp, votre URL de rappel Android serait : https://example.us.auth0.com/android/com.example.myapp/callback

   Important : Assurez-vous que le nom du package (Android) ou l’identifiant du bundle (iOS/macOS) dans vos URL de rappel correspond bien à l’identifiant réel de votre application. Si l’authentication échoue, vérifiez que ces valeurs sont identiques.

4. Configurer votre application

   Une configuration propre à la plateforme est requise pour activer le flux d’authentification. Suivez les instructions pour chaque plateforme ciblée.

   Android

   Ouvrez le fichier android/app/build.gradle et ajoutez les espaces réservés du Manifest suivants dans android > defaultConfig :

   android/app/build.gradle

   android {
       // ...
       defaultConfig {
           // Ajoutez la ligne suivante
           manifestPlaceholders += [auth0Domain: "{yourDomain}", auth0Scheme: "https"]
       }
       // ...
   }
   

   Remplacez {yourDomain} par votre domaine Auth0 (p. ex. example.us.auth0.com).

   schéma https

   Pour utiliser le schéma https pour votre URL de rappel, configurez les Android App Links pour votre application.

   Pour l’authentification biométrique (facultatif) :

   Si vous prévoyez utiliser l’authentification biométrique, mettez à jour votre MainActivity.kt pour qu’elle étende FlutterFragmentActivity :

   android/app/src/main/kotlin/.../MainActivity.kt

   import io.flutter.embedding.android.FlutterFragmentActivity
   
   class MainActivity: FlutterFragmentActivity() {
   }
   

   iOS

   Pour utiliser Universal Links (URL de rappel HTTPS) sur iOS 17.4+, configurez un domaine associé :

   1. Ouvrez votre application dans Xcode : open ios/Runner.xcworkspace
   2. Sélectionnez la cible Runner et accédez à Signing & Capabilities
   3. Cliquez sur + Capability et ajoutez Associated Domains
   4. Ajoutez l’entrée : webcredentials:{yourDomain}
   5. Dans le Auth0 Dashboard, accédez à Settings > Advanced Settings > Device Settings
   6. Dans la section iOS, définissez votre Team ID et votre App ID (identificateur du bundle)

   La configuration des Universal Links est facultative. Omettez cette étape si vous n’avez pas besoin de la prise en charge des Universal Links — le SDK reviendra automatiquement aux schémas d’URL personnalisés.

   macOS

   Suivez les mêmes étapes que pour iOS, mais ouvrez macos/Runner.xcworkspace à la place.

   Android : Assurez-vous que la valeur auth0Domain correspond exactement à votre domaine Auth0. Si l’authentification échoue, vérifiez que cette valeur est identique au domaine affiché dans votre Auth0 Dashboard.

   iOS/macOS : Les Universal Links nécessitent un compte Apple Developer payant et iOS 17.4+/macOS 14.4+. Sur les versions antérieures, le SDK reviendra automatiquement aux schémas d’URL personnalisés.

5. Implement Login et Logout

   Universal Login est le moyen le plus simple de configurer l’authentification dans votre application. Nous vous recommandons de l’utiliser pour profiter de la meilleure expérience, d’une sécurité optimale et de l’éventail de fonctionnalités le plus complet.

   Mettre en place la connexion :

   Importez le SDK Auth0 Flutter et créez une instance Auth0 :

   lib/auth_service.dart

   import 'package:auth0_flutter/auth0_flutter.dart';
   
   class AuthService {
     final auth0 = Auth0('{yourDomain}', '{yourClientId}');
   
     Future<Credentials> login() async {
       final credentials = await auth0.webAuthentication().login(useHTTPS: true);
   
       // Jeton d'accès -> credentials.accessToken
       // Jeton d'identité -> credentials.idToken
       // Profil utilisateur -> credentials.user
   
       return credentials;
     }
   }
   

   Implement Déconnexion :

   lib/auth_service.dart

   Future<void> logout() async {
     await auth0.webAuthentication().logout(useHTTPS: true);
   
     // L'utilisateur est maintenant déconnecté
     // Les informations d'identification ont été supprimées du stockage sécurisé
   }
   

   iOS/macOS : Le paramètre useHTTPS: true active les Universal Links sur iOS 17.4+ et macOS 14.4+ pour une sécurité renforcée.

   Android : Si vous utilisez un schéma personnalisé, transmettez-le à la méthode login afin que le SDK puisse rediriger correctement vers la page de connexion, puis revenir ensuite :

   await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();
   
6. Afficher les renseignements du profil utilisateur

   Le profil utilisateur est récupéré automatiquement lorsque l’utilisateur se connecte. L’objet Credentials contient une propriété user avec tous les renseignements du profil utilisateur, renseignée à partir du décodage de l’ID token.

   lib/profile_screen.dart

   void displayUserProfile(Credentials credentials) {
     final user = credentials.user;
     
     print('User ID: ${user.sub}');
     print('Email: ${user.email}');
     print('Name: ${user.name}');
     print('Picture: ${user.pictureUrl}');
     print('Nickname: ${user.nickname}');
   }
   

   Demandez les scopes appropriés lors de la connexion pour accéder à certains champs du profil d’utilisateur. Les scopes par défaut sont openid, profile, email et offline_access.

7. Lancez votre application

   Compilez et exécutez votre application Flutter.

   Dans votre terminal :

   # Lister les appareils disponibles
   flutter devices
   
   # Exécuter sur Android
   flutter run -d android
   
   # Exécuter sur le simulateur iOS
   flutter run -d ios
   
   # Exécuter sur macOS
   flutter run -d macos
   

   Flux attendu :

   1. L’application s’ouvre avec votre interface de connexion
   2. L’utilisateur appuie sur Se connecter → le navigateur/l’onglet personnalisé s’ouvre avec Auth0 Universal Login
   3. L’utilisateur termine l’authentification
   4. Le navigateur redirige l’utilisateur vers votre application
   5. L’utilisateur est maintenant authentifié et ses identifiants sont enregistrés

Point de contrôle

Vous devriez maintenant disposer d’une expérience de connexion Auth0 entièrement fonctionnelle dans votre application Flutter. L’application utilise une authentification sécurisée par navigateur et enregistre automatiquement les informations d’identification pour maintenir la session.

---

​

Résolution des problèmes et utilisation avancée

Problèmes courants et solutions

​

Incompatibilité de l’URL de rappel

Symptôme : Error “redirect_uri_mismatch” ou l’authentification échoue sans message.

Solutions :

1. Vérifiez que les Allowed Callback URLs dans le Auth0 Dashboard correspondent exactement à la configuration de votre application
2. Vérifiez le schéma (https:// vs http://)
3. Assurez-vous que le nom du package (Android) ou l’identifiant du bundle (iOS/macOS) est correct
4. Vérifiez s’il y a une barre oblique finale

​

Android : l’onglet personnalisé Chrome ne s’ouvre pas

Symptôme : Rien ne se passe lors de l’appel à login().

Correctif :

1. Vérifiez que manifestPlaceholders est correctement défini dans build.gradle
2. Assurez-vous que la permission Internet figure dans AndroidManifest.xml :
   <uses-permission android:name="android.permission.INTERNET" />
   
3. Vérifiez que Chrome ou un autre navigateur est installé sur l’appareil

​

iOS : alerte « Open in App »

Symptôme : Une boîte d’alerte apparaît et demande d’ouvrir l’application.

Correctif : Il s’agit du comportement attendu avec ASWebAuthenticationSession. Pour la supprimer :

• Utilisez les liens universels (nécessite iOS 17.4+ et un compte Apple Developer payant)
• Ou définissez useEphemeralSession: true (désactive le SSO) :

await auth0.webAuthentication().login(
  useHTTPS: true,
  useEphemeralSession: true,
);

​

Authentification annulée par l’utilisateur

Gérez ce cas correctement dans votre gestion des erreurs :

try {
  final credentials = await auth0.webAuthentication().login(useHTTPS: true);
  // Gérer une connexion réussie
} on WebAuthenticationException catch (e) {
  if (e.code == 'USER_CANCELLED') {
    showMessage('La connexion a été annulée');
  } else {
    showMessage('Échec de la connexion : ${e.message}');
  }
}

Gestion des informations d’identification

Le Auth0 Flutter SDK comprend un Credentials Manager intégré qui stocke de façon sécurisée les informations d’identification de l’utilisateur. Sur les plateformes mobiles, ces informations d’identification sont chiffrées et stockées dans le stockage sécurisé de la plateforme (Keychain sur iOS/macOS, SharedPreferences chiffré sur Android).

​

Vérifier les informations d’identification stockées

Avant d’inviter l’utilisateur à se connecter, vérifiez si des informations d’identification valides existent déjà :

lib/auth_service.dart

Future<bool> checkAuthentication() async {
  return await auth0.credentialsManager.hasValidCredentials();
}

​

Récupérer les informations d’identification stockées

Récupérez les informations d’identification pour accéder aux jetons d’accès ou aux renseignements de l’utilisateur. Le Credentials Manager actualise automatiquement les jetons expirés lorsque c’est possible :

lib/auth_service.dart

Future<Credentials> getCredentials() async {
  return await auth0.credentialsManager.credentials();
}

Vous n’avez pas besoin de stocker manuellement les informations d’identification après la connexion — le SDK s’en charge automatiquement. Vous n’avez pas non plus besoin d’actualiser manuellement les jetons; le Credentials Manager les actualise au besoin.

Gestion des erreurs

Gérez les erreurs d’authentification correctement afin d’offrir une bonne expérience utilisateur.

lib/auth_service.dart

import 'package:auth0_flutter/auth0_flutter.dart';

Future<void> login() async {
  try {
    final credentials = await auth0.webAuthentication().login(useHTTPS: true);
    // Gérer une connexion réussie
  } on WebAuthenticationException catch (e) {
    if (e.code == 'USER_CANCELLED') {
      // L’utilisateur a annulé la connexion
      print('Connexion annulée par l’utilisateur');
    } else {
      // Gérer les autres erreurs
      print('Erreur de connexion : ${e.message}');
    }
  }
}

Future<Credentials> getCredentials() async {
  try {
    return await auth0.credentialsManager.credentials();
  } on CredentialsManagerException catch (e) {
    if (e.isNoCredentialsFound) {
      // Aucune information d’identification stockée; l’utilisateur doit se connecter
      throw Exception('Veuillez d’abord vous connecter');
    } else if (e.isTokenRenewFailed) {
      // Le refresh token a expiré; une nouvelle authentification est requise
      return await auth0.webAuthentication().login(useHTTPS: true);
    }
    rethrow;
  }
}

Intégration Flutter avancée

​

Sécurité renforcée des identifiants grâce à la biométrie

Implémentez l’authentification biométrique pour accéder aux identifiants sur mobile :

lib/secure_auth_service.dart

class SecureAuthService {
  final auth0 = Auth0('{yourDomain}', '{yourClientId}');
  
  Future<void> enableBiometrics() async {
    // Activer l’authentification locale (Face ID, Touch ID, empreinte digitale)
    await auth0.credentialsManager.enableLocalAuthentication(
      title: 'Authenticate to access your account',
      cancelTitle: 'Cancel',
      fallbackTitle: 'Use passcode',
    );
  }
  
  Future<Credentials> getCredentialsWithBiometrics() async {
    // Cela nécessitera désormais une authentification biométrique
    return await auth0.credentialsManager.credentials();
  }
}

Android : nécessite que MainActivity étende FlutterFragmentActivity, comme configuré à l’étape 4.

iOS/macOS : nécessite d’ajouter NSFaceIDUsageDescription à votre Info.plist.

​

Scopes personnalisés et audience

Demandez des scopes précis et une audience spécifique pour votre API :

lib/auth_service.dart

Future<Credentials> loginWithCustomScopes() async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    scopes: {'openid', 'profile', 'email', 'offline_access', 'read:posts'},
    audience: 'https://myapi.example.com',
    parameters: {'prompt': 'login'},
  );
}

​

Organizations (B2B/Enterprise)

Authentifiez les utilisateurs au sein d’une organisation précise :

lib/auth_service.dart

Future<Credentials> loginWithOrganization(String organizationId) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationId: organizationId,
  );
}

// Ou demander à l’utilisateur de sélectionner une organisation
Future<Credentials> loginWithOrganizationName(String organizationName) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationName: organizationName,
  );
}

Déploiement en production

​

Préparation pour l’App Store

• Configurez les liens universels (iOS) et les App Links (Android) pour une authentification sans friction
• Testez sur plusieurs tailles d’appareil et versions du système d’exploitation
• Implémentez une gestion adéquate des erreurs en cas de panne réseau
• Ajoutez des règles ProGuard pour Android si vous utilisez l’obscurcissement du code
• Respectez les politiques propres à chaque plateforme pour l’App Store et le Play Store

​

Considérations de sécurité

• Utilisez le Credentials Manager intégré pour stocker les identifiants en production
• Activez l’authentification biométrique pour les opérations sensibles
• Envisagez l’épinglage de certificat pour renforcer la sécurité de l’API
• Implémentez une gestion adéquate de l’actualisation des tokens
• Utilisez useHTTPS: true pour les liens universels sur les plateformes prises en charge

---

​

Prochaines étapes

Consultez le fichier EXAMPLES.md dans le dépôt du SDK pour accéder à des exemples de code détaillés illustrant des scénarios avancés, comme DPoP, l’authentification biométrique, la connexion sans mot de passe et bien d’autres fonctionnalités.