Authentication State Persistence

You can specify how the Authentication state persists when using the Firebase
JS SDK. This includes the ability to specify whether a signed in user should
be indefinitely persisted until explicit sign out, cleared when the window is
closed or cleared on page reload.

For a web application, the default behavior is to persist a user's session even
after the user closes the browser. This is convenient as the user is not
required to continuously sign-in every time the web page is visited on the same
device. This could require the user having to re-enter their password, send an
SMS verification, etc, which could add a lot of friction to the user experience.

However, there are cases where this behavior may not be ideal:

Applications with sensitive data may want to clear the state when the window
or tab is closed. This is important in case the user forgets to sign out.

Applications that are used on a device shared by multiple users. A common
example here is an app running in a library computer.

An application on a shared device that might be accessed by multiple users.
The developer is unable to tell how that application is accessed and may want
to provide a user with the ability to choose whether to persist their session
or not. This could be done by adding a "Remember me" option during sign-in.

In some situations, a developer may want to not persist an anonymous user
until that user is upgraded to a non-anonymous account (federated, password,
phone, etc.).

A developer may want to allow different users to sign in to an application
on different tabs. The default behavior is to persist the state across tabs
for the same origin.

As stated above, there are multiple situations where the default permanent
persistence may need to be overridden.

Note: Do not confuse Auth state persistence with Firestore
offline data persistence. Auth
state persistence specifies how a user session is persisted on a device.
Whereas Firestore enablePersistence enables Cloud Firestore data caching when
the device is offline.

Supported types of Auth state persistence

You can choose one of three types of Auth state persistence on a specified
Firebase Auth instance based on your application or user's requirements.

Enum

Value

Description

firebase.auth.Auth.Persistence.LOCAL

'local'

Indicates that the state will be persisted even when the browser window is
closed or the activity is destroyed in React Native. An explicit sign out
is needed to clear that state. Note that Firebase Auth web sessions are
single host origin and will be persisted for a single domain only.

firebase.auth.Auth.Persistence.SESSION

'session'

Indicates that the state will only persist in the current session or tab,
and will be cleared when the tab or window in which the user authenticated
is closed. Applies only to web apps.

firebase.auth.Auth.Persistence.NONE

'none'

Indicates that the state will only be stored in memory and will be cleared
when the window or activity is refreshed.

Modifying the Auth state persistence

You can specify or modify the existing type of persistence by calling the
firebase.auth().setPersistence method:

This will change the type of persistence on the specified Auth instance
for the currently saved Auth session and apply this type of persistence for
future sign-in requests, including sign-in with redirect requests. This will
return a promise that will resolve once the state finishes copying from one
type of storage to the other.
Calling a sign-in method after changing persistence will wait for that
persistence change to complete before applying it on the new Auth state.

The default for web browser and React Native apps is local (provided the
browser supports this storage mechanism, eg. 3rd party cookies/data are enabled)
whereas it is none for Node.js backend apps.

Overview of persistence behavior

The following criteria will be applied when determining the current state of
persistence.

Initially, the SDK will check if an authenticated user exists. Unless
setPersistence is called, that user's current persistence type will be
applied for future sign-in attempts. So if that user was persisted in
session on a previous web page and a new page was visited,
signing in again with a different user will result in that user's state being
also saved with session persistence.

If no user is signed in and no persistence is specified, the default setting
will be applied (local in a browser app).

If no user is signed in and a new type of persistence is set, any future
sign-in attempt will use that type of persistence.

If the user is signed in and persistence type is modified, that existing
signed in user will change persistence to the new one. All future sign-in
attempts will use that new persistence.

When signInWithRedirect is called, the current persistence type is retained
and applied at the end of the OAuth flow to the newly signed in user, even if
the persistence was none.
If the persistence is explicitly specified on that page, it will override the
retained auth state persistence from the previous page that started the
redirect flow.

Expected behavior across browser tabs

The following expected behavior will apply when different persistence types are
used in different tabs. The requirement is that at any point, there should never
be multiple types of saved states at the same time (eg. auth state saved in
session and local types of storage):

Users can sign in using session or none persistence with different users
on multiple tabs. Each tab cannot see the state of the other tab.

Any attempt to sign in using local persistence will be detected and
synchronized on all tabs. If the user was previously signed in on a specific
tab using session or none persistence, that state will be cleared.

If the user was previously signed in using local persistence with multiple
tabs opened and then switches to none or session persistence in one tab,
the state of that tab will be modified with the user persisted in
session or none and on all other tabs, the user will be signed out.