Collegare l'app all'emulatore Authentication

Prima di utilizzare l'emulatore Authentication con la tua app, assicurati di comprendere il flusso di lavoro complessivo di Firebase Local Emulator Suite e di installare e configurare Local Emulator Suite, nonché di esaminare i relativi comandi dell'interfaccia a riga di comando.

Questo argomento presuppone che tu abbia già familiarità con lo sviluppo di soluzioni Firebase Authentication per la produzione. Se necessario, consulta la documentazione relativa alla tua combinazione di piattaforma e tecnica di autenticazione.

Cosa posso fare con l'emulatore Authentication?

L'emulatore Authentication fornisce un'emulazione locale ad alta fedeltà dei servizi Firebase Authentication, offrendo gran parte delle funzionalità presenti in Firebase Authentication di produzione. In combinazione con gli SDK Firebase per piattaforme Apple, Android e web, l'emulatore ti consente di:

• Crea, aggiorna e gestisci account utente emulati per testare l'autenticazione di email/password, numero di telefono/SMS, autenticazione a più fattori tramite SMS e provider di identità di terze parti (ad es. Google)
• Visualizzare e modificare gli utenti emulati
• Sistemi di autenticazione con token personalizzati per i prototipi
• Controlla i messaggi relativi all'autenticazione nella scheda Log della UI dell'emulatore.

Scegli un progetto Firebase

Firebase Local Emulator Suite emula i prodotti per un singolo progetto Firebase.

Per selezionare il progetto da utilizzare, prima di avviare gli emulatori, esegui firebase use nell'interfaccia a riga di comando nella directory di lavoro. In alternativa, puoi passare il flag --project a ogni comando dell'emulatore.

Nota: in genere è buona norma utilizzare un ID progetto per tutte le chiamate dell'emulatore, in modo che Emulator Suite UI, i diversi emulatori di prodotti e tutte le istanze in esecuzione di un determinato emulatore possano comunicare correttamente in tutti i casi. In effetti, per impostazione predefinita, Local Emulator Suite genera un avviso quando rileva più ID progetto in uso, anche se puoi eseguire l'override di questo comportamento. Per indicazioni sull'impostazione e sulla gestione degli ID progetto, consulta la guida all'installazione e alla configurazione.

Local Emulator Suite supporta l'emulazione di progetti Firebase reali e progetti demo.

Tipo di progetto	Funzionalità	Utilizzo con gli emulatori
Reale	Un progetto Firebase reale è un progetto che hai creato e configurato (molto probabilmente tramite la console Firebase). I progetti reali hanno risorse attive, come istanze di database, bucket di archiviazione, funzioni o qualsiasi altra risorsa configurata per quel progetto Firebase.	Quando lavori con progetti Firebase reali, puoi eseguire emulatori per uno o tutti i prodotti supportati. Per i prodotti che non stai emulando, le tue app e il tuo codice interagiranno con la risorsa live (istanza di database, bucket di archiviazione, funzione e così via).
Demo	Un progetto Firebase dimostrativo non ha una configurazione Firebase reale e non ha risorse attive. In genere, l'accesso a questi progetti avviene tramite codelab o altri tutorial. Gli ID progetto per i progetti demo hanno il prefisso demo-.	Quando lavori con progetti Firebase dimostrativi, le tue app e il tuo codice interagiscono solo con gli emulatori. Se l'app tenta di interagire con una risorsa per la quale non è in esecuzione un emulatore, il codice non funzionerà.

Ti consigliamo di utilizzare i progetti demo, se possibile. I vantaggi includono:

• Configurazione più semplice, poiché puoi eseguire gli emulatori senza creare un progetto Firebase
• Maggiore sicurezza, poiché se il codice richiama accidentalmente risorse non emulate (di produzione), non c'è alcuna possibilità di modifica dei dati, utilizzo e fatturazione
• Migliore supporto offline, poiché non è necessario accedere a internet per scaricare la configurazione dell'SDK.

