Connectez votre application à l'émulateur d'authentification

Avant d'utiliser l'émulateur d'authentification avec votre application, assurez-vous que vous comprenez le flux de travail global de Firebase Local Emulator Suite et que vous installez et configurez Local Emulator Suite et passez en revue ses commandes CLI .

Cette rubrique suppose que vous êtes déjà familiarisé avec le développement de solutions d'authentification Firebase pour la production. Si nécessaire, consultez la documentation relative à votre combinaison de plate-forme et de technique d'authentification .

Que puis-je faire avec l'émulateur d'authentification ?

L'émulateur d'authentification fournit une émulation locale haute fidélité des services d'authentification Firebase, fournissant une grande partie des fonctionnalités trouvées dans la production Firebase Authentication . Couplé aux plateformes Apple, aux SDK Android et Web Firebase, l'émulateur vous permet de :

  • Créer, mettre à jour et gérer des comptes d'utilisateurs é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
  • Prototypes de systèmes d'authentification par jeton personnalisé
  • Vérifiez les messages liés à l'authentification dans l'onglet Journaux de l'interface utilisateur de l'émulateur.

Choisissez un projet Firebase

La suite d'émulateurs locaux Firebase émule des produits pour un seul projet Firebase.

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

Local Emulator Suite prend en charge l'émulation de projets Firebase réels et de projets de démonstration .

Type de projet Caractéristiques Utiliser avec des émulateurs
Réel

Un vrai projet Firebase est celui que vous avez créé et configuré (très probablement via la console Firebase).

Les projets réels ont des ressources actives, telles que des instances de base de données, des compartiments de stockage, des fonctions ou toute autre ressource que vous avez configurée pour ce projet Firebase.

Lorsque vous travaillez avec de vrais projets Firebase, vous pouvez exécuter des émulateurs pour tout ou partie des produits pris en charge.

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

Démo

Un projet de démonstration Firebase n'a pas de véritable configuration Firebase ni de ressources en direct. Ces projets sont généralement accessibles via des ateliers de programmation ou d'autres didacticiels.

Les ID de projet pour les projets de démonstration ont le préfixe demo- .

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

Nous vous recommandons d'utiliser des projets de démonstration dans la mesure du possible. Les avantages incluent :

  • Configuration plus facile, car vous pouvez exécuter les émulateurs sans jamais créer de projet Firebase
  • Sécurité renforcée, car si votre code invoque 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 ligne, car il n'est pas nécessaire d'accéder à Internet pour télécharger votre configuration SDK.

Instrumentez votre application pour parler à l'émulateur

SDK Android, iOS et Web

Configurez votre configuration intégrée à l'application ou testez les classes pour interagir avec l'émulateur d'authentification comme suit.

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

Web modular API

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

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

Web namespaced API

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

Aucune configuration supplémentaire n'est nécessaire pour prototyper et tester les interactions entre l'authentification et les fonctions cloud ou les règles de sécurité Firebase pour Cloud Firestore ou la base de données en temps réel. Lorsque l'émulateur d'authentification est configuré et que d'autres émulateurs sont en cours d'exécution, ils fonctionnent automatiquement ensemble.

SDK d'administration

Les SDK Firebase Admin se connectent automatiquement à l'émulateur d'authentification 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 d'authentification. Vous pouvez donc ignorer cette étape lorsque vous testez des intégrations entre Cloud Functions et les émulateurs d'authentification. La variable d'environnement sera automatiquement définie pour le SDK Admin dans Cloud Functions.

Avec la variable d'environnement définie, les SDK Firebase Admin accepteront les jetons d'identification non signés et les cookies de session émis par l'émulateur d'authentification (via les méthodes verifyIdToken et createSessionCookie respectivement) pour faciliter le développement et les tests locaux. Assurez-vous de ne pas définir la variable d'environnement en production.

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

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

Jetons d'identification

