Google is committed to advancing racial equity for Black communities. See how.

Connect your app to the Authentication Emulator

Before using the the Authentication emulator with you app, make sure that you understand the overall Firebase Local Emulator Suite workflow and that you install and configure the Local Emulator Suite.

What can I do with the Authentication emulator?

The Authentication emulator provides high-fidelity local emulation of Firebase Authentication services, providing much of the functionality found in production Firebase Authentication. Paired with the iOS, Android and web Firebase SDKs, the emulator lets you:

  • Create, update and manage emulated user accounts for testing email/password, phone number/SMS and sign-in with third-party identity providers (such as Google)
  • View and edit emulated users
  • Check authentication-related messages in the Emulator UI Logs tab.

Instrument your app to talk to the Authentication emulator

Android, iOS, and web SDKs

Set up your in-app configuration or test classes to interact with the Authentication emulator as follows.

Android
FirebaseAuth.getInstance().useEmulator('10.0.2.2', 9099);
iOS - Swift
Auth.auth().useEmulator(withHost:"localhost", port:9099)
Web
firebase.auth().useEmulator('http://localhost:9099/');

No additional setup is needed to prototype and test interactions between Authentication and Cloud Functions or Firebase Security Rules for Cloud Firestore or Realtime Database. When the Authentication emulator is configured and other emulators are running, they automatically work together.

Admin SDKs

The Firebase Admin SDK for Node.js automatically connects to the Authentication emulator when the FIREBASE_AUTH_EMULATOR_HOST environment variable is set.

export FIREBASE_AUTH_EMULATOR_HOST="localhost:9099"

Note that the Cloud Functions emulator is automatically aware of the Authentication emulator. If you are testing integrations between Cloud Functions and Authentication, you don't need to declare the Authentication emulator host this way.

When connecting to the Authentication emulator, you will need to specify a project ID. You can pass a project ID to initializeApp directly or set the GCLOUD_PROJECT environment variable. Note that you do not need to use your real Firebase project ID; the Authentication emulator will accept any project ID.

Node.js Admin SDK
admin.initializeApp({ projectId: "YOUR_PROJECT_ID" };
Environment Variable
export GCLOUD_PROJECT="YOUR_PROJECT_ID"

ID Tokens

For security reasons, the Authentication emulator issues unsigned ID Tokens which are only accepted verifyIdToken and createSessionCookie of the Firebase Admin SDK when running inside the Cloud Functions emulator. When running in any other environment, such as Cloud Run or your own server, these tokens will be rejected by the Admin SDK.

To begin interactive prototyping with the Authentication emulator and the Emulator Suite UI, start the Firebase Local Emulator Suite.

firebase emulators:start

For anonymous authentication, your app can exercise the sign-in logic for your platform (iOS, Android, web).

For email/password authentication, you can start prototyping by adding user accounts to the Authentication emulator from your app using Authentication SDK methods, or by using the Emulator Suite UI.

  1. In the Emulator Suite UI, click the Authentication tab.
  2. Click the Add user button.
  3. Follow the user account creation wizard, filling in the email authentication fields.

With a test user created, your app can sign the user in and out with SDK logic for your platform (iOS, Android, web).

For testing email verification/sign-in with email link flows, the emulator prints a URL to the terminal at which firebase emulators:start was executed.

i  To verify the email address customer@ex.com, follow this link:
http://localhost:9099/emulator/action?mode=verifyEmail&lang=en&oobCode=XYZ123&apiKey=fake-api-key

Paste the link into your browser to simulate the verification event, and check whether verification succeeded.

{
  "authEmulator": {
    "success": "The email has been successfully verified.",
    "email": "customer@example.com"
  }
}

For testing password resets, the emulator prints a similar URL, including a newPassword parameter (which you may change as needed), to the terminal.

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

Non-interactive testing

Instead of using the Emulator Suite UI or client code to manage email/password user accounts, you can write test setup scripts that call REST APIs to create and delete user accounts and fetch out-of-band email verification codes to populate the emulator email verification URL. This keeps platform and test code separate and lets you test non-interactively.

For non-interactive email and password test flows, the typical sequence is as follows.

  1. Create users with the Authentication signUp REST endpoint.
  2. Sign in users using the emails and passwords to perform tests.
  3. If applicable to your tests, fetch available out-of-band email verification codes from the emulator-specific REST endpont.
  4. Flush user records with the emulator-specific REST endpoint for clearing data.

Emulated phone/SMS authentication

For phone authentication, the Auth emulator does not support:

  • reCAPTCHA and APN flows. Once configured to interact with the emulator, client SDKs disable these verification methods in a way similar to that described for integration testing (iOS, Android, web).
  • Test phone numbers with codes preconfigured in the Firebase console.

Otherwise, in terms of client code, the phone/SMS authentication flow is identical to that described for production (iOS, Android, web).

Using the Emulator Suite UI:

  1. In the Emulator Suite UI, click the Authentication tab.
  2. Click the Add user button.
  3. Follow the user account creation wizard, filling in the phone authentication fields.

However, for phone authentication flows, the emulator will NOT trigger delivery of any text messages, since contacting a carrier is out of scope and not friendly for local testing! Instead, the emulator prints out the code that would have been sent via SMS to the same terminal at which you ran firebase emulators:start; input this code to the app to simulate users checking their text messages.

Non-interactive testing

For non-interactive phone authentication testing, use the Authentication emulator REST API to retrieve available SMS codes. Note that the code is different every time you initiate the flow.

The typical sequence is as follows.

  1. Call platform signInWithPhoneNumber to start the verification process.
  2. Retrieve the verification code using the emulator-specific REST endpoint.
  3. Call confirmationResult.confirm(code) as usual with the verification code.

Emulated third-party identity provider (IDP) authentication

The Authentication emulator lets you test many third-party authentication flows in your iOS, Android or web apps with no changes from production code. For examples of authentication flows, consult the documentation for various combinations of providers and platforms you can use in your app.

Generally speaking, you can use the Firebase SDK to authenticate in one of two ways:

  • Your app lets the SDK handle the entire process end-to-end, including all interactions with third-party IDP providers to retrieve credentials.
  • Your app manually retrieves credentials from a third-party provider using that party's SDK and passes those credentials on to the Authentication SDK.

Again, check the documentation link above and make sure you're familiar with whichever flow - Firebase SDK-managed vs. manual credential retrieval - you want to use. The Authentication emulator supports testing of either approach.

Testing Firebase SDK-driven IDP flows

If your app uses any Firebase SDK end-to-end flow, like OAuthProvider for sign-in with Microsoft, GitHub, or Yahoo, for interactive testing, the Authentication emulator serves a local version of the corresponding sign-in page to help you test authentication from web apps that call the signinWithPopup or signInWithRedirect method. This locally-served sign-in page also appears in mobile apps, rendered by your platform's webview library.

The emulator creates mock third-party user accounts and credentials as needed as the flows proceed.

Testing IDP flows with manual credential retrieval

If you use "manual" sign-in techniques and call your platform's signInWithCredentials method, then, as usual, your app will request real third-party sign-in and retrieve real third-party credentials.

Note that the emulator only supports signInWithCredential authentication for credentials retrieved from Google Sign-In, Apple, and other providers that use ID tokens implemented as JSON Web Tokens (JWTs). Access tokens (e.g. those provided by Facebook or Twitter, which are not JWTs) are not supported. The next section discusses an alternative in these cases.

Non-interactive testing

One approach to non-interactive testing is to automate user clicks on the sign-in page served by the emulator. For web apps, use a control interface like WebDriver. For mobile, use the UI test tooling from your platform, like Espresso or Xcode.

Alternatively, you can update your code to use signInWithCredential (e.g. in a code branch) and use a token authentication flow with mock ID tokens for accounts instead of real credentials.

  1. Rewire or comment out the part of your code that retrieve idTokens from the IDP; this removes the need to input real usernames and passwords during your tests, and relieves your tests from API quotas and rate limits at the IDP.
  2. Second, use a literal JSON string in place of the token for signInWithCredential. Using the web SDK as an example, you can change the code to:
firebase.auth().signInWithCredential(firebase.auth.GoogleAuthProvider.credential(
  '{"sub": "abc123", "email": "foo@example.com", "email_verified": true}'
));

When used with the emulator, this code will successfully authenticate a user with email foo@example.com at Google. Think of the sub field as a primary key, which can be changed to any string, mocking signing in different users. You can replace firebase.auth.GoogleAuthProvider with, for example, new firebase.auth.OAuthProvider('yahoo.com') or any other provider ID you want to mock.

What next?