Connecter votre application à l'émulateur Authentication

Avant d'utiliser l'émulateur Authentication avec votre application, assurez-vous de comprendre le workflow global Firebase Local Emulator Suite, d'installer et de configurer Local Emulator Suite, et de consulter ses commandes CLI.

Cet article suppose que vous connaissez déjà le développement de solutions Firebase Authentication pour la production. Si nécessaire, consultez la documentation de votre combinaison de plate-forme et de technique d'authentification.

Que puis-je faire avec l'émulateur Authentication ?

L'émulateur Authentication fournit une émulation locale haute fidélité des services Firebase Authentication, offrant une grande partie des fonctionnalités disponibles dans Firebase Authentication de production. Associé aux plates-formes Apple, aux SDK Android et Firebase Web, l'émulateur vous permet de:

  • Créez, mettez à jour et gérez des comptes utilisateur émulés pour tester l'authentification par e-mail/mot de passe, numéro de téléphone/SMS, SMS multifacteur et fournisseur d'identité tiers (par exemple, Google).
  • Afficher et modifier les utilisateurs émulés
  • Créer des prototypes de systèmes d'authentification par jeton personnalisés
  • Vérifiez les messages liés à l'authentification dans l'onglet "Journaux de l'UI de l'émulateur".

Choisir un projet Firebase

Firebase Local Emulator Suite émule des produits pour un seul projet Firebase.

Pour sélectionner le projet à utiliser, avant de démarrer les émulateurs, exécutez firebase use dans votre répertoire de travail dans la CLI. Vous pouvez également transmettre l'option --project à chaque commande de l'émulateur.

Local Emulator Suite est compatible avec l'émulation de projets Firebase réels et de projets de démonstration.

Type de projet Fonctionnalités Utiliser avec des émulateurs
Situation réelle

Un projet Firebase réel est celui que vous avez créé et configuré (le plus souvent via la console Firebase).

Les projets réels disposent de ressources en ligne, comme des instances de base de données, des buckets de stockage, des fonctions ou toute autre ressource que vous configurez pour ce projet Firebase.

Lorsque vous travaillez avec de véritables projets Firebase, vous pouvez exécuter des émulateurs pour tous les produits compatibles ou certains d'entre eux.

Pour tous les produits que vous n'émulez pas, vos applications et votre code interagissent avec la ressource en direct (instance de base de données, bucket de stockage, fonction, etc.).

Démo

Un projet Firebase de démonstration ne comporte aucune configuration réelle de Firebase et aucune ressource en ligne. Pour accéder à ces projets, vous devez généralement suivre des ateliers de programmation ou d'autres tutoriels.

Les ID de projet des projets de démonstration portent le préfixe demo-.

Lorsque vous travaillez avec des projets Firebase de démonstration, vos applications et votre code n'interagissent qu'avec des émulateurs. Si votre application tente d'interagir avec une ressource pour laquelle aucun émulateur n'est en cours d'exécution, ce code échouera.

Dans la mesure du possible, nous vous recommandons d'utiliser des projets de démonstration. Voici quelques-uns de ses avantages :

  • Configuration plus simple, car vous pouvez exécuter les émulateurs sans avoir à créer un projet Firebase
  • Sécurité renforcée, car si votre code appelle accidentellement des ressources non émulées (de production), il n'y a aucune chance de modification, d'utilisation et de facturation des données.
  • Meilleure prise en charge hors connexion, car vous n'avez pas besoin d'accéder à Internet pour télécharger la configuration de votre SDK.

Instrumenter votre application pour qu'elle communique avec l'émulateur

SDK Android, iOS et Web

Configurez votre configuration dans l'application ou vos classes de test pour interagir avec l'émulateur Authentication comme suit.

Kotlin+KTX
Firebase.auth.useEmulator("10.0.2.2", 9099)
Java
FirebaseAuth.getInstance().useEmulator("10.0.2.2", 9099);
Swift
Auth.auth().useEmulator(withHost:"127.0.0.1", port:9099)