Nota: se vuoi emulare interazioni tra servizi, come Cloud Functions o Security Rules attivati dal database che si basano su Authentication, devi assicurarti che l'ID progetto nel codice (in initializeApp() e così via) corrisponda all'ID progetto utilizzato dall'interfaccia a riga di comando Firebase.

Strumenta la tua app per comunicare con l'emulatore

SDK per Android, iOS e web

Configura le classi di configurazione o di test in-app per interagire con l'emulatore Authentication come segue.

Kotlin

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)

Unity

L'host predefinito è 127.0.0.1. Se utilizzi un emulatore Android, devi utilizzare 10.0.2.2.

FirebaseAuth auth = FirebaseAuth.DefaultInstance;
// Connects to the Auth Emulator running on port 9099
auth.UseEmulator("127.0.0.1", 9099);

Web

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

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

Web

Scopri di più sull'API web modulare tree-shakeable e sui suoi vantaggi rispetto all'API con spazio dei nomi.

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

Non è necessaria alcuna configurazione aggiuntiva per creare prototipi e testare le interazioni tra Authentication e Cloud Functions o Firebase Security Rules per Cloud Firestore o Realtime Database. Quando l'emulatore Authentication è configurato e altri emulatori sono in esecuzione, funzionano automaticamente insieme.

Admin SDK s

I Firebase Admin SDK si connettono automaticamente all'emulatore Authentication quando viene impostata la variabile di ambiente FIREBASE_AUTH_EMULATOR_HOST.

export FIREBASE_AUTH_EMULATOR_HOST="127.0.0.1:9099"

Nota: affinché gli emulatori funzionino correttamente, la variabile di ambiente FIREBASE_AUTH_EMULATOR_HOST deve omettere protocolli come http://.

Tieni presente che l'emulatore Cloud Functions riconosce automaticamente l'emulatore Authentication, quindi puoi saltare questo passaggio quando testi le integrazioni tra gli emulatori Cloud Functions e Authentication. La variabile di ambiente verrà impostata automaticamente per Admin SDK in Cloud Functions.

Con la variabile di ambiente impostata, Firebase Admin SDK accetterà token ID non firmati e cookie di sessione emessi dall'emulatore Authentication (rispettivamente tramite i metodi verifyIdToken e createSessionCookie) per facilitare lo sviluppo e i test locali. Assicurati di non impostare la variabile di ambiente in produzione.

Se vuoi che il tuo codice Admin SDK si connetta a un emulatore condiviso in esecuzione in un altro ambiente, devi specificare lo stesso ID progetto che hai impostato utilizzando l'interfaccia a riga di comando di Firebase. Puoi passare un ID progetto direttamente a initializeApp o impostare la variabile di ambiente GCLOUD_PROJECT.

SDK Admin per Node.js

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

Variabile di ambiente

export GCLOUD_PROJECT="your-project-id"

Token ID

Per motivi di sicurezza, l'emulatore Authentication emette token ID non firmati, che vengono accettati solo da altri emulatori Firebase o dall'SDK Firebase Admin se configurato. Questi token verranno rifiutati dai servizi Firebase di produzione o dall'SDK Firebase Admin in esecuzione in modalità di produzione (ad esempio, il comportamento predefinito senza i passaggi di configurazione descritti sopra).

Avvia l'emulatore

Puoi utilizzare l'emulatore Authentication in modo interattivo tramite Emulator Suite UI e in modo non interattivo tramite la sua interfaccia REST locale. Le sezioni seguenti illustrano i casi d'uso interattivi e non interattivi.

Per avviare l'emulatore Authentication, la relativa interfaccia REST e Emulator Suite UI, esegui:

firebase emulators:start

Autenticazione emulata tramite email, link email e anonima

Per l'autenticazione anonima, la tua app può utilizzare la logica di accesso per la tua piattaforma (iOS, Android, web).

Per l'autenticazione con email/password, puoi iniziare la prototipazione aggiungendo account utente all'emulatore Authentication dalla tua app utilizzando i metodi dell'SDK Authentication o utilizzando Emulator Suite UI.

