Connecter votre application à l'émulateur Authentication

Avant d'utiliser l'émulateur Authentication avec votre application, assurez-vous de comprendre le workflow global de Firebase Local Emulator Suite, et d'installer et configurer Local Emulator Suite, puis 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 concernant 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 adresse e-mail/mot de passe, numéro de téléphone/SMS, multifacteur par SMS et par 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'interface utilisateur de l'émulateur.

Sélectionner 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 accepte 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 sur des projets Firebase réels, vous pouvez exécuter des émulateurs pour tout ou partie des produits compatibles.

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, 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 utiliser des ateliers de programmation ou d'autres tutoriels.

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

Lorsque vous utilisez 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 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 connaît automatiquement 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 est automatiquement définie pour Admin SDK dans Cloud Functions.

Lorsque la variable d'environnement est définie, les Firebase Admin SDK acceptent 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 local et les tests. 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 Admin 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 Authentication de manière interactive via Emulator Suite UI et de manière non interactive via son interface REST locale. Les sections suivantes traitent des 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 qu'un utilisateur test est créé, votre application peut connecter l'utilisateur et s'en déconnecter à l'aide de la logique du SDK pour votre plate-forme (iOS, Android, Web).

Pour tester la validation/la connexion d'adresse e-mail avec des flux de liens par e-mail, l'émulateur affiche 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 Emulator Suite UI ou le code client pour gérer les comptes utilisateur de type "adresse 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 utilisateur, et extraire des codes de validation d'adresse e-mail hors bande pour renseigner l'URL de validation de l'adresse e-mail de l'émulateur. Le code de plate-forme et le code de test sont ainsi séparés, et vous pouvez tester de manière non interactive.

Pour les flux de test d'e-mails et de mots de passe non interactifs, la séquence est généralement la suivante.

  1. Créez des utilisateurs avec le point de terminaison REST d'inscription 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 d'adresse e-mail hors bande disponibles à partir du point de terminaison REST spécifique à l'émulateur.
  4. Videz 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:

  • 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 des 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).

Avec 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 le confirmationResult.confirm(code) comme d'habitude en indiquant le code de validation.

Authentification multifacteur via SMS

L'émulateur Authentication prend en charge le prototypage et le test des flux d'authentification multifacteur (MFA) SMS disponibles en production pour iOS, Android et le 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 par fournisseur d'identité tiers émulé

L'émulateur Authentication 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 sur les différentes combinaisons de fournisseurs et de plates-formes que vous pouvez utiliser dans votre application.

En règle 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 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.

À nouveau, cliquez sur le lien vers la documentation ci-dessus et assurez-vous de bien connaître le parcours que vous souhaitez utiliser (gestion par SDK Firebase ou récupération manuelle des identifiants). L'émulateur Authentication permet de tester l'une ou l'autre approche.

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 diffuse une version locale de la page de connexion correspondante pour vous aider à tester l'authentification des applications Web qui appellent la méthode signinWithPopup ou signInWithRedirect. Cette page de connexion diffusée localement apparaît également dans les applications mobiles et est 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, comme d'habitude, votre application demandera une véritable connexion tierce et récupérera des identifiants tiers réels.

Notez que l'émulateur n'accepte que l'authentification signInWithCredential pour les identifiants récupérés depuis Google Sign-In, 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 (tels que ceux fournis par Facebook ou Twitter, qui ne sont pas des 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 utiliser 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. Modifiez ou mettez en commentaire la partie de votre code qui récupère les idTokens à partir de l'IdP. Cela évite d'avoir à saisir de vrais noms d'utilisateur et mots de passe pendant vos tests, et libère ces derniers des quotas d'API et des limites de débit au niveau de l'IdP.
  2. Ensuite, 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 permet d'authentifier 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é

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. Cependant, comme tout type de système d'authentification s'appuie 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. Toutefois, dans les situations où IAM est normalement utilisé, par exemple pour définir Cloud Functions qui appelle un compte de service et donc des autorisations, l'émulateur n'est pas configurable et utilise le compte disponible dans le monde entier sur votre ordinateur de développement, comme lorsque vous exécutez directement un script local.

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

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 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 pas d'e-mails ni de SMS, mais, comme décrit ci-dessus, il génère des codes de connexion et les transmet au terminal à des fins de test.

L'émulateur ne permet pas 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 Authentication ne valide pas la signature ni l'expiration des jetons personnalisés. Cela vous permet d'utiliser des jetons fabriqués manuellement et de les réutiliser indéfiniment dans des 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 limitations techniques, l'émulateur Authentication écrit pour être stocké deux fois : 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 getAuth().getUser() dans beforeSignIn dans l'émulateur Authentication, mais vous rencontrerez une erreur en production.

Et maintenant ?