Web

import { getAuth, connectAuthEmulator } from "firebase/auth";

const auth = getAuth();
connectAuthEmulator(auth, "http://127.0.0.1:9099");

Web

const auth = firebase.auth();
auth.useEmulator("http://127.0.0.1:9099");

Aucune configuration supplémentaire n'est requise pour prototyper et tester les interactions entre Authentication et Cloud Functions ou Firebase Security Rules pour Cloud Firestore ou Realtime Database. Lorsque l'émulateur Authentication est configuré et que d'autres émulateurs sont en cours d'exécution, ils fonctionnent automatiquement ensemble.

Admin SDK s

Les Firebase Admin SDK se connectent automatiquement à l'émulateur Authentication lorsque la variable d'environnement FIREBASE_AUTH_EMULATOR_HOST est définie.

export FIREBASE_AUTH_EMULATOR_HOST="127.0.0.1:9099"

Notez que l'émulateur Cloud Functions est automatiquement conscient de l'émulateur Authentication. Vous pouvez donc ignorer cette étape lorsque vous testez les intégrations entre les émulateurs Cloud Functions et Authentication. La variable d'environnement sera automatiquement définie pour le Admin SDK dans Cloud Functions.

Une fois la variable d'environnement définie, les Firebase Admin SDK accepteront les jetons d'ID non signés et les cookies de session émis par l'émulateur Authentication (via les méthodes verifyIdToken et createSessionCookie, respectivement) pour faciliter le développement et les tests locaux. Veillez à ne pas définir la variable d'environnement en production.

Si vous souhaitez que votre code Admin SDK se connecte à un émulateur partagé exécuté dans un autre environnement, vous devez spécifier le même ID de projet que celui que vous avez défini à l'aide de la CLI Firebase. Vous pouvez transmettre directement un ID de projet à initializeApp ou définir la variable d'environnement GCLOUD_PROJECT.

SDK Admin Node.js
admin.initializeApp({ projectId: "your-project-id" });
Variable d'environnement
export GCLOUD_PROJECT="your-project-id"

Jetons d'ID

Pour des raisons de sécurité, l'émulateur Authentication émet des jetons d'ID non signés, qui ne sont acceptés que par d'autres émulateurs Firebase ou par le SDK Firebase Admin lorsqu'il est configuré. Ces jetons seront rejetés par les services Firebase de production ou le SDK Firebase Admin exécuté en mode production (par exemple, le comportement par défaut sans les étapes de configuration décrites ci-dessus).

Démarrer l'émulateur

Vous pouvez utiliser l'émulateur Authentication de manière interactive via Emulator Suite UI et de manière non interactive via son interface REST locale. Les sections suivantes couvrent les cas d'utilisation interactifs et non interactifs.

Pour démarrer l'émulateur Authentication, son interface REST et le Emulator Suite UI, exécutez:

firebase emulators:start

Pour l'authentification anonyme, votre application peut exécuter la logique de connexion pour votre plate-forme (iOS, Android, Web).

Pour l'authentification par e-mail/mot de passe, vous pouvez commencer le prototypage en ajoutant des comptes utilisateur à l'émulateur Authentication à partir de votre application à l'aide des méthodes du SDK Authentication ou en utilisant Emulator Suite UI.

  1. Dans Emulator Suite UI, cliquez sur l'onglet Authentification.
  2. Cliquez sur le bouton Ajouter un utilisateur.
  3. Suivez l'assistant de création de compte utilisateur en remplissant les champs d'authentification par e-mail.

Une fois un utilisateur de test créé, votre application peut le connecter et le déconnecter à l'aide de la logique du SDK pour votre plate-forme (iOS, Android, Web).

Pour tester la validation/la connexion par e-mail avec des flux de lien d'e-mail, l'émulateur imprime une URL sur le terminal sur lequel firebase emulators:start a été exécuté.