1. In Emulator Suite UI, fai clic sulla scheda Autenticazione.
2. Fai clic sul pulsante Aggiungi utente.
3. Segui la procedura guidata per la creazione dell'account utente, compilando i campi di autenticazione email.

Una volta creato un utente di test, la tua app può consentire l'accesso e l'uscita dell'utente con la logica dell'SDK per la tua piattaforma (iOS, Android, web).

Per testare i flussi di verifica email/accesso con link email, l'emulatore stampa un URL nel terminale in cui è stato eseguito firebase emulators:start.

i  To verify the email address [e-mail], follow this link:
http://127.0.0.1:9099/emulator/action?mode=verifyEmail&lang=en&oobCode=XYZ123&apiKey=fake-api-key

Incolla il link nel browser per simulare l'evento di verifica e controlla se la verifica è andata a buon fine.

{
  "authEmulator": {
    "success": "The email has been successfully verified.",
    "email": "[e-mail]"
  }
}

Per testare le reimpostazioni della password, l'emulatore stampa un URL simile, incluso un parametro newPassword (che puoi modificare in base alle esigenze), nel terminale.

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

Test non interattivi

Anziché utilizzare Emulator Suite UI o il codice client per gestire gli account utente con email/password, puoi scrivere script di configurazione dei test che chiamano le API REST per creare ed eliminare gli account utente e recuperare i codici di verifica email fuori banda per compilare l'URL di verifica email dell'emulatore. In questo modo, il codice della piattaforma e quello del test rimangono separati e puoi eseguire i test in modo non interattivo.

Per i flussi di test non interattivi di email e password, la sequenza tipica è la seguente.

1. Crea utenti con l'endpoint REST signUp di Authentication.
2. Fai accedere gli utenti utilizzando le email e le password per eseguire i test.
3. Se applicabile ai tuoi test, recupera i codici di verifica email out-of-band disponibili dall'endpoint REST specifico dell'emulatore.
4. Svuota i record utente con l'endpoint REST specifico dell'emulatore per cancellare i dati.

Autenticazione tramite telefono/SMS emulati

Per l'autenticazione telefonica, l'emulatore Auth non supporta:

• Flussi reCAPTCHA e APN. Una volta configurati per interagire con l'emulatore, gli SDK client disattivano questi metodi di verifica in modo simile a quanto descritto per i test di integrazione (iOS, Android, web).
• Numeri di telefono di prova con codici preconfigurati nella console Firebase.

In caso contrario, in termini di codice client, il flusso di autenticazione tramite telefono/SMS è identico a quello descritto per la produzione (iOS, Android, web).

Utilizzo di Emulator Suite UI:

1. In Emulator Suite UI, fai clic sulla scheda Autenticazione.
2. Fai clic sul pulsante Aggiungi utente.
3. Segui la procedura guidata per la creazione dell'account utente, compilando i campi di autenticazione tramite telefono.

Tuttavia, per i flussi di autenticazione tramite telefono, l'emulatore NON attiverà l'invio di messaggi, poiché contattare un operatore non rientra nell'ambito e non è adatto ai test locali. L'emulatore stampa invece il codice che sarebbe stato inviato tramite SMS allo stesso terminale in cui hai eseguito firebase emulators:start. Inserisci questo codice nell'app per simulare gli utenti che controllano i propri messaggi.

Test non interattivi

Per i test di autenticazione telefonica non interattivi, utilizza l'API REST dell'emulatore Authentication per recuperare i codici SMS disponibili. Tieni presente che il codice è diverso ogni volta che avvii il flusso.

La sequenza tipica è la seguente.

1. Chiama la piattaforma signInWithPhoneNumber per avviare la procedura di verifica.
2. Recupera il codice di verifica utilizzando l'endpoint REST specifico dell'emulatore.
3. Chiama il numero confirmationResult.confirm(code) come di consueto con il codice di verifica.

Autenticazione a più fattori con SMS

