FirebaseUI is an open-source JavaScript library for Web that provides simple, customizable UI bindings on top of Firebase SDKs to eliminate boilerplate code and promote best practices.
FirebaseUI Auth provides a drop-in auth solution that handles the UI flows for signing in users with email addresses and passwords, and Identity Provider Sign In using Google, Facebook and others. It is built on top of Firebase Auth.
The FirebaseUI component implements best practices for authentication on mobile devices and websites, helping to sign-in and sign-up conversion for your app. It also handles cases like account recovery and account linking that can be security sensitive and error-prone to handle.
FirebaseUI Auth clients are also available for iOS and Android.
FirebaseUI fully supports all recent browsers. Signing in with federated providers (Google, Facebook, Twitter, Github) is also supported in Cordova/Ionic environments. Additional non-browser environments (React Native...) or Chrome extensions will be added once the underlying Firebase core SDK supports them in a way that is compatible with FirebaseUI.
- Demo
- Installation
- Usage instructions
- Configuration
- Customization
- Advanced
- Developer Setup
- Cordova Setup
- Known issues
- Release Notes
Accessible here: https://fir-ui-demo-84a6c.firebaseapp.com.
You just need to include the following script and CSS file in the <head>
tag
of your page, below the initialization snippet from the Firebase Console:
<script src="https://cdn.firebase.com/libs/firebaseui/2.3.0/firebaseui.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.firebase.com/libs/firebaseui/2.3.0/firebaseui.css" />
Localized versions of the widget are available through the CDN. To use a localized widget, load the localized JS library instead of the default library:
<script src="https://www.gstatic.com/firebasejs/ui/2.3.0/firebase-ui-auth__{LANGUAGE_CODE}.js"></script>
<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/firebasejs/ui/2.3.0/firebase-ui-auth.css" />
where {LANGUAGE_CODE}
is replaced by the code of the language you want. For example, the French
version of the library is available at
https://www.gstatic.com/firebasejs/ui/2.3.0/firebase-ui-auth__fr.js
. The list of available
languages and their respective language codes can be found at LANGUAGES.md.
Right-to-left languages also require the right-to-left version of the stylesheet, available at
https://www.gstatic.com/firebasejs/ui/2.3.0/firebase-ui-auth-rtl.css
, instead of the default
stylesheet. The supported right-to-left languages are Arabic (ar), Farsi (fa), and Hebrew (iw).
Install FirebaseUI and its dependencies via npm using the following command:
$ npm install firebaseui --save
You can then require
the following modules within your source files:
var firebase = require('firebase');
var firebaseui = require('firebaseui');
Or include the required files in your HTML, if your HTTP Server serves the files
within node_modules/
:
<script src="node_modules/firebaseui/dist/firebaseui.js"></script>
<link type="text/css" rel="stylesheet" href="node_modules/firebaseui/dist/firebaseui.css" />
Install FirebaseUI and its dependencies via Bower using the following command:
$ bower install firebaseui --save
You can then include the required files in your HTML, if your HTTP Server serves
the files within bower_components/
:
<script src="bower_components/firebaseui/dist/firebaseui.js"></script>
<link type="text/css" rel="stylesheet" href="bower_components/firebaseui/dist/firebaseui.css" />
FirebaseUI includes the following flows:
- Interaction with Identity Providers such as Google and Facebook
- Phone number based authentication
- Sign-up and sign-in with email accounts
- Password reset
- Prevention of account duplication (activated when "One account per email address" setting is enabled in the Firebase console. This setting is enabled by default.)
- Account Chooser for remembering emails
To use FirebaseUI to authenticate users you first need to configure each provider you want to use in their own developer app settings. Please read the Before you begin section of Firebase Authentication at the following links:
You first need to initialize your
Firebase app. The
firebase.auth.Auth
instance should be passed to the constructor of
firebaseui.auth.AuthUI
. You can then call the start
method with the CSS
selector that determines where to create the widget, and a configuration object.
The following example shows how to set up a sign-in screen with all supported providers. Please refer to the demo application in the examples folder for a more in-depth example, showcasing a Single Page Application mode.
Firebase and FirebaseUI do not work when executed directly from a file (i.e. opening the file in your browser, not through a web server). Always run
firebase serve
(or your preferred local server) to test your app locally.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Sample FirebaseUI App</title>
<!-- *******************************************************************************************
* TODO(DEVELOPER): Paste the initialization snippet from:
* Firebase Console > Overview > Add Firebase to your web app. *
***************************************************************************************** -->
<script src="https://cdn.firebase.com/libs/firebaseui/2.3.0/firebaseui.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.firebase.com/libs/firebaseui/2.3.0/firebaseui.css" />
<script type="text/javascript">
// FirebaseUI config.
var uiConfig = {
signInSuccessUrl: '<url-to-redirect-to-on-success>',
signInOptions: [
// Leave the lines as is for the providers you want to offer your users.
firebase.auth.GoogleAuthProvider.PROVIDER_ID,
firebase.auth.FacebookAuthProvider.PROVIDER_ID,
firebase.auth.TwitterAuthProvider.PROVIDER_ID,
firebase.auth.GithubAuthProvider.PROVIDER_ID,
firebase.auth.EmailAuthProvider.PROVIDER_ID,
firebase.auth.PhoneAuthProvider.PROVIDER_ID
],
// Terms of service url.
tosUrl: '<your-tos-url>'
};
// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());
// The start method will wait until the DOM is loaded.
ui.start('#firebaseui-auth-container', uiConfig);
</script>
</head>
<body>
<!-- The surrounding HTML is left untouched by FirebaseUI.
Your app may use that space for branding, controls and other customizations.-->
<h1>Welcome to My Awesome App</h1>
<div id="firebaseui-auth-container"></div>
</body>
</html>
Here is how you would track the Auth state across all your pages:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Sample FirebaseUI App</title>
<!-- *******************************************************************************************
* TODO(DEVELOPER): Paste the initialization snippet from:
* Firebase Console > Overview > Add Firebase to your web app. *
***************************************************************************************** -->
<script type="text/javascript">
initApp = function() {
firebase.auth().onAuthStateChanged(function(user) {
if (user) {
// User is signed in.
var displayName = user.displayName;
var email = user.email;
var emailVerified = user.emailVerified;
var photoURL = user.photoURL;
var uid = user.uid;
var phoneNumber = user.phoneNumber;
var providerData = user.providerData;
user.getIdToken().then(function(accessToken) {
document.getElementById('sign-in-status').textContent = 'Signed in';
document.getElementById('sign-in').textContent = 'Sign out';
document.getElementById('account-details').textContent = JSON.stringify({
displayName: displayName,
email: email,
emailVerified: emailVerified,
phoneNumber: phoneNumber,
photoURL: photoURL,
uid: uid,
accessToken: accessToken,
providerData: providerData
}, null, ' ');
});
} else {
// User is signed out.
document.getElementById('sign-in-status').textContent = 'Signed out';
document.getElementById('sign-in').textContent = 'Sign in';
document.getElementById('account-details').textContent = 'null';
}
}, function(error) {
console.log(error);
});
};
window.addEventListener('load', function() {
initApp()
});
</script>
</head>
<body>
<h1>Welcome to My Awesome App</h1>
<div id="sign-in-status"></div>
<div id="sign-in"></div>
<div id="account-details"></div>
</body>
</html>
FirebaseUI supports the following configuration parameters.
Name | Required | Description |
---|---|---|
callbacks | No |
A list of developers callbacks after
specific events.
Default: []
|
credentialHelper | No |
The Credential Helper to use.
See Credential Helper.
Default: firebaseui.auth.CredentialHelper.ACCOUNT_CHOOSER_COM
|
queryParameterForSignInSuccessUrl | No |
The redirect URL parameter name for the sign-in success URL. See
Overwriting the sign-in success URL.
Default: "signInSuccessUrl"
|
queryParameterForWidgetMode | No |
The redirect URL parameter name for the “mode” of the Widget.
See FirebaseUI widget modes.
Default: "mode"
|
signInFlow | No |
The sign-in flow to use for IDP providers: redirect or
popup .
Default: "redirect"
|
signInOptions | Yes | The list of providers enabled for signing into your app. The order you specify them will be the order they are displayed on the sign-in provider selection screen. |
signInSuccessUrl | No |
The URL where to redirect the user after a successful sign-in.
Required when the signInSuccess callback is not
used or when it returns true .
|
tosUrl | Yes | The URL of the Terms of Service page. |
The role of a credential helper is to help your users sign into you website. When one is enabled, your users will be prompted with email addresses and usernames they have saved from your app or other applications. To achieve this, accountchooser.com is available. Upon signing in or signing up with email, the user will be redirected to the accountchooser.com website and will be able to select one of their saved accounts. It is recommended to use this, but you can also disable it by specifying the value below. This feature is always disabled for non HTTP/HTTPS environments.
Credential Helper | Value |
---|---|
accountchooser.com | firebaseui.auth.CredentialHelper.ACCOUNT_CHOOSER_COM |
None (disable) | firebaseui.auth.CredentialHelper.NONE |
Provider | Value |
---|---|
firebase.auth.GoogleAuthProvider.PROVIDER_ID |
|
firebase.auth.FacebookAuthProvider.PROVIDER_ID |
|
firebase.auth.TwitterAuthProvider.PROVIDER_ID |
|
Github | firebase.auth.GithubAuthProvider.PROVIDER_ID |
Email and password | firebase.auth.EmailAuthProvider.PROVIDER_ID |
Phone number | firebase.auth.PhoneAuthProvider.PROVIDER_ID |
To specify custom scopes, or custom OAuth parameters per provider, you can pass an object instead of just the provider value:
ui.start('#firebaseui-auth-container', {
signInOptions = [
{
provider: firebase.auth.GoogleAuthProvider.PROVIDER_ID,
scopes: [
'https://www.googleapis.com/auth/plus.login'
],
customParameters: {
// Forces account selection even when one account
// is available.
prompt: 'select_account'
}
},
{
provider: firebase.auth.FacebookAuthProvider.PROVIDER_ID,
scopes: [
'public_profile',
'email',
'user_likes',
'user_friends'
],
customParameters: {
// Forces password re-entry.
auth_type: 'reauthenticate'
}
},
firebase.auth.TwitterAuthProvider.PROVIDER_ID, // Twitter does not support scopes.
firebase.auth.EmailAuthProvider.PROVIDER_ID // Other providers don't need to be given as object.
]
});
The EmailAuthProvider
can be configured to require the user to enter a display name (defaults to true
).
ui.start('#firebaseui-auth-container', {
signInOptions = [
{
provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
requireDisplayName: false
}
]
});
The PhoneAuthProvider
can be configured with custom reCAPTCHA parameters
whether reCAPTCHA is visible or invisible (defaults to normal
). Refer to the
reCAPTCHA API docs for
more details.
The default country to select in the phone number input can also be set. List of supported country codes. If unspecified, the phone number input will default to the United States (+1).
The following options are currently supported. Any other parameters will be ignored.
ui.start('#firebaseui-auth-container', {
signInOptions = [
{
provider: firebase.auth.PhoneAuthProvider.PROVIDER_ID,
recaptchaParameters: {
type: 'image', // 'audio'
size: 'normal', // 'invisible' or 'compact'
badge: 'bottomleft' //' bottomright' or 'inline' applies to invisible.
},
defaultCountry: 'GB' // Set default country to the United Kingdom (+44).
}
]
});
Two sign in flows are available:
redirect
, the default, will perform a full page redirect to the sign-in page of the provider (Google, Facebook...). This is recommended for mobile apps.- The
popup
flow will open a popup to the sign-in page of the provider. If the popup is blocked by the browser, it will fall back to a full page redirect.
Parameters:
Name | Type | Optional | Description |
---|---|---|---|
currentUser |
firebase.User |
No | The logged in user. |
credential |
firebase.auth.AuthCredential |
Yes | The credential used to sign in the user. |
redirectUrl |
string |
Yes | The URL where the user is redirected after the callback finishes. It will only be given if you overwrite the sign-in success URL. |
Should return: boolean
If the callback returns true
, then the page is automatically redirected
depending on the case:
- If no
signInSuccessUrl
parameter was given in the URL (See: Overwriting the sign-in success URL) then the defaultsignInSuccessUrl
in config is used. - If the value is provided in the URL, that value will be used instead of the
static
signInSuccessUrl
in config.
If the callback returns false
or nothing, the page is not automatically
redirected.
This callback is triggered the first time the widget UI is rendered. This is useful for cases where the application should display a custom loader before FirebaseUI is displayed.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Sample FirebaseUI App</title>
<!-- *******************************************************************************************
* TODO(DEVELOPER): Paste the initialization snippet from:
* Firebase Console > Overview > Add Firebase to your web app. *
***************************************************************************************** -->
<script src="https://cdn.firebase.com/libs/firebaseui/2.3.0/firebaseui.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.firebase.com/libs/firebaseui/2.3.0/firebaseui.css" />
<script type="text/javascript">
// FirebaseUI config.
var uiConfig = {
callbacks: {
signInSuccess: function(currentUser, credential, redirectUrl) {
// Do something.
// Return type determines whether we continue the redirect automatically
// or whether we leave that to developer to handle.
return true;
},
uiShown: function() {
// The widget is rendered.
// Hide the loader.
document.getElementById('loader').style.display = 'none';
}
},
credentialHelper: firebaseui.auth.CredentialHelper.ACCOUNT_CHOOSER_COM,
// Query parameter name for mode.
queryParameterForWidgetMode: 'mode',
// Query parameter name for sign in success url.
queryParameterForSignInSuccessUrl: 'signInSuccessUrl',
// Will use popup for IDP Providers sign-in flow instead of the default, redirect.
signInFlow: 'popup',
signInSuccessUrl: '<url-to-redirect-to-on-success>',
signInOptions: [
// Leave the lines as is for the providers you want to offer your users.
firebase.auth.GoogleAuthProvider.PROVIDER_ID,
firebase.auth.FacebookAuthProvider.PROVIDER_ID,
firebase.auth.TwitterAuthProvider.PROVIDER_ID,
{
provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
// Whether the display name should be displayed in the Sign Up page.
requireDisplayName: true
},
{
provider: firebase.auth.PhoneAuthProvider.PROVIDER_ID,
// Invisible reCAPTCHA with image challenge and bottom left badge.
recaptchaParameters: {
type: 'image',
size: 'invisible',
badge: 'bottomleft'
}
}
],
// Terms of service url.
tosUrl: '<your-tos-url>'
};
var ui = new firebaseui.auth.AuthUI(firebase.auth());
// The start method will wait until the DOM is loaded.
ui.start('#firebaseui-auth-container', uiConfig);
</script>
</head>
<body>
<!-- The surrounding HTML is left untouched by FirebaseUI.
Your app may use that space for branding, controls and other customizations.-->
<h1>Welcome to My Awesome App</h1>
<div id="firebaseui-auth-container"></div>
<div id="loader">Loading...</div>
</body>
</html>
Currently, FirebaseUI does not offer customization out of the box. However, the HTML around the widget is not affected by it so you can display everything you want around the widget container.
Upon initialization, FirebaseUI will look for the mode
parameter in the URL.
Depending on the value of this parameter, it will trigger a specific mode. When
no mode
parameter is found, it will default to the sign-in mode.
You can change the name of this parameter with the queryParameterForWidgetMode
configuration parameter.
Query parameter value | Description |
---|---|
?mode=select |
Sign-in mode |
Example:
https://<url-of-the-widget>?mode=select
You can pass a query parameter to the widget's URL that will overwrite the URL
the user is redirected to after a successful sign-in. If you do so, you must set
the configuration signInSuccessUrl
value (even if it will be overwritten).
When passing the redirect URL this way, the signInSuccess
callback will
receive the value as the redirectUrl
argument.
You must include the mode explicitly in the URL when using the
signInSuccessUrl
parameter, otherwise FirebaseUI will directly redirect to the
URL specified.
You can change the name of this parameter with the
queryParameterForSignInSuccessUrl
configuration parameter.
Example:
https://<url-of-the-widget>?mode=select&signInSuccessUrl=signedIn.html
will
redirect the user to https://<url-of-the-widget>/signedIn.html
after a
successful sign-in flow.
To set up a development environment to build FirebaseUI from source, you must have the following installed:
- Node.js (>= 6.0.0)
- npm (should be included with Node.js)
- Java Runtime Environment
In order to run the demo and tests, you must also have:
- Python (2.7)
Download the FirebaseUI source and its dependencies with:
git clone https://github.com/firebase/firebaseui-web.git
cd firebaseui-web
npm install
To build the library, run:
npm run build
This will create output files in the dist/
folder.
To build a localized JavaScript binary, run:
npm run build build-js-{LANGUAGE_CODE}
where {LANGUAGE_CODE}
is replaced by the
code of the language you want. For example, the French binary
can be built with npm run build build-js-fr
. This will create a binary
firebaseui__fr.js
in the dist/
folder.
To run the demo app, you must have a Firebase project set up on the
Firebase Console. Copy
demo/public/sample-config.js
to demo/public/config.js
:
cp demo/public/sample-config.js demo/public/config.js
Copy the data from the "Add Firebase to your web app" flow in Firebase Console. Next, run
npm run demo
This will start a local server serving a FirebaseUI demo app with all local changes. More details can be found in the demo app folder, covering how to configure the app to be deployed on a Firebase Hosting instance.
All unit tests can be run on the command line (via PhantomJS) with:
npm test
Alternatively, the unit tests can be run manually by running
npm run serve
Then, all unit tests can be run at: http://localhost:4000/buildtools/all_tests.html
You can also run tests individually by accessing each HTML file under
generated/tests
, for example: http://localhost:4000/generated/tests/javascript/widgets/authui_test.html
You need a SauceLabs account to run tests on SauceLabs.
Go to your SauceLab account, under "My Account", and copy paste the access key. Now export the following variables, in two Terminal windows:
export SAUCE_USERNAME=<your username>
export SAUCE_ACCESS_KEY=<the copy pasted access key>
Then, in one Terminal window, start SauceConnect:
./buildtools/sauce_connect.sh
Take note of the "Tunnel Identifier" value logged in the terminal,at the top. In the other terminal that has the exported variables, run the tests:
npm test -- --saucelabs --tunnelIdentifier=<the tunnel identifier>
FirebaseUI sign-in widget supports Cordova applications. This includes email/password and all OAuth providers (Google, Facebook, Twitter and GitHub). Phone authentication is not supported due to the limitation in the underlying Firebase core SDK.
Provider | Value |
---|---|
firebase.auth.GoogleAuthProvider.PROVIDER_ID |
|
firebase.auth.FacebookAuthProvider.PROVIDER_ID |
|
firebase.auth.TwitterAuthProvider.PROVIDER_ID |
|
Github | firebase.auth.GithubAuthProvider.PROVIDER_ID |
Email and password | firebase.auth.EmailAuthProvider.PROVIDER_ID |
In order to integrate FirebaseUI with your Cordova application, you need to follow these steps:
- Install the necessary Cordova plugins, make the necessary Firebase Console changes and update your config.xml file as documented in OAuth Sign-In for Cordova
- After you have successfully configured your application, you can use FirebaseUI in your Cordova application just like any other traditional browser applications.
Keep in mind the following while you set up the app:
- Only
redirect
signInFlow
is supported as Firebase Auth does not supportpopup
mode for Cordova. firebase.auth.PhoneAuthProvider.PROVIDER_ID
is not currently supported.- As the application runs within an embedded webview,
accountchooser.com
will always be disabled. - If you are providing a
Content-Security-Policy
make sure you add the appropriate exceptions for FirebaseUI resources (style-src
,media-src
,img-src
,script-src
, etc.) and underlying Firebase JS SDK.
When a user has enabled the private browsing mode in Safari, the web storage is disabled. This currently results in an error being thrown upon Firebase Auth initialization. Therefore, when following the snippets above, FirebaseUI will never get initialized and no UI will be displayed.
When re-rendering the FirebaseUI Auth widget (for instance after signing in a user, signing her out and trying to sign her in again), it will sometimes log a warning:
UI Widget is already rendered on the page and is pending some user interaction. Only one widget instance can be rendered per page. The previous instance has been automatically reset.
This happens when the UI widget was in a pending state, i.e. the user was in the
middle of performing a sign-in flow. You should generally avoid re-rendering the
widget in the middle of an action, but if you do, to avoid the warning, you
should use the reset()
method before re-rendering the widget.
When trying to initialize a new UI widget with the same Auth instance, you will
get an app/duplicate-app
error. In general, you should keep a reference to
the AuthUI instance and instead call reset()
and then start(...)
again to
re-render the widget.
If you don't keep a reference to that AuthUI instance, you can get the reference
by calling firebaseui.auth.AuthUI.getInstance(appId)
where appId
is the same
as the optional one used to initialize the AuthUI instance. If none was provided
just call firebaseui.auth.AuthUI.getInstance()
.
This is the recommended way but you also have the option to delete the AuthUI
instance by calling ui.delete()
which returns a promise that resolves on
successful deletion. You can then initialize a new UI instance with the same
Auth instance without getting the app/duplicate-app
error. At any time, you
can only have one AuthUI instance with the same appId
or the same Auth
instance.
FirebaseUI is broken in IE11 when deployed on a local server accessed through localhost
(but works when deployed on a remote server)
Several developers reported issues with IE11 when testing the widget integration on a server deployed locally, accessing the application through a localhost
address. However, it doesn't impact applications deployed on a server (as you can verify in the demo app).
Latest: https://github.com/firebase/firebaseui-web/releases/latest
For v1.0.0 and superior: https://github.com/firebase/firebaseui-web/releases
See the milestone 0.5.0 for the issues covered in this release. Below is a summary of the most important ones:
- FirebaseUI now supports Single Page Application: a
reset
method was added to allow to dispose of the widget. When the user leaves a page where the FirebaseUI widget was rendered (for instance in thecomponentWillUnmount
method of a React component), call thereset
method of thefirebaseui.auth.AuthUI
instance you created. Also, call thereset
method before rendering again the widget if one has already been rendered on the page. Please refer to the demo app for guidance on how to use FirebaseUI in a Single Page Application context. - Custom scopes can now be added for each provider. See Configure OAuth providers.
- Several issues, different but related to the
displayName
not being present after sign up with email and password, have been fixed. - A new config parameter has been added:
signInFlow
. It allows to specify whether the Identity Providers sign in flows should be done throughredirect
(the default) orpopup
. See Sign In Flows.