i  To verify the email address customer@ex.com, follow this link:
http://127.0.0.1:9099/emulator/action?mode=verifyEmail&lang=en&oobCode=XYZ123&apiKey=fake-api-key

Collez le lien dans votre navigateur pour simuler l'événement de validation et vérifier si la validation a réussi.

{
  "authEmulator": {
    "success": "The email has been successfully verified.",
    "email": "customer@example.com"
  }
}

Pour tester la réinitialisation du mot de passe, l'émulateur imprime une URL similaire, y compris un paramètre newPassword (que vous pouvez modifier si nécessaire), dans le terminal.

http://127.0.0.1:9099/emulator/action?mode=resetPassword&oobCode=XYZ!23&apiKey=fake-api-key&newPassword=YOUR_NEW_PASSWORD

Tests non interactifs

Au lieu d'utiliser le code Emulator Suite UI ou client pour gérer les comptes utilisateur par e-mail/mot de passe, vous pouvez écrire des scripts de configuration de test qui appellent des API REST pour créer et supprimer des comptes utilisateur, et extraire des codes de validation par e-mail hors bande pour renseigner l'URL de validation de l'e-mail de l'émulateur. Cela permet de séparer le code de la plate-forme et le code de test, et de tester de manière non interactive.

Pour les flux de test d'adresse e-mail et de mot de passe non interactifs, la séquence type est la suivante.

  1. Créez des utilisateurs avec le point de terminaison REST signUp de Authentication.
  2. Connectez les utilisateurs à l'aide des adresses e-mail et des mots de passe pour effectuer des tests.
  3. Le cas échéant, récupérez les codes de validation par e-mail hors bande disponibles à partir du point de terminaison REST spécifique à l'émulateur.
  4. Effacez les enregistrements utilisateur à l'aide du point de terminaison REST spécifique à l'émulateur pour effacer les données.

Authentification par téléphone/SMS émulée

Pour l'authentification par téléphone, l'émulateur Auth n'est pas compatible avec les éléments suivants:

  • Flux reCAPTCHA et APN Une fois configurés pour interagir avec l'émulateur, les SDK client désactivent ces méthodes de validation de manière similaire à celle décrite pour les tests d'intégration (iOS, Android, Web).
  • Tester les numéros de téléphone avec des codes préconfigurés dans la console Firebase

Sinon, en termes de code client, le flux d'authentification par téléphone/SMS est identique à celui décrit pour la production (iOS, Android, Web).

En utilisant Emulator Suite UI:

  1. Dans Emulator Suite UI, cliquez sur l'onglet Authentication (Authentification).
  2. Cliquez sur le bouton Ajouter un utilisateur.
  3. Suivez l'assistant de création de compte utilisateur, en remplissant les champs d'authentification par téléphone.

Toutefois, pour les flux d'authentification par téléphone, l'émulateur NE déclenchera PAS l'envoi de SMS, car contacter un opérateur n'entre pas dans le champ d'application et n'est pas adapté aux tests locaux. À la place, l'émulateur imprime le code qui aurait été envoyé par SMS au même terminal que celui sur lequel vous avez exécuté firebase emulators:start. Saisissez ce code dans l'application pour simuler la consultation des messages par les utilisateurs.

Tests non interactifs

Pour les tests d'authentification par téléphone non interactifs, utilisez l'API REST de l'émulateur Authentication pour récupérer les codes SMS disponibles. Notez que le code est différent à chaque fois que vous lancez le flux.

La séquence type est la suivante :

  1. Appelez la plate-forme signInWithPhoneNumber pour lancer le processus de validation.
  2. Récupérez le code de validation à l'aide du point de terminaison REST spécifique à l'émulateur.
  3. Appelez confirmationResult.confirm(code) comme d'habitude avec le code de validation.

Authentification multifacteur via SMS

L'émulateur Authentication permet de prototyper et de tester les flux d'authentification multifacteur (MFA) par SMS disponibles en production pour iOS, Android et Web.