L'emulatore Authentication supporta la prototipazione e il test dei flussi di autenticazione a più fattori (MFA) tramite SMS disponibili in produzione per iOS, Android e web.

Quando aggiungi un utente fittizio all'emulatore, puoi attivare l'MFA e configurare uno o più numeri di telefono a cui verranno inviati gli SMS del secondo fattore. I messaggi vengono inviati allo stesso terminale in cui hai eseguito firebase emulators:start e sono disponibili dall'interfaccia REST.

Autenticazione del provider di identità (IdP) di terze parti emulato

L'emulatore Authentication ti consente di testare molti flussi di autenticazione di terze parti nelle tue app per iOS, Android o app web senza modifiche al codice di produzione. Per esempi di flussi di autenticazione, consulta la documentazione relativa alle varie combinazioni di provider e piattaforme che puoi utilizzare nella tua app.

In generale, puoi utilizzare l'SDK Firebase per l'autenticazione in uno dei due modi seguenti:

• La tua app consente all'SDK di gestire l'intero processo end-to-end, incluse tutte le interazioni con i provider IDP di terze parti per recuperare le credenziali.
• La tua app recupera manualmente le credenziali da un provider di terze parti utilizzando l'SDK di quest'ultima e le trasmette all'SDK Authentication.

Ancora una volta, controlla il link alla documentazione riportato sopra e assicurati di avere familiarità con il flusso che vuoi utilizzare, ovvero il recupero delle credenziali gestito dall'SDK Firebase o manuale. L'emulatore Authentication supporta i test di entrambi gli approcci.

Test dei flussi IDP basati sull'SDK Firebase

Se la tua app utilizza un flusso end-to-end dell'SDK Firebase, come OAuthProvider per l'accesso con Microsoft, GitHub o Yahoo, per i test interattivi, l'emulatore Authentication fornisce una versione locale della pagina di accesso corrispondente per aiutarti a testare l'autenticazione dalle app web che chiamano il metodo signinWithPopup o signInWithRedirect. Questa pagina di accesso pubblicata localmente viene visualizzata anche nelle app mobile, visualizzate dalla libreria webview della tua piattaforma.

L'emulatore crea account utente e credenziali di terze parti fittizi, se necessario, man mano che i flussi procedono.

Test dei flussi IDP con recupero manuale delle credenziali

Se utilizzi tecniche di accesso "manuali" e chiami il metodo signInWithCredentials della tua piattaforma, come di consueto, la tua app richiederà l'accesso di terze parti reale e recupererà le credenziali di terze parti reali.

Tieni presente che l'emulatore supporta l'autenticazione signInWithCredential solo per le credenziali recuperate da Accedi con Google, Apple e altri provider che utilizzano token ID implementati come JSON Web Token (JWT). I token di accesso (ad esempio quelli forniti da Facebook o Twitter, che non sono JWT) non sono supportati. La sezione successiva illustra un'alternativa per questi casi.

Test non interattivi

Un approccio ai test non interattivi consiste nell'automatizzare i clic degli utenti sulla pagina di accesso fornita dall'emulatore. Per le app web, utilizza un'interfaccia di controllo come WebDriver. Per i dispositivi mobili, utilizza gli strumenti di test della UI della tua piattaforma, come Espresso o Xcode.

In alternativa, puoi aggiornare il codice per utilizzare signInWithCredential (ad esempio in un ramo di codice) e utilizzare un flusso di autenticazione dei token con token ID fittizi per gli account anziché credenziali reali.

1. Ricollega o commenta la parte del codice che recupera gli idToken dall'IdP. In questo modo, non è necessario inserire nomi utente e password reali durante i test e i test non sono soggetti a quote API e limiti di frequenza nell'IdP.
2. In secondo luogo, utilizza una stringa JSON letterale al posto del token per signInWithCredential. Utilizzando l'SDK web come esempio, puoi modificare il codice in:

firebase.auth().signInWithCredential(firebase.auth.GoogleAuthProvider.credential(
  '{"sub": "abc123", "email": "[e-mail]", "email_verified": true}'
));

Se utilizzato con l'emulatore, questo codice autenticherà correttamente un utente con l'indirizzo email [e-mail] su Google. Pensa al campo sub come a una chiave primaria, che può essere modificata in qualsiasi stringa, simulando l'accesso di utenti diversi. Puoi sostituire firebase.auth.GoogleAuthProvider con, ad esempio, new firebase.auth.OAuthProvider('yahoo.com') o qualsiasi altro ID provider che vuoi simulare.

Autenticazione con token personalizzato emulato

L'emulatore Authentication gestisce l'autenticazione con token web JSON personalizzati utilizzando chiamate al metodo signInWithCustomToken sulle piattaforme supportate, come descritto nella documentazione di Authentication di produzione.

Differenze tra l'emulatore Authentication e la produzione

L'emulatore Firebase Authentication simula molte funzionalità del prodotto di produzione. Tuttavia, poiché qualsiasi tipo di sistema di autenticazione si basa fortemente sulla sicurezza a più livelli (dispositivo, fornitori di terze parti, Firebase e così via), è difficile per l'emulatore ricreare correttamente tutti i flussi.

Cloud IAM

Firebase Emulator Suite non tenta di replicare o rispettare alcun comportamento relativo a IAM per l'esecuzione. Gli emulatori rispettano le regole di sicurezza di Firebase fornite, ma in situazioni in cui normalmente verrebbe utilizzato IAM, ad esempio per impostare il service account di chiamata di Cloud Functions e quindi le autorizzazioni, l'emulatore non è configurabile e utilizzerà l'account disponibile a livello globale sulla tua macchina di sviluppo, in modo simile all'esecuzione diretta di uno script locale.

Accesso tramite link via email su dispositivo mobile

Poiché sulle piattaforme mobile l'accesso tramite link via email si basa su Firebase Dynamic Links, tutti questi link verranno aperti sulla piattaforma web (mobile).

Accesso di terze parti

Per i flussi di accesso di terze parti, Firebase Authentication si basa su credenziali di sicurezza di provider di terze parti come Twitter e GitHub.

Le credenziali reali dei provider OpenID Connect come Google e Apple sono accettate dall'emulatore Authentication. Le credenziali di provider non OpenID Connect non sono supportate.

Accesso tramite email/SMS

Nelle app di produzione, i flussi di accesso via email e SMS prevedono un'operazione asincrona in cui l'utente controlla un messaggio ricevuto e inserisce un codice di accesso in un'interfaccia di accesso. L'emulatore Authentication non invia email o SMS, ma, come descritto sopra, genera codici di accesso e li restituisce nel terminale per utilizzarli nei test.

L'emulatore non supporta la possibilità di definire numeri di telefono di test con codici di accesso fissi, come è possibile fare utilizzando la console Firebase.

Autenticazione con token personalizzato

L'emulatore Authentication non convalida la firma o la scadenza dei token personalizzati. In questo modo, puoi utilizzare token personalizzati e riutilizzarli all'infinito negli scenari di prototipazione e test.

Limitazione di frequenza/anti-abuso

L'emulatore Authentication non replica le funzionalità di limitazione di frequenza o anti-abuso della produzione.

Funzioni di blocco

In produzione, gli utenti vengono scritti nello spazio di archiviazione una volta dopo l'attivazione degli eventi beforeCreate e beforeSignIn. Tuttavia, a causa di limitazioni tecniche, l'emulatore Authentication scrive nello store due volte: una dopo la creazione dell'utente e un'altra dopo l'accesso. Ciò significa che per i nuovi utenti puoi chiamare correttamente getAuth().getUser() in beforeSignIn nell'emulatore Authentication, ma se lo fai in produzione si verificherà un errore.

Cosa devo fare adesso?

• Per una raccolta di video e istruzioni dettagliate, segui la playlist di formazione sulle suite di emulatori Firebase.

• Poiché le funzioni attivate sono una tipica integrazione con Authentication, scopri di più sull'emulatore Cloud Functions for Firebase in Esegui le funzioni in locale.