Pour des raisons de sécurité, l'émulateur d'authentification émet des jetons d'identification non signés , qui ne sont acceptés que par d'autres émulateurs Firebase, ou le SDK Firebase Admin lorsqu'il est configuré . Ces jetons seront rejetés par les services de production Firebase ou le SDK Firebase Admin exécutés 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 d'authentification de manière interactive via l'interface utilisateur d'Emulator Suite 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 d'authentification, son interface REST et l'interface utilisateur d'Emulator Suite, exécutez :

firebase emulators:start

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

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

  1. Dans l'interface utilisateur d'Emulator Suite, 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 de l'e-mail.

Avec un utilisateur test créé, votre application peut connecter et déconnecter l'utilisateur avec la logique du SDK pour votre plate-forme ( iOS , Android , Web ).

Pour tester la vérification/la connexion par e-mail avec des flux de liens par 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://localhost: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 vérification et vérifiez si la vérification a réussi.

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

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

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

Tests non interactifs

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

Pour les flux de test de courrier électronique et de mot de passe non interactifs, la séquence typique est la suivante.

  1. Créez des utilisateurs avec le point de terminaison REST Authentication signUp .
  2. Connectez les utilisateurs à l'aide des e-mails et des mots de passe pour effectuer des tests.
  3. Si cela s'applique à vos tests, récupérez les codes de vérification des e-mails hors bande disponibles à partir du point de terminaison REST spécifique à l'émulateur .
  4. Videz les enregistrements utilisateur avec le point de terminaison REST spécifique à l'émulateur pour effacer les données.

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

Pour l'authentification par téléphone, l'émulateur Auth ne prend pas en charge :

  • Flux reCAPTCHA et APN. Une fois configurés pour interagir avec l'émulateur, les SDK clients désactivent ces méthodes de vérification d'une manière similaire à celle décrite pour les tests d'intégration ( iOS , Android , Web ).
  • Testez 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 téléphone/SMS est identique à celui décrit en production ( iOS , Android , web ).

Utilisation de l'interface utilisateur de la suite d'émulateurs :

  1. Dans l'interface utilisateur d'Emulator Suite, 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 du téléphone.

Cependant, pour les flux d'authentification téléphonique, l'émulateur ne déclenchera PAS la livraison de messages texte, car contacter un opérateur est hors de portée et n'est pas adapté aux tests locaux ! Au lieu de cela, l'émulateur imprime le code qui aurait été envoyé par SMS au même terminal sur lequel vous avez exécuté firebase emulators:start ; entrez ce code dans l'application pour simuler les utilisateurs vérifiant leurs messages texte.

Tests non interactifs

Pour les tests d'authentification téléphonique non interactifs, utilisez l'API REST de l'émulateur d'authentification 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 typique est la suivante.

  1. Appelez la plateforme signInWithPhoneNumber pour démarrer le processus de vérification.
  2. Récupérez le code de vérification à l'aide du point de terminaison REST spécifique à l'émulateur .
  3. Appelez confirmationResult.confirm(code) comme d'habitude avec le code de vérification.

SMS multi-facteurs

L'émulateur d'authentification prend en charge le prototypage et le test des flux d'authentification multifacteur (MFA) SMS disponibles en production pour iOS , Android et Web .

Lorsque vous ajoutez un utilisateur fictif à l'émulateur, vous pouvez activer MFA et configurer un ou plusieurs numéros de téléphone auxquels les messages SMS de second facteur seront envoyés. Les messages sont envoyés au même terminal sur lequel vous avez exécuté firebase emulators:start , et disponibles à partir de l'interface REST.

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

L'émulateur d'authentification vous permet de tester de nombreux flux d'authentification tiers dans vos applications iOS, Android ou Web sans aucune modification du code de production. Pour obtenir des exemples de flux d'authentification, consultez la documentation des 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 l'une des deux manières suivantes :

  • Votre application permet au SDK de gérer l'intégralité du processus de bout en bout, y compris toutes les interactions avec les fournisseurs IDP tiers pour récupérer les informations d'identification.
  • Votre application récupère manuellement les informations d'identification d'un fournisseur tiers à l'aide du SDK de cette partie et transmet ces informations d'identification au SDK d'authentification.