Lorsque vous ajoutez un utilisateur fictif à l'émulateur, vous pouvez activer l'authentification multifacteur et configurer un ou plusieurs numéros de téléphone auxquels des SMS de deuxième facteur seront envoyés. Les messages sont affichés dans le même terminal que celui dans lequel vous avez exécuté firebase emulators:start et sont disponibles depuis l'interface REST.

Authentification du fournisseur d'identité tiers (IDP) émulée

L'émulateur Authentication vous permet de tester de nombreux flux d'authentification tiers dans vos applications iOS, Android ou Web sans apporter de modifications au code de production. Pour obtenir des exemples de flux d'authentification, consultez la documentation sur les différentes combinaisons de fournisseurs et de plates-formes que vous pouvez utiliser dans votre application.

De manière générale, vous pouvez utiliser le SDK Firebase pour vous authentifier de deux manières:

  • Votre application permet au SDK de gérer l'ensemble du processus de bout en bout, y compris toutes les interactions avec les fournisseurs d'IDP tiers pour récupérer les identifiants.
  • Votre application récupère manuellement les identifiants d'un fournisseur tiers à l'aide du SDK de ce tiers et les transmet au SDK Authentication.

Encore une fois, consultez le lien de documentation ci-dessus et assurez-vous de connaître le flux que vous souhaitez utiliser (gestion par le SDK Firebase ou récupération manuelle des identifiants). L'émulateur Authentication permet de tester les deux approches.

Tester les flux d'IDP gérés par le SDK Firebase

Si votre application utilise un flux de bout en bout du SDK Firebase, comme OAuthProvider pour la connexion avec Microsoft, GitHub ou Yahoo, pour les tests interactifs, l'émulateur Authentication fournit une version locale de la page de connexion correspondante pour vous aider à tester l'authentification à partir d'applications Web qui appellent la méthode signinWithPopup ou signInWithRedirect. Cette page de connexion diffusée localement apparaît également dans les applications mobiles, affichée par la bibliothèque Webview de votre plate-forme.

L'émulateur crée des comptes utilisateur et des identifiants tiers fictifs selon les besoins au fur et à mesure des flux.

Tester les flux de l'IDP avec la récupération manuelle des identifiants

Si vous utilisez des techniques de connexion "manuelles" et appelez la méthode signInWithCredentials de votre plate-forme, votre application demandera une véritable connexion tierce et récupérera des identifiants tiers réels, comme d'habitude.

Notez que l'émulateur n'est compatible qu'avec l'authentification signInWithCredential pour les identifiants récupérés à partir de Google Sign-In, d'Apple et d'autres fournisseurs qui utilisent des jetons d'ID implémentés en tant que jetons Web JSON (JWT). Les jetons d'accès (par exemple, ceux fournis par Facebook ou Twitter, qui ne sont pas des jetons JWT) ne sont pas acceptés. La section suivante présente une alternative dans ces cas.

Tests non interactifs

Une approche des tests non interactifs consiste à automatiser les clics des utilisateurs sur la page de connexion diffusée par l'émulateur. Pour les applications Web, utilisez une interface de contrôle telle que WebDriver. Pour les appareils mobiles, utilisez les outils de test d'interface utilisateur de votre plate-forme, comme Espresso ou Xcode.

Vous pouvez également mettre à jour votre code pour qu'il utilise signInWithCredential (par exemple, dans une branche de code) et utiliser un flux d'authentification par jeton avec des jetons d'ID fictifs pour les comptes au lieu d'identifiants réels.

  1. Rebranchez ou commentez la partie de votre code qui récupère les idTokens auprès de l'IDP. Vous n'aurez plus besoin de saisir de véritables noms d'utilisateur et de mots de passe lors de vos tests, et vos tests ne seront plus soumis aux quotas d'API et aux limites de débit de l'IDP.
  2. Deuxièmement, utilisez une chaîne JSON littérale à la place du jeton pour signInWithCredential. En utilisant le SDK Web comme exemple, vous pouvez remplacer le code par:
firebase.auth().signInWithCredential(firebase.auth.GoogleAuthProvider.credential(
  '{"sub": "abc123", "email": "foo@example.com", "email_verified": true}'
));

Lorsqu'il est utilisé avec l'émulateur, ce code authentifie un utilisateur avec l'adresse e-mail foo@example.com sur Google. Considérez le sous-champ comme une clé primaire, qui peut être remplacée par n'importe quelle chaîne, simulant la connexion de différents utilisateurs. Vous pouvez remplacer firebase.auth.GoogleAuthProvider par, par exemple, new firebase.auth.OAuthProvider('yahoo.com') ou tout autre ID de fournisseur que vous souhaitez simuler.

Authentification par jeton personnalisé émulée

L'émulateur Authentication gère l'authentification avec des jetons Web JSON personnalisés à l'aide d'appels à la méthode signInWithCustomToken sur les plates-formes compatibles, comme décrit dans la documentation de production Authentication.

Différences entre l'émulateur Authentication et la production

L'émulateur Authentication Firebase simule de nombreuses fonctionnalités du produit de production. Toutefois, comme tout type de système d'authentification repose fortement sur la sécurité à plusieurs niveaux (appareil, fournisseurs tiers, Firebase, etc.), il est difficile pour l'émulateur de recréer correctement tous les flux.

Cloud IAM

La suite d'émulateurs Firebase ne tente pas de reproduire ni de respecter le comportement lié à l'IAM pour l'exécution. Les émulateurs respectent les règles de sécurité Firebase fournies, mais dans les cas où IAM est normalement utilisé, par exemple pour définir le compte de service d'invocation de Cloud Functions et donc les autorisations, l'émulateur n'est pas configurable et utilisera le compte disponible dans le monde entier sur votre ordinateur de développement, comme si vous exécutiez directement un script local.

Étant donné que, sur les plates-formes mobiles, la connexion via un lien par e-mail repose sur Firebase Dynamic Links, tous ces liens seront ouverts sur la plate-forme Web (mobile) à la place.

Connexion tierce

Pour les flux de connexion tiers, Firebase Authentication s'appuie sur des identifiants sécurisés provenant de fournisseurs tiers tels que Twitter et GitHub.

Les identifiants réels des fournisseurs OpenID Connect tels que Google et Apple sont acceptés par l'émulateur Authentication. Les identifiants provenant de fournisseurs autres qu'OpenID Connect ne sont pas acceptés.

Connexion par e-mail / SMS

Dans les applications de production, les flux de connexion par e-mail et par SMS impliquent une opération asynchrone au cours de laquelle l'utilisateur vérifie un message reçu et saisit un code de connexion dans une interface de connexion. L'émulateur Authentication n'envoie aucun e-mail ni SMS, mais comme décrit ci-dessus, il génère des codes de connexion et les transmet au terminal pour les utiliser lors des tests.

L'émulateur ne permet pas de définir des numéros de téléphone de test avec des codes de connexion fixes, comme vous pouvez le faire à l'aide de la console Firebase.

Authentification par jeton personnalisée

L'émulateur Authentication ne valide pas la signature ni l'expiration des jetons personnalisés. Vous pouvez ainsi utiliser des jetons créés manuellement et les réutiliser indéfiniment dans les scénarios de prototypage et de test.

Limitation du débit / Lutte contre les utilisations abusives

L'émulateur Authentication ne reproduit pas les fonctionnalités de limitation de débit ou de lutte contre les utilisations abusives en production.

Fonctions de blocage

En production, les utilisateurs sont écrits dans le stockage une fois après le déclenchement des événements beforeCreate et beforeSignIn. Toutefois, en raison de contraintes techniques, l'émulateur Authentication écrit dans le stockage deux fois, une fois après la création de l'utilisateur et une autre fois après la connexion. Cela signifie que pour les nouveaux utilisateurs, vous pouvez appeler getAuth().getUser() dans beforeSignIn dans l'émulateur Authentication, mais vous rencontrerez une erreur en production.

Et maintenant ?