Connectez votre application à l'émulateur d'authentification

Avant d'utiliser l'émulateur d'authentification avec votre application, assurez-vous de bien comprendre le flux de travail global de Firebase Local Emulator Suite , d' installer et de configurer Local Emulator Suite et de revoir 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 plateforme 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 l'authentification Firebase de production . Associé aux plateformes Apple, aux SDK Android et Web Firebase, l'émulateur vous permet de :

  • Créez, mettez à jour et gérez des comptes d'utilisateurs émulés pour tester l'authentification par courrier électronique/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
  • Prototype 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 Firebase Local Emulator émule les produits pour un seul projet Firebase.

Pour sélectionner le projet à utiliser, avant de démarrer les émulateurs, dans la CLI, firebase use dans votre répertoire de travail. Vous pouvez également transmettre l'indicateur --project à chaque commande d'é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 disposent de 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 actives. 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 portent le préfixe demo- .

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

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

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

Instrumentez votre application pour communiquer avec l'émulateur

SDK Android, iOS et Web

Configurez votre configuration dans l'application ou testez vos 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 reconnaît automatiquement l'émulateur d'authentification. Vous pouvez donc ignorer cette étape lorsque vous testez les 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.

Une fois la variable d'environnement définie, les SDK d'administration Firebase 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. Veuillez vous assurer de ne pas définir la variable d'environnement en production.

Si vous souhaitez que votre code SDK Admin se connecte à un émulateur partagé exécuté dans un autre environnement, vous devrez spécifier le même ID de projet 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 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 par le SDK d'administration Firebase 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 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 plateforme ( 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 en utilisant 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.

Une fois 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/connexion des e-mails avec les flux de liens de messagerie, 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 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 la réinitialisation du mot de passe, l'émulateur imprime une URL similaire, comprenant un paramètre newPassword (que vous pouvez modifier si nécessaire), sur 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 l'interface utilisateur d'Emulator Suite ou le code client pour gérer les comptes utilisateur de messagerie/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 récupérer les codes de vérification de messagerie hors bande pour remplir la vérification de messagerie 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 d'authentification.
  2. Connectez les utilisateurs à l’aide des e-mails et des mots de passe pour effectuer des tests.
  3. Le cas échéant, récupérez les codes de vérification de courrier électronique 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.

Par ailleurs, 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 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 du téléphone.

Cependant, pour les flux d'authentification téléphonique, l'émulateur ne déclenchera AUCUN message texte, car contacter un opérateur est hors de portée et n'est pas convivial pour les 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 ; saisissez ce code dans l'application pour simuler la vérification par les utilisateurs de 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 multifacteurs

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 deuxième facteur seront envoyés. Les messages sont envoyés au même terminal sur lequel vous avez exécuté firebase emulators:start et sont disponibles depuis l'interface REST.

Authentification émulée du 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 par rapport au code de production. Pour obtenir des exemples de flux d'authentification, consultez la documentation relative aux 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 des 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 ce tiers et transmet ces informations d'identification au SDK d'authentification.

Encore une fois, vérifiez le lien de documentation ci-dessus et assurez-vous que vous êtes familier avec le flux - gestion du SDK Firebase ou récupération manuelle des informations d'identification - que vous souhaitez utiliser. L'émulateur d'authentification prend en charge les tests des deux approches.

Test des flux IDP piloté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, à des fins de tests interactifs, l'émulateur d'authentification propose une version locale de la page de connexion correspondante pour vous aider à tester. authentification à partir d'applications Web qui appellent la méthode signinWithPopup ou signInWithRedirect . Cette page de connexion servie localement apparaît également dans les applications mobiles, rendues par la bibliothèque de vues Web de votre plateforme.

L'émulateur crée des comptes d'utilisateurs tiers fictifs et des informations d'identification selon les besoins au fur et à mesure du déroulement des flux.

Test des 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 à un tiers et récupérera de véritables informations d'identification de tiers.

Notez que l'émulateur prend uniquement en charge l'authentification signInWithCredential pour les informations d'identification récupérées depuis 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 discute 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 d'interface utilisateur de votre plateforme, 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 le besoin de saisir de vrais noms d'utilisateur et mots de passe pendant 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 modifier le code comme suit :
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 modifiée en n'importe quelle chaîne, se moquant de la connexion de différents utilisateurs. Vous pouvez remplacer firebase.auth.GoogleAuthProvider par, par exemple, new firebase.auth.OAuthProvider('yahoo.com') ou tout autre identifiant de fournisseur dont vous souhaitez vous moquer.

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 d'authentification de production .

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

IAM dans le cloud

La suite d'émulateurs Firebase ne tente pas de répliquer ou de respecter tout comportement lié à IAM lors de son exécution. Les émulateurs adhèrent aux règles de sécurité Firebase fournies, mais dans les situations où IAM serait normalement utilisé, par exemple pour définir le compte de service appelant Cloud Functions et donc les autorisations, l'émulateur n'est pas configurable et utilisera le compte disponible mondialement sur votre ordinateur 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 courrier électronique repose sur les liens dynamiques Firebase, tous ces liens seront ouverts sur la plate-forme Web (mobile).

Connexion par un tiers

Pour les flux de connexion tiers, l'authentification Firebase s'appuie sur des informations d'identification sécurisées provenant de fournisseurs tiers tels que Twitter et Github.

Les véritables informations d'identification des fournisseurs OpenID Connect tels que Google et Apple sont acceptées par l'émulateur d'authentification. Les informations d'identification provenant de fournisseurs non 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 saisit un code de connexion dans une interface de connexion. L'émulateur d'authentification n'envoie aucun e-mail ni message 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 reproduit 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 ?