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.
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:
Web modular API
import { getAuth, setPersistence, signInWithEmailAndPassword, browserSessionPersistence } from "firebase/auth";
const auth = getAuth();
setPersistence(auth, browserSessionPersistence)
.then(() => {
// Existing and future Auth states are now persisted in the current
// session only. Closing the window would clear any existing state even
// if a user forgets to sign out.
// ...
// New sign-in will be persisted with session persistence.
return signInWithEmailAndPassword(auth, email, password);
})
.catch((error) => {
// Handle Errors here.
const errorCode = error.code;
const errorMessage = error.message;
});
Web namespaced API
firebase.auth().setPersistence(firebase.auth.Auth.Persistence.SESSION)
.then(() => {
// Existing and future Auth states are now persisted in the current
// session only. Closing the window would clear any existing state even
// if a user forgets to sign out.
// ...
// New sign-in will be persisted with session persistence.
return firebase.auth().signInWithEmailAndPassword(email, password);
})
.catch((error) => {
// Handle Errors here.
var errorCode = error.code;
var errorMessage = error.message;
});
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.
Web modular API
import { getAuth, setPersistence, signInWithRedirect, inMemoryPersistence, GoogleAuthProvider } from "firebase/auth";
const auth = getAuth();
setPersistence(auth, inMemoryPersistence)
.then(() => {
const provider = new GoogleAuthProvider();
// In memory persistence will be applied to the signed in Google user
// even though the persistence was set to 'none' and a page redirect
// occurred.
return signInWithRedirect(auth, provider);
})
.catch((error) => {
// Handle Errors here.
const errorCode = error.code;
const errorMessage = error.message;
});
Web namespaced API
firebase.auth().setPersistence(firebase.auth.Auth.Persistence.NONE)
.then(() => {
var provider = new firebase.auth.GoogleAuthProvider();
// In memory persistence will be applied to the signed in Google user
// even though the persistence was set to 'none' and a page redirect
// occurred.
return firebase.auth().signInWithRedirect(provider);
})
.catch((error) => {
// Handle Errors here.
var errorCode = error.code;
var errorMessage = error.message;
});
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.