Connecter votre application à l'émulateur Authentication

Avant d'utiliser l'émulateur Authentication avec votre application, assurez-vous de comprendre le workflow Firebase Local Emulator Suite global, et d'installer et 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 pour 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 la plupart des fonctionnalités disponibles dans Firebase Authentication de production. Associé aux SDK Firebase pour les plates-formes Apple, Android et 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, SMS multifactorielle et fournisseur d'identité tiers (par exemple, Google).
• Afficher et modifier les utilisateurs émulés
• Prototyper des systèmes d'authentification par jeton personnalisés
• Consultez 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 les 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 d'émulateur.

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

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

• Configuration plus facile, car vous pouvez exécuter les émulateurs sans jamais créer de projet Firebase
• Sécurité renforcée : si votre code appelle accidentellement des ressources non émulées (de production), il n'y a aucun risque de modification des données, d'utilisation et de facturation.
• Meilleure compatibilité 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 vos classes de configuration ou de test dans l'application pour interagir avec l'émulateur Authentication comme suit.

Firebase.auth.useEmulator("10.0.2.2", 9099)

FirebaseAuth.getInstance().useEmulator("10.0.2.2", 9099);

Auth.auth().useEmulator(withHost:"127.0.0.1", port:9099)

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

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

const auth = firebase.auth();
auth.useEmulator("http://127.0.0.1:9099");
emulator-suite.js

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 au courant de l'existence de l'émulateur Authentication. Vous pouvez donc ignorer cette étape lorsque vous testez des intégrations entre les émulateurs Cloud Functions et Authentication. La variable d'environnement sera automatiquement définie pour Admin SDK dans Cloud Functions.

Une fois la variable d'environnement définie, les Firebase Admin SDK acceptent les jetons d'identité non signés et les cookies de session émis par l'émulateur Authentication (respectivement via les méthodes verifyIdToken et createSessionCookie) 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é 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.

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Jetons d'identité

Pour des raisons de sécurité, l'émulateur Authentication émet des jetons d'identification 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 refusés par les services Firebase de production ou le SDK Admin Firebase 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 Emulator Suite UI, exécutez la commande suivante :

firebase emulators:start

Authentification par e-mail émulé, lien d'adresse e-mail et authentification anonyme

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 à prototyper en ajoutant des comptes utilisateur à l'émulateur Authentication depuis 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 renseignant les champs d'authentification par e-mail.

Une fois l'utilisateur 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 les flux de validation d'adresse e-mail/de connexion avec un lien par e-mail, l'émulateur affiche une URL dans 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érifiez 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 affiche une URL semblable, 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 avec 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 récupérer les codes de validation d'adresse e-mail hors bande afin de renseigner l'URL de validation d'adresse e-mail de l'émulateur. Cela permet de séparer le code de plate-forme et le code de test, et d'effectuer des tests non interactifs.

Pour les flux de test non interactifs avec adresse e-mail et mot de passe, 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 de leur adresse e-mail et de leur mot de passe pour effectuer des tests.
3. Si cela s'applique à vos tests, 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 avec le 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 clients désactivent ces méthodes de validation de la même manière que celle décrite pour les tests d'intégration (iOS, Android, Web).
• Testez les numéros de téléphone avec les 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).

Utiliser 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 téléphone.

Toutefois, pour les flux d'authentification par téléphone, l'émulateur ne déclenchera PAS l'envoi de SMS, car la prise de contact avec un opérateur n'est pas dans le champ d'application et n'est pas adaptée aux tests locaux. Au lieu de cela, l'émulateur affiche 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 des messages texte par les utilisateurs.

Tests non interactifs

Pour tester l'authentification par téléphone non interactive, 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.

Voici la séquence type :

1. Appelez la plate-forme signInWithPhoneNumber pour lancer la procédure 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 avec le code de validation.

Authentification multifacteur via SMS

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

Lorsque vous ajoutez un utilisateur fictif à l'émulateur, vous pouvez activer l'AMF et configurer un ou plusieurs numéros de téléphone auxquels les messages SMS du 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 de fournisseur d'identité (IdP) tiers émulée

L'émulateur Authentication vous permet de tester de nombreux flux d'authentification tiers dans vos applications iOS, Android ou Web sans modifier le 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 les fournisseurs d'identité tiers pour récupérer les identifiants.
• Votre application récupère manuellement les identifiants auprès d'un fournisseur tiers à l'aide du SDK de ce fournisseur et les transmet au SDK Authentication.

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

Tester les 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, l'émulateur Authentication sert 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 servie localement s'affiche également dans les applications mobiles, rendue par la bibliothèque WebView de votre plate-forme.

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

Tester les flux 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, comme d'habitude, une véritable connexion tierce et récupérera de véritables identifiants tiers.

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'identité 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 acceptés. La section suivante présente une alternative dans ces cas.

Tests non interactifs

Une approche pour les tests non interactifs consiste à automatiser les clics des utilisateurs sur la page de connexion affichée par l'émulateur. Pour les applications Web, utilisez une interface de contrôle comme WebDriver. Pour les mobiles, utilisez les outils de test d'UI 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'identité fictifs pour les comptes au lieu de véritables identifiants.

1. Recâblez ou mettez en commentaire la partie de votre code qui récupère les jetons d'identité auprès du fournisseur d'identité. Cela vous évitera de saisir de vrais noms d'utilisateur et mots de passe lors de vos tests, et vous dispensera de respecter les quotas et les limites de débit de l'API au niveau du fournisseur d'identité.
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 authentifie correctement un utilisateur avec l'adresse 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 pour simuler 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 sur l'environnement de production Authentication.

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

L'émulateur Firebase Authentication simule de nombreuses fonctionnalités du produit de production. Toutefois, comme tout 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 répliquer ni de respecter les comportements liés à IAM pour l'exécution. Les émulateurs respectent les règles de sécurité Firebase fournies. Toutefois, dans les situations où IAM serait normalement utilisé (par exemple, pour définir le compte de service d'appel Cloud Functions et donc les autorisations), l'émulateur n'est pas configurable et utilisera le compte disponible à l'échelle mondiale sur votre machine de développement, comme lors de l'exécution directe d'un script local.

Se connecter via un lien envoyé par e-mail sur mobile

Étant donné que la connexion par lien envoyé par e-mail sur les plates-formes mobiles repose sur Firebase Dynamic Links, tous ces liens seront ouverts 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.

L'émulateur Authentication accepte les identifiants réels des fournisseurs OpenID Connect tels que Google et Apple. 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 dans 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 message SMS, mais comme décrit ci-dessus, il génère des codes de connexion et les affiche dans le terminal pour être utilisés 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 c'est le cas avec 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 créés manuellement et de les réutiliser indéfiniment dans des scénarios de prototypage et de test.

Limitation du débit / Protection contre les utilisations abusives

L'émulateur Authentication ne réplique pas les fonctionnalités de production de limitation du débit ni de lutte contre l'utilisation abusive.

Fonctions de blocage

En production, les utilisateurs sont écrits dans le stockage une seule fois après le déclenchement des événements beforeCreate et beforeSignIn. Toutefois, en raison de contraintes techniques, l'émulateur Authentication é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 getAuth().getUser() dans beforeSignIn dans l'émulateur Authentication, mais que vous rencontrerez une erreur si vous le faites en production.

Et maintenant ?

• Pour découvrir un ensemble organisé de vidéos et d'exemples détaillés, consultez la playlist de formation sur les émulateurs Firebase.

• Étant donné que les fonctions déclenchées sont une intégration typique avec Authentication, découvrez l'émulateur Cloud Functions pour Firebase sur la page Exécuter des fonctions localement.