Conectar o app ao emulador do Authentication

Antes de usar o emulador de Autenticação com seu app, você precisa você precisa conferir o fluxo de trabalho geral do Pacote de emuladores locais do Firebase, além de instalar e configurar esse pacote e revisar os comandos da CLI.

Este tópico pressupõe que você já conhece o desenvolvimento das soluções do Firebase Authentication para produção. Se necessário, consulte a documentação para sua combinação de plataforma e técnica de autenticação.

O que posso fazer com o emulador do Authentication?

Ele fornece a emulação local dos serviços do Firebase Authentication com alta fidelidade, oferecendo grande parte das funções encontradas no Firebase Authentication para produção. Pareado com as plataformas da Apple e os SDKs do Firebase para Android e Web, o emulador permite fazer o seguinte:

• Criar, atualizar e gerenciar contas de usuário emuladas para testar e-mails/senhas, números de telefone/SMS, autenticações multifator por SMS e de provedores de identidade de terceiros (por exemplo, o Google)
• Ver e editar usuários emulados
• Criar protótipos de sistemas de autenticação de tokens personalizados
• Verificar mensagens relacionadas à autenticação na guia "Registros" da IU do emulador

Escolher um projeto do Firebase

O Pacote de emuladores locais do Firebase emula produtos para um único projeto.

Na CLI, execute firebase use no diretório de trabalho antes de iniciar os emuladores para selecionar o projeto a ser usado. Como opção, é possível transmitir a flag --project para cada comando do emulador.

Note: It's generally a good practice to use one project ID for all emulator invocations, so the Emulator Suite UI, different product emulators, and all running instances of a particular emulator can communicate correctly in all cases. Na verdade, por padrão, o Pacote de emuladores locais vai avisar sobre a detecção de vários IDs de projetos em uso, mas é possível modificar esse comportamento. Aprenda a definir e gerenciar IDs de projetos no Guia de instalação e configuração.

O Pacote de emuladores locais oferece suporte à emulação de projetos reais e de demonstração do Firebase.

Tipo de projeto	Recursos	Usar com emuladores
Real	Um projeto real do Firebase é aquele que você criou e configurou (provavelmente pelo Console do Firebase). Os projetos reais têm recursos ativos, como instâncias de banco de dados, buckets de armazenamento, funções ou qualquer outro recurso configurado para o projeto do Firebase.	Ao trabalhar com projetos reais do Firebase, é possível executar emuladores para qualquer um ou todos os produtos suportados. Para todos os produtos que você não estiver emulando, os apps e o código interagem com recursos ativos, como o banco de dados, o bucket de armazenamento, a função etc.
Demonstração	Um projeto de demonstração do Firebase não tem configuração real nem recursos ativos. Em geral, esses projetos são acessados usando codelabs ou outros tutoriais. Os IDs dos projetos de demonstração têm o prefixo demo-.	Ao trabalhar com projetos de demonstração do Firebase, os apps e códigos interagem apenas com emuladores. Se o app tentar interagir com um recurso em que um emulador não esteja em execução, o código falhará.

Recomendamos que você use projetos de demonstração sempre que possível. Alguns dos benefícios são:

• Configuração mais fácil, já que é possível executar os emuladores sem precisar criar um projeto do Firebase
• Mais segurança, já que, se o código invocar acidentalmente recursos não emulados (produção), não haverá chance de alteração, uso e faturamento de dados
• Melhor suporte off-line, já que não é necessário acessar a Internet para fazer o download da configuração do SDK

Observação: para emular interações entre serviços, como funções do Cloud acionadas pelo banco de dados ou regras que dependem do Authentication, verifique se o ID do projeto no código (em initializeApp() etc.) corresponde ao ID do projeto usado pela CLI do Firebase.

Instruir o app para se comunicar com o emulador

SDKs para Android, iOS e Web

Defina a configuração no app ou as classes de teste para interagir com o emulador do Authentication conforme mostrado a seguir.

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)

API modular da Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

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

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

API com namespace da Web

Saiba mais sobre a API Web modular compatível com tree shaking e faça upgrade da API com namespace.

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

Nenhuma outra configuração é necessária para criar protótipos e testar interações entre o Authentication e o Cloud Functions ou as regras de segurança do Firebase para Cloud Firestore ou Realtime Database. Quando o emulador do Authentication estiver configurado e outros emuladores estiverem em execução, eles funcionarão automaticamente em conjunto.