Encore une fois, consultez le lien de documentation ci-dessus et assurez-vous que vous connaissez le flux - géré par le SDK Firebase ou récupération manuelle des informations d'identification - que vous souhaitez utiliser. L'émulateur d'authentification prend en charge les tests de l'une ou l'autre approche.

Tester les flux IDP basés sur 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 d'authentification 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, rendue par la bibliothèque de vues Web de votre plate-forme.

L'émulateur crée des comptes d'utilisateurs et des informations d'identification tiers fictifs au fur et à mesure que les flux se déroulent.

Tester les flux IDP avec récupération manuelle des informations d'identification

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

Notez que l'émulateur prend uniquement en charge l'authentification signInWithCredential pour les informations d'identification extraites de Google Sign-In, Apple et d'autres fournisseurs qui utilisent des jetons d'identification 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 JWT) ne sont pas pris en charge. La section suivante traite d'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 servie par l'émulateur. Pour les applications Web, utilisez une interface de contrôle telle que WebDriver. Pour mobile, utilisez les outils de test de l'interface utilisateur de votre plate-forme, comme Espresso ou Xcode.

Vous pouvez également mettre à jour votre code pour utiliser signInWithCredential (par exemple, dans une branche de code) et utiliser un flux d'authentification par jeton avec des jetons d'identification fictifs pour les comptes au lieu de véritables informations d'identification.

  1. Recâblez ou commentez la partie de votre code qui récupère les idTokens de l'IDP ; cela supprime la nécessité de saisir de vrais noms d'utilisateur et mots de passe lors de vos tests, et soulage vos tests des quotas d'API et des limites de débit au niveau 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 authentifiera avec succès un utilisateur avec l'e-mail foo@example.com chez Google. Considérez le sous-champ comme une clé primaire, qui peut être remplacée par n'importe quelle chaîne, se moquant de la signature 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é

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

En quoi l'émulateur d'authentification diffère de la production

L'émulateur Firebase Authentication simule de nombreuses fonctionnalités du produit de production. Cependant, étant donné que 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

Firebase Emulator Suite ne tente pas de répliquer ou de respecter un comportement lié à IAM pour l'exécution. Les émulateurs respectent les règles de sécurité Firebase fournies, mais dans les situations où IAM serait normalement utilisé, par exemple pour définir les fonctions Cloud invoquant le compte de service et donc les autorisations, l'émulateur n'est pas configurable et utilisera le compte disponible dans le monde entier sur votre machine de développeur, similaire à l'exécution directe d'un script local.

Étant donné que sur les plates-formes mobiles, la connexion par lien de messagerie 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 informations d'identification sécurisées de fournisseurs tiers tels que Twitter et Github.

Les informations d'identification réelles des fournisseurs OpenID Connect tels que Google et Apple sont acceptées par l'émulateur d'authentification. Les informations d'identification provenant de fournisseurs autres que OpenID Connect ne sont pas prises en charge.

Connexion par e-mail/SMS

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

L'émulateur ne prend pas en charge la possibilité de définir des numéros de téléphone de test avec des codes de connexion fixes, comme cela peut être fait à l'aide de la console Firebase.

Authentification par jeton personnalisé

L'émulateur d'authentification ne valide pas la signature ou l'expiration des jetons personnalisés. Cela vous permet d'utiliser des jetons fabriqués à la main et de les réutiliser indéfiniment dans des scénarios de prototypage et de test.

Limitation de débit / anti-abus

L'émulateur d'authentification ne réplique pas les fonctionnalités de limitation du taux de production ou anti-abus.

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 . Cependant, en raison de limitations techniques, l'émulateur d'authentification écrit deux fois dans le magasin, une fois après la création de l'utilisateur et une autre après la connexion. Cela signifie que pour les nouveaux utilisateurs, vous pouvez appeler avec succès getAuth().getUser() dans beforeSignIn dans l'émulateur d'authentification, mais vous rencontrerez une erreur en le faisant en production.

Et ensuite ?