Ajouter la connexion à votre application Flutter

Ce guide explique comment intégrer Auth0 à n’importe quelle application Flutter à l’aide du SDK Flutter d’Auth0.

Utilisez l’IA pour intégrer Auth0

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

Installer :

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-flutter-native

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 au SDK auth0_flutter, configurera les URL de callback Android et iOS, et implémentera la connexion/déconnexion Web Auth avec un stockage sécurisé des informations d’identification. Documentation complète d’Agent Skills →

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

Le SDK Flutter d’Auth0 prend aussi en charge Web et Windows (bêta). Ces plateformes ont des guides de démarrage rapide dédiés :

• Guide de démarrage rapide Flutter Web — pour les applications Flutter ciblant le navigateur
• Guide de démarrage rapide Flutter Windows — pour les applications de bureau Flutter sur Windows (bêta)

​

Pour commencer

1. Créer un projet Flutter

   Créez un nouveau projet Flutter pour ce guide de démarrage rapide.

   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 .
   

   Cette commande crée une application Flutter moderne avec la structure de projet la plus récente. Exécutez flutter doctor pour vérifier que votre environnement est correctement configuré.

2. Installez le SDK Auth0 pour Flutter

   Ajoutez le SDK Auth0 pour Flutter à votre projet à l’aide de l’interface de ligne de commande 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 Flutter d’Auth0 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 application Auth0

   Ensuite, vous devez créer une nouvelle application dans votre locataire 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, entrez un nom pour votre application, sélectionnez Native comme type d’application, puis cliquez sur Create
   4. Allez à l’onglet Settings dans la page des détails de l’application
   5. Notez les valeurs Domaine et ID client — vous en aurez besoin plus tard

   Dans l’onglet Settings, configurez les URL suivantes en fonction de la ou des 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 configurées ci-dessus pour les URL de rappel.

   Allowed Callback URLs sont 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’authentification. Sans URL correspondante, le processus de connexion échouera.

   Allowed Logout URLs sont essentielles pour offrir une expérience utilisateur fluide lors 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 domaine Auth0 est example.us.auth0.com et que le nom de votre 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’authentification échoue, vérifiez que ces valeurs sont identiques.

4. Configurez votre application

   Une configuration propre à chaque plateforme est nécessaire 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 variables de substitution du manifeste suivantes dans android > defaultConfig :

   android/app/build.gradle

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

   Remplacez {yourDomain} par votre domaine Auth0 (par exemple, example.us.auth0.com).

   schéma https

   Pour utiliser le schéma https pour votre URL de rappel, configurez les liens d’application Android pour votre application.

   Pour l’authentification biométrique (facultatif) :

   Si vous comptez utiliser l’authentification biométrique, modifiez votre fichier MainActivity.kt pour qu’il étende FlutterFragmentActivity :

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

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

   iOS

   Pour utiliser les 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 (identifiant du bundle)

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

   macOS

   Suivez les mêmes étapes que pour iOS, mais ouvrez plutôt macos/Runner.xcworkspace.

   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 basculera automatiquement vers les schémas d’URL personnalisés.

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

   Universal Login est la façon la 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.

   Implémenter 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;
     }
   }
   

   Implémenter la 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é effacé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é accrue.

   Android : Si vous utilisez un schéma personnalisé, passez ce schéma à la méthode de connexion pour que le SDK puisse rediriger correctement vers la page de connexion, puis revenir à l’application :

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

   Le profil de l’utilisateur est récupéré automatiquement lorsque celui-ci se connecte. L’objet Credentials contient une propriété user avec toutes les informations du profil de l’utilisateur, obtenues en décodant le jeton d’identité.

   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 à des champs précis du profil de l’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
   

   Déroulement attendu :

   1. L’application se lance avec votre interface de connexion
   2. L’utilisateur appuie sur Se connecter → le navigateur ou l’onglet personnalisé s’ouvre avec Universal Login d’Auth0
   3. L’utilisateur termine l’authentification
   4. Le navigateur redirige ensuite vers votre application
   5. L’utilisateur est maintenant authentifié et ses informations d’identification sont stockées

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 dans le navigateur et stocke automatiquement les identifiants afin de maintenir la session.

---

​

Dépannage et utilisation avancée

Problèmes courants et solutions

​

L’URL de callback ne correspond pas

Symptôme : erreur “redirect_uri_mismatch” ou échec silencieux de l’authentification.

Solutions :

1. Vérifiez que Allowed Callback URLs dans Auth0 Dashboard correspond 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 lorsque vous appelez login().

Correctif :

1. Vérifiez que manifestPlaceholders est correctement défini dans build.gradle
2. Assurez-vous que l’autorisation 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 alerte s’affiche et demande d’ouvrir dans votre application.

Correctif : Il s’agit du comportement attendu avec ASWebAuthenticationSession. Pour l’éliminer :

• Utilisez les Universal Links (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 traitement des erreurs :

try {
  final credentials = await auth0.webAuthentication().login(useHTTPS: true);
  // Gérer la 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 identifiants

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

​

Vérifier la présence d’identifiants stockés

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

lib/auth_service.dart

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

​

Récupérer les identifiants stockés

Récupérez les identifiants pour obtenir des jetons ou des renseignements sur 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 identifiants 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 la 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) {
      // Aucun identifiant stocké, l’utilisateur doit se connecter
      throw Exception('Veuillez d’abord vous connecter');
    } else if (e.isTokenRenewFailed) {
      // Le jeton d’actualisation a expiré, une nouvelle authentification est requise
      return await auth0.webAuthentication().login(useHTTPS: true);
    }
    rethrow;
  }
}

Intégration Flutter avancée

​

Sécurité accrue 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: 'Authentifiez-vous pour accéder à votre compte',
      cancelTitle: 'Annuler',
      fallbackTitle: 'Utiliser le code d’accès',
    );
  }
  
  Future<Credentials> getCredentialsWithBiometrics() async {
    // Cela exigera maintenant 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 précise 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'},
  );
}

​

Organisations (B2B/entreprise)

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 avant publication

• Configurez les Universal Links (iOS) et les App Links (Android) pour une authentification fluide
• Testez sur plusieurs tailles d’appareils et versions du système d’exploitation
• Gérez correctement les erreurs en cas de défaillance réseau
• Ajoutez des règles ProGuard pour Android si vous utilisez l’obfuscation 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 certificats pour renforcer la sécurité de l’API
• Gérez correctement l’actualisation des jetons
• Utilisez useHTTPS: true pour les Universal Links sur les plateformes prises en charge

---

​

Étapes suivantes

Consultez le fichier EXAMPLES.md dans le dépôt du SDK pour voir des exemples de code détaillés couvrant des scénarios avancés comme DPoP, l’authentification biométrique, la connexion Passwordless et bien d’autres fonctionnalités.