SDKs Admin

Os SDKs Admin do Firebase se conectam automaticamente ao emulador do Authentication quando a variável de ambiente FIREBASE_AUTH_EMULATOR_HOST estiver definida.

export FIREBASE_AUTH_EMULATOR_HOST="127.0.0.1:9099"

O emulador do Cloud Functions reconhece automaticamente o emulador do Authentication. Dessa forma, é possível pular esta etapa ao testar integrações entre os emuladores do Cloud Functions e do Authentication. A variável de ambiente será definida automaticamente para o SDK Admin no Cloud Functions.

Com a variável de ambiente definida, os SDKs Admin do Firebase vão aceitar tokens de ID não assinados e os cookies de sessão emitidos pelo emulador do Authentication (usando métodos verifyIdToken e createSessionCookie, respectivamente), para facilitar o desenvolvimento local e os testes. Não defina a variável de ambiente na produção.

Se você quiser que o código do SDK Admin se conecte a um emulador compartilhado em execução em outro ambiente, especifique o mesmo ID do projeto definido usando a CLI do Firebase. É possível transmitir um ID de projeto para initializeApp diretamente ou definir a variável de ambiente GCLOUD_PROJECT.

SDK Admin para Node.js

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

Variável de ambiente

export GCLOUD_PROJECT="your-project-id"

Tokens de ID

Por motivos de segurança, o emulador do Authentication emite tokens de ID não assinados, que são aceitos somente por outros emuladores do Firebase ou pelo SDK Admin do Firebase quando configurado. Esses tokens vão ser rejeitados por serviços de produção do Firebase ou pelo SDK Admin em execução no modo de produção (por exemplo, o comportamento padrão sem as etapas de configuração descritas acima).

Iniciar o emulador

Você pode usar o emulador do Authentication de maneira interativa na IU do Pacote de emuladores e de maneira não interativa na interface REST local. As seções a seguir abrangem casos de uso interativos e não interativos.

Para iniciar o emulador do Authentication, a interface REST dele e a IU do Pacote de emuladores, execute este comando:

firebase emulators:start

E-mail emulado, link de e-mail e autenticação anônima

Para autenticação anônima, seu app pode usar a lógica de login da sua plataforma (iOS, Android ou Web).

Para autenticação de e-mail/senha, é possível começar a prototipagem adicionando contas de usuário ao emulador do Authentication pelo app usando métodos do SDK do Authentication ou a IU do Pacote de emuladores.

1. Clique na guia Authentication na IU do Pacote de emuladores.
2. Clique no botão Adicionar usuário.
3. Siga o assistente de criação de conta de usuário, preenchendo os campos de autenticação de e-mail.

Com um usuário de teste criado, seu app pode deixar o usuário entrar ou sair com a lógica do SDK para sua plataforma (iOS, Android, Web).

Para testar a verificação de e-mail/login com fluxos de links de e-mail, o emulador imprime um URL no terminal em que firebase emulators:start foi executado.

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

Cole o link no navegador para simular o evento de verificação e veja se ela foi bem-sucedida.

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

Para testar as redefinições de senha, o emulador imprime um URL semelhante, incluindo um parâmetro newPassword (que você pode alterar conforme necessário), no terminal.

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

Teste não interativo

Em vez de usar a IU do Pacote de emuladores ou o código do cliente para gerenciar contas de usuário de e-mail/senha, é possível escrever scripts de configuração de teste que chamam APIs REST. Eles criam e excluem contas de usuário e buscam códigos de verificação de e-mail fora da banda para preencher o URL de verificação de e-mail do emulador. Isso mantém a plataforma e o código de teste separados e permite que você faça o teste de maneira não interativa.

Nos fluxos de teste de e-mail e senha não interativos, a sequência comum é a que aparece a seguir.

1. Crie usuários com o endpoint REST signUp do Authentication.
2. Faça login de usuários usando os e-mails e senhas para realizar testes.
3. Se aplicável aos seus testes, busque códigos de verificação de e-mail fora da banda disponíveis no endpoint REST específico do emulador.
4. Limpe os registros do usuário com o endpoint REST específico do emulador para limpar os dados.

Autenticação emulada por SMS/telefone

Na autenticação feita por smartphone, o emulador do Authentication não suporta as opções a seguir:

