Passer au contenu principal
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, macOS et Web.

​
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 (ou Single Page Application pour le Web uniquement), 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:
https://{yourDomain}/android/{yourPackageName}/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 Web Origins (Web Only):Si vous ciblez le Web, ajoutez l’URL de votre application :
http://localhost:3000
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.
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 httpsPour 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() {
}
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é, transmettez-le à la méthode de connexion afin que le SDK puisse rediriger correctement vers la page de connexion, puis revenir à l’application :
lib/auth_service.dart
await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();
Web : Vous devez appeler onLoad() au démarrage de votre application. Cette méthode gère le callback de redirection d’Auth0 et rétablit la session de l’utilisateur s’il est déjà authentifié.
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 le Web (utiliser le port 3000 pour correspondre aux URL de rappel)
flutter run -d chrome --web-port 3000
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
Assurez-vous d’utiliser le port 3000 lorsque vous exécutez l’application web afin qu’il corresponde aux URL de rappel configurées dans Auth0. Vous pouvez modifier ce port, mais veillez à ce qu’il corresponde à votre configuration dans Auth0.
Point de contrôleVous 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

​
L’URL de rappel 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 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,
);

​
Web : l’utilisateur est déconnecté après l’actualisation de la page

Symptôme : l’utilisateur semble déconnecté après l’actualisation de la page.Correctif :
  1. Assurez-vous que onLoad() est appelé pendant l’initialisation de l’application
  2. Essayez d’utiliser localStorage comme emplacement du cache : 
    final auth0Web = Auth0Web(
  '{yourDomain}',
  '{yourClientId}',
  cacheLocation: CacheLocation.localStorage,
);
  3. Assurez-vous que votre domaine est ajouté à Allowed Web Origins dans Auth0 Dashboard

​
Web : erreur “Must run on a secure origin”

Symptôme : erreur liée à une origine sécurisée dans la console du navigateur.Correctif : Le SDK SPA d’Auth0 exige un contexte sécurisé. Utilisez localhost (qui est considéré comme sécurisé) ou déployez sur un domaine HTTPS.

​
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}');
  }
}
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 {
  if (kIsWeb) {
    return await auth0Web.hasValidCredentials();
  } else {
    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 {
  if (kIsWeb) {
    return await auth0Web.credentials();
  } else {
    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.
Gérez les erreurs d’authentification correctement afin d’offrir une bonne expérience utilisateur.

​
Erreurs sur mobile/macOS

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) {
      // 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;
  }
}

​
Erreurs Web

lib/web_auth_service.dart
import 'package:auth0_flutter/auth0_flutter_web.dart';

Future<void> login() async {
  try {
    await auth0Web.loginWithRedirect(redirectUrl: 'http://localhost:3000');
  } on WebException catch (e) {
    print('Erreur de connexion : ${e.message}');
  }
}

​
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,
  );
}

​
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.