Skip to content

Commit 8d969bb

Browse files
author
Thomas Cesare-Herriau
committed
Initial version of the README
Change-Id: I8827718f50a16a2122a8b60a7f5436820f0bf72a
1 parent 95d3a28 commit 8d969bb

File tree

1 file changed

+336
-0
lines changed

1 file changed

+336
-0
lines changed

‎README.md‎

Lines changed: 336 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,336 @@
1+
# FirebaseUI for Web — Auth
2+
3+
FirebaseUI is an open-source JavaScript library for Web that provides simple, customizable UI
4+
bindings on top of [Firebase](https://firebase.google.com) SDKs to eliminate boilerplate code and
5+
promote best practices.
6+
7+
FirebaseUI Auth provides a drop-in auth solution that handles the UI flows for signing in users with
8+
email addresses and passwords, and Identity Provider Sign In using Google, Facebook and others.
9+
It is built on top of [Firebase Auth](https://firebase.google.com/docs/auth).
10+
11+
The FirebaseUI component implements best practices for authentication on mobile devices and
12+
websites, helping to sign-in and sign-up conversion for your app. It also handles cases like account
13+
recovery and account linking that can be security sensitive and error-prone to handle.
14+
15+
FirebaseUI Auth clients are also available for
16+
[iOS](https://github.com/firebase/firebaseui-ios/tree/master/auth) and
17+
[Android](https://github.com/firebase/firebaseui-android/tree/master/auth).
18+
19+
## Table of Contents
20+
21+
1. [Installation](#installation)
22+
2. [Usage instructions](#using-firebaseui-for-authentication)
23+
3. [Configuration](#configuration)
24+
4. [Customization](#customizing-firebaseui-for-authentication)
25+
5. [Advanced](#advanced)
26+
27+
## Installation
28+
29+
You just need to include the following code in the `<head>` tag of your page:
30+
31+
```html
32+
<script src="https://www.gstatic.com/firebasejs/live/3.0/firebase-app.js"></script>
33+
<script src="https://www.gstatic.com/firebasejs/live/3.0/firebase-auth.js"></script>
34+
<script src="https://www.gstatic.com/firebasejs/live/3.0/ui/firebase-ui-auth.js"></script>
35+
<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/firebasejs/live/3.0/ui/firebase-ui-auth.css" />
36+
```
37+
38+
## Using FirebaseUI for Authentication
39+
40+
FirebaseUI includes the following flows:
41+
1. Interaction with Identity Providers such as Google and Facebook
42+
2. Sign-up and sign-in with email accounts
43+
3. Password reset
44+
4. Prevention of account duplication (activated when *"One account per email adress"* setting is
45+
enabled in the [Firebase console](https://console.firebase.google.com). This setting is enabled by
46+
default.)
47+
5. [Account Chooser](https://www.accountchooser.com/learnmore.html?lang=en) for remembering emails
48+
49+
### Configuring sign-in providers
50+
51+
To use FirebaseUI to authenticate users you first need to configure each provider you want to use in
52+
their own developer app settings. Please read the *Before you begin* section of Firebase
53+
Authentication at the following links:
54+
55+
- [Email and password](https://firebase.google.com/docs/auth/web/password-auth#before_you_begin)
56+
- [Google](https://firebase.google.com/docs/auth/web/google-signin#before_you_begin)
57+
- [Facebook](https://firebase.google.com/docs/auth/web/facebook-login#before_you_begin)
58+
- [Twitter](https://firebase.google.com/docs/auth/web/twitter-login#before_you_begin)
59+
- [Github](https://firebase.google.com/docs/auth/web/github-auth#before_you_begin)
60+
61+
### Starting the sign-in flow
62+
63+
You first need to initialize your
64+
[Firebase app](https://firebase.google.com/docs/web/setup#prerequisites). The `firebase.auth.Auth`
65+
instance should be passed to the constructor of `firebaseui.auth.AuthUI`. You can then call the
66+
`start` method with the CSS selector that determines where to create the widget, and a configuration
67+
object.
68+
69+
The following example shows how to set up a sign-in screen with all supported providers.
70+
71+
```html
72+
<!DOCTYPE html>
73+
<html>
74+
<head>
75+
<meta charset="UTF-8">
76+
<title>Sample FirebaseUI App</title>
77+
<script src="firebase-app.js"></script>
78+
<script src="firebase-auth.js"></script>
79+
<script src="firebase-ui-auth.js"></script>
80+
<script type="text/javascript">
81+
// Firebase config.
82+
var config = {
83+
'authDomain': '<your-firebase-project-domain>.firebaseapp.com',
84+
'apiKey': '<your-API-key>',
85+
};
86+
87+
// FirebaseUI config.
88+
var uiConfig = {
89+
'signInSuccessUrl': '<url-to-redirect-to-on-success>',
90+
'signInOptions': [
91+
firebase.auth.GoogleAuthProvider.PROVIDER_ID,
92+
firebase.auth.FacebookAuthProvider.PROVIDER_ID,
93+
firebase.auth.TwitterAuthProvider.PROVIDER_ID,
94+
firebase.auth.GithubAuthProvider.PROVIDER_ID,
95+
firebase.auth.EmailAuthProvider.PROVIDER_ID
96+
],
97+
// Terms of service url.
98+
'tosUrl': '<your-tos-url>',
99+
};
100+
101+
102+
// Initialize the FirebaseUI Widget using Firebase.
103+
var app = firebase.initializeApp(config);
104+
var auth = app.auth();
105+
var ui = new firebaseui.auth.AuthUI(auth);
106+
// The start method will wait until the DOM is loaded.
107+
ui.start('#firebaseui-auth-container', uiConfig);
108+
</script>
109+
<link type="text/css" rel="stylesheet" href="firebase-ui-auth.css" />
110+
</head>
111+
<body>
112+
<!-- The surrounding HTML is left untouched by FirebaseUI.
113+
Your app may use that space for branding, controls and other customizations.-->
114+
<h1>Welcome to My Awesome App</h1>
115+
<div id="firebaseui-auth-container"></div>
116+
</body>
117+
</html>
118+
```
119+
120+
Here is how you would track the Auth state across all your pages:
121+
122+
```html
123+
<!DOCTYPE html>
124+
<html>
125+
<head>
126+
<meta charset="UTF-8">
127+
<title>Sample FirebaseUI App</title>
128+
<script src="firebase-app.js"></script>
129+
<script src="firebase-auth.js"></script>
130+
<script type="text/javascript">
131+
// Firebase config.
132+
var config = {
133+
'authDomain': '<your-firebase-project-domain>.firebaseapp.com',
134+
'apiKey': '<your-API-key>',
135+
};
136+
137+
// Instantiates the Firebase Auth instance.
138+
var app = firebase.initializeApp(config);
139+
var auth = app.auth();
140+
141+
initApp = function() {
142+
auth.onAuthStateChanged(function(user) {
143+
if (user) {
144+
// User is signed in.
145+
var displayName = user.displayName;
146+
var email = user.email;
147+
var emailVerified = user.emailVerified;
148+
var photoURL = user.photoURL;
149+
var uid = user.uid;
150+
var providerData = user.providerData;
151+
user.getToken().then(function(accessToken) {
152+
document.getElementById('quickstart-sign-in-status').textContent = 'Signed in';
153+
document.getElementById('quickstart-sign-in').textContent = 'Sign out';
154+
document.getElementById('quickstart-account-details').textContent = JSON.stringify({
155+
displayName: displayName,
156+
email: email,
157+
emailVerified: emailVerified,
158+
photoURL: photoURL,
159+
uid: uid,
160+
accessToken: accessToken,
161+
providerData: providerData
162+
}, null, ' ');
163+
});
164+
} else {
165+
// User is signed out.
166+
document.getElementById('quickstart-sign-in-status').textContent = 'Signed out';
167+
document.getElementById('quickstart-sign-in').textContent = 'Sign in';
168+
document.getElementById('quickstart-account-details').textContent = 'null';
169+
}
170+
}, function(error) {
171+
console.log(error);
172+
});
173+
};
174+
175+
window.onload = function() {
176+
initApp()
177+
};
178+
</script>
179+
</head>
180+
<body>
181+
<h1>Welcome to My Awesome App</h1>
182+
<div id="quickstart-sign-in-status"></div>
183+
<div id="quickstart-sign-in"></div>
184+
<div id="quickstart-account-details"></div>
185+
</body>
186+
</html>
187+
188+
```
189+
190+
## Configuration
191+
192+
FirebaseUI supports the following configuration parameters.
193+
194+
|Name |Required|Default |Description |
195+
|---------------------------------|--------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
196+
|callbacks |No |`[]` |A list of developers [callbacks](#available-callbacks) after specific events. |
197+
|queryParameterForSignInSuccessUrl|No |`"signInSuccessUrl"`|The redirect URL parameter name for the sign-in success URL. See [Overwriting the sign-in success URL](#overwriting-the-sign-in-success-url). |
198+
|queryParameterForWidgetMode |No |`"mode"` |The redirect URL parameter name for the “mode” of the Widget. See [FirebaseUI widget modes](#firebaseui-widget-modes). |
199+
|signInOptions |Yes |- |The list of [providers](#available-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.|
200+
|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`. |
201+
|tosUrl |Yes |- |The URL of the Terms of Service page. |
202+
203+
### Available providers
204+
205+
|Provider |Value |
206+
|------------------|------------------------------------------------|
207+
|Google |`firebase.auth.GoogleAuthProvider.PROVIDER_ID` |
208+
|Facebook |`firebase.auth.FacebookAuthProvider.PROVIDER_ID`|
209+
|Twitter |`firebase.auth.TwitterAuthProvider.PROVIDER_ID` |
210+
|Github |`firebase.auth.GithubAuthProvider.PROVIDER_ID` |
211+
|Email and password|`firebase.auth.EmailAuthProvider.PROVIDER_ID` |
212+
213+
### Available callbacks
214+
215+
Currently only one callback is supported. Some will be added soon to monitor UI changes.
216+
217+
#### `signInSuccess(currentUser: !firebase.User, credential : ?firebase.auth.AuthCredential, redirectUrl : ?string):boolean`
218+
219+
- `currentUser`: The logged in user.
220+
- `credential`: Optional. The credential used to sign in the user.
221+
- `redirectUrl`: Optional. The URL where the user is redirected after the callback finishes. It will only be given if you [overwrite the sign-in success URL](#overwriting-the-sign-in-success-url).
222+
223+
If the callback returns true, then the page is automatically redirected depending on the case:
224+
225+
- If no `signInSuccessUrl` parameter was given in the URL (See:
226+
[Overwriting the sign-in success URL](#overwriting-the-sign-in-success-url)) then the default
227+
`signInSuccessUrl` in config is used.
228+
- If the value is provided in the URL, that value will be used instead of the static
229+
`signInSuccessUrl` in config.
230+
231+
If the callback returns false or nothing, the page is not automatically redirected.
232+
233+
234+
### Example with all parameters used
235+
236+
```html
237+
<!DOCTYPE html>
238+
<html>
239+
<head>
240+
<meta charset="UTF-8">
241+
<title>Sample FirebaseUI App</title>
242+
<script src="firebase-app.js"></script>
243+
<script src="firebase-auth.js"></script>
244+
<script src="firebase-ui-auth.js"></script>
245+
<script type="text/javascript">
246+
// Firebase config.
247+
var config = {
248+
'authDomain': '<your-firebase-project-domain>.firebaseapp.com',
249+
'apiKey': '<your-API-key>',
250+
};
251+
252+
// FirebaseUI config.
253+
var uiConfig = {
254+
// Query parameter name for mode.
255+
'queryParameterForWidgetMode': 'mode',
256+
// Query parameter name for sign in success url.
257+
'queryParameterForSignInSuccessUrl': 'signInSuccessUrl',
258+
'signInSuccessUrl': '<url-to-redirect-to-on-success>',
259+
'signInOptions': [
260+
firebase.auth.GoogleAuthProvider.PROVIDER_ID,
261+
firebase.auth.FacebookAuthProvider.PROVIDER_ID,
262+
firebase.auth.TwitterAuthProvider.PROVIDER_ID,
263+
firebase.auth.EmailAuthProvider.PROVIDER_ID
264+
],
265+
// Terms of service url.
266+
'tosUrl': '<your-tos-url>',
267+
'callbacks': {
268+
'signInSuccess': function(currentUser, credential, redirectUrl) {
269+
// Do something.
270+
// Return type determines whether we continue the redirect automatically
271+
// or whether we leave that to developer to handle.
272+
return true;
273+
}
274+
}
275+
};
276+
277+
278+
// Initialize the FirebaseUI Widget using Firebase.
279+
var app = firebase.initializeApp(config);
280+
var auth = app.auth();
281+
var ui = new firebaseui.auth.AuthUI(auth);
282+
// The start method will wait until the DOM is loaded.
283+
ui.start('#firebaseui-auth-container', uiConfig);
284+
</script>
285+
<link type="text/css" rel="stylesheet" href="firebase-ui-auth.css" />
286+
</head>
287+
<body>
288+
<!-- The surrounding HTML is left untouched by FirebaseUI.
289+
Your app may use that space for branding, controls and other customizations.-->
290+
<h1>Welcome to My Awesome App</h1>
291+
<div id="firebaseui-auth-container"></div>
292+
</body>
293+
</html>
294+
```
295+
296+
## Customizing FirebaseUI for authentication
297+
298+
Currently, FirebaseUI does not offer customization out of the box. However, the HTML around the
299+
widget is not affected by it so you can display everything you want around the widget container.
300+
301+
## Advanced
302+
303+
### FirebaseUI widget modes
304+
305+
Upon initilization, FirebaseUI will look for the `mode` parameter in the URL. Depending on the value
306+
of this parameter, it will trigger a specific mode. When no `mode` parameter is found, it will
307+
default to the sign-in mode.
308+
309+
You can change the name of this parameter with the `queryParameterForWidgetMode` configuration
310+
parameter.
311+
312+
|Query parameter value|Description |
313+
|---------------------|------------|
314+
|`?mode=select` |Sign-in mode|
315+
316+
**Example:**
317+
318+
https://<url-of-the-widget>?mode=select
319+
320+
### Overwriting the sign-in success URL
321+
322+
You can pass a query parameter to the widget's URL that will overwrite the URL the user is
323+
redirected to after a successful sign-in. If you do so, you must set the configuration
324+
`signInSuccessUrl` value (even if it will be overwritten). When passing the redirect URL this way,
325+
the `signInSuccess` callback will receive the value as the `redirectUrl` argument.
326+
327+
You **must include the mode explicitly** in the URL when using the `signInSuccessUrl` parameter,
328+
otherwise FirebaseUI will directly redirect to the URL specified.
329+
330+
You can change the name of this parameter with the `queryParameterForSignInSuccessUrl` configuration
331+
parameter.
332+
333+
**Example:**
334+
335+
`https://<url-of-the-widget>?mode=select&signInSuccessUrl=signedIn.html` will redirect the user to
336+
`https://<url-of-the-widget>/signedIn.html` after a successful sign-in flow.

0 commit comments

Comments
 (0)