• Fluxos reCAPTCHA e APN. Uma vez configurados para interagir com o emulador, os SDKs do cliente desativam estes métodos de verificação de modo semelhante ao descrito no teste de integração (iOS, Android, Web).
• Números de telefone de teste com códigos pré-configurados no Console do Firebase.

Caso contrário, em termos de código do cliente, o fluxo de autenticação por telefone/SMS é idêntico ao descrito para produção (iOS, Android, Web).

Como usar a IU do Pacote de emuladores:

1. Clique na guia Authentication na IU do Pacote de emuladores.
2. Clique no botão Adicionar usuário.
3. Siga o assistente de criação de conta de usuário, preenchendo os campos da autenticação feita por Smartphone.

No entanto, para fluxos de autenticação por smartphone, o emulador NÃO vai acionar a entrega de nenhuma mensagem de texto, já que o contato com uma operadora está fora do escopo e não é adequado para testes locais. Em vez disso, o emulador imprime o código que seria enviado por SMS no mesmo terminal em que você executou firebase emulators:start e insere este código no app para simular usuários verificando as mensagens de texto deles.

Teste não interativo

Para fazer testes da autenticação por smartphone não interativos, use a API REST do emulador do Authentication para recuperar os códigos SMS disponíveis. Observe que o código é diferente sempre que você inicia o fluxo.

A sequência típica é a seguinte.

1. Chame a plataforma signInWithPhoneNumber para iniciar o processo de verificação.
2. Recupere o código de verificação usando o endpoint REST específico do emulador.
3. Chame confirmationResult.confirm(code) como de costume usando o código de verificação.

Autenticação multifator por SMS

O emulador do Authentication tem suporte à prototipagem e ao teste dos fluxos de autenticação multifator (MFA) por SMS disponíveis em produção para iOS, Android e Web.

Ao adicionar um usuário fictício ao emulador, você pode ativar a MFA e configurar um ou mais números de telefone para os quais as mensagens SMS da autenticação vão ser enviadas. O mesmo terminal em que você executou firebase emulators:start recebe as mensagens, e elas ficam disponíveis na interface REST.

Autenticação emulada em um provedor de identidade (IdP) de terceiros

O emulador do Authentication permite testar vários fluxos de autenticação de terceiros em apps iOS, Android ou da Web sem alterar o código de produção. Para exemplos de fluxos de autenticação, consulte a documentação para várias combinações de provedores e plataformas que podem ser usadas no app.

De modo geral, é possível usar o SDK do Firebase para realizar a autenticação de duas maneiras:

• O app permite que o SDK faça o processo completo, incluindo todas as interações com provedores IDP de terceiros para recuperar credenciais.
• O app recupera manualmente as credenciais de um provedor de terceiros usando o SDK dessa empresa e faz a transmissão delas para o SDK do Authentication.

Verifique novamente o link da documentação acima e confira o fluxo que você quer usar: gerenciado pelo SDK Firebase ou pela recuperação manual de credenciais. O emulador do Authentication permite testar qualquer uma dessas abordagens.

Como testar fluxos do IdP voltados para o SDK do Firebase

Se o app usar qualquer fluxo completo do SDK do Firebase, como OAuthProvider para fazer login na Microsoft, no GitHub ou no Yahoo, em testes interativos, o emulador do Authentication vai disponibilizar uma versão local da página de login correspondente para ajudar a testar a autenticação de apps da Web que chamam o método signinWithPopup ou signInWithRedirect. Esta página de login mostrada localmente também aparece em apps para dispositivos móveis, renderizados pela biblioteca de visualização da Web da plataforma.

O emulador cria contas de usuário e credenciais fictícias de terceiros conforme necessário, à medida que os fluxos avançam.

Como testar fluxos do IdP com recuperação manual de credenciais

Se você usar técnicas de login "manuais" e chamar o método signInWithCredentials da plataforma, o app vai solicitar o login real e recuperar credenciais reais de terceiros como de costume.

O emulador tem suporte apenas à autenticação signInWithCredential para credenciais recuperadas do Login do Google, da Apple e de outros provedores que usam tokens de ID implementados como JSON Web Tokens (JWTs). Não há suporte para os tokens de acesso (por exemplo, fornecidos pelo Facebook ou Twitter, que não são JWTs). A próxima seção discute uma alternativa nesses casos.

Teste não interativo

Uma abordagem para testes não interativos é automatizar os cliques do usuário na página de login disponibilizada pelo emulador. Para apps da Web, use uma interface de controle, como o WebDriver. Para dispositivos móveis, use as ferramentas de teste de IU da sua plataforma, como Espresso ou Xcode.

Outra opção é atualizar o código para usar signInWithCredential (por exemplo, em uma ramificação de código) e usar um fluxo de autenticação de token com tokens de ID fictícios para contas, em vez de credenciais reais.

1. Reconecte ou comente na parte do código que recupera idTokens do IDP. Com isso, não será necessário inserir nomes de usuário e senhas reais durante os testes, além de substituir os testes de cotas de API e limites de taxa no IDP.
2. Depois, use uma string JSON literal em vez do token para signInWithCredential. Com o SDK da Web como exemplo, é possível alterar o código para:

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

Quando usado com o emulador, este código autentica um usuário com o e-mail [e-mail] no Google. Pense no subcampo como uma chave primária, que pode ser alterada para qualquer string, simulando o login de usuários diferentes. É possível substituir, por exemplo, firebase.auth.GoogleAuthProvider por new firebase.auth.OAuthProvider('yahoo.com') ou qualquer outro ID de provedor que você quer simular.

Autenticação emulada com tokens personalizados

O emulador do Authentication processa a autenticação com JSON Web Tokens personalizados usando chamadas para o método signInWithCustomToken em plataformas com suporte, conforme descrito na documentação do Authentication para produção.

Qual é a diferença entre o emulador do Authentication e a produção

O emulador do Firebase Authentication simula muitos recursos do produto de produção. No entanto, como qualquer tipo de sistema de autenticação depende fortemente da segurança em vários níveis (dispositivo, provedores de terceiros, Firebase etc.), é difícil para o emulador recriar corretamente todos os fluxos.

Cloud IAM

O Pacote do emuladores do Firebase não tenta replicar nem respeitar qualquer comportamento relacionado ao IAM para execução. Os emuladores aderem às regras de segurança do Firebase. No entanto, em situações em que o IAM normalmente seria usado, por exemplo, para definir as funções do Cloud que invocam a conta de serviço e, portanto, as permissões, o emulador não é configurável e vai usar a conta disponível globalmente na máquina de desenvolvimento, semelhante à execução direta de um script local.

Fazer login por link de e-mail no dispositivo móvel

Como nas plataformas móveis, o login por e-mail depende do Firebase Dynamic Links, todos esses links serão abertos na plataforma da Web (para dispositivos móveis).

Login de terceiros

Para fluxos de login de terceiros, o Firebase Authentication depende de credenciais seguras de provedores de terceiros, como Twitter e GitHub.

Credenciais reais de provedores do OpenID Connect, como Google e Apple, são aceitas pelo emulador do Authentication. As credenciais de provedores que não sejam o OpenID Connect não recebem suporte.

Login com e-mail / SMS

Em apps de produção, os fluxos de login por e-mail e SMS envolvem uma operação assíncrona, em que o usuário verifica uma mensagem recebida e insere um código de login em uma interface de login. O emulador do Authentication não envia e-mails ou mensagens SMS, mas conforme descrito acima, ele gera códigos de login e os envia para o terminal usado durante o teste.

O emulador não tem suporte à capacidade de definir números de telefone de teste com códigos de login fixos, algo que é feito usando o Console do Firebase.

Autenticação com tokens personalizados

O emulador do Authentication não valida a assinatura ou a expiração dos tokens personalizados. Isso permite usar tokens criados manualmente que podem ser reusados indefinidamente em cenários de prototipagem e testes.

Limitação de taxa / antiabuso

O emulador do Authentication não replica recursos de limitação de taxa de produção ou de antiabuso.

Funções de bloqueio

Na produção, os usuários são gravados no armazenamento uma vez após o acionamento dos eventos beforeCreate e beforeSignIn. No entanto, devido a limitações técnicas, o emulador do Authentication grava para armazenar duas vezes, uma após a criação do usuário e outra após o login. Isso significa que, para novos usuários, é possível chamar getAuth().getUser() em beforeSignIn no emulador do Authentication, mas você encontraria um erro ao fazer isso na produção.

A seguir

• Para ver um conjunto selecionado de vídeos e exemplos detalhados de instruções, siga a playlist de treinamento dos emuladores do Firebase.

• Como as funções acionadas são uma integração típica com o Authentication, saiba mais sobre o emulador do Cloud Functions para Firebase em Executar funções localmente.