Skip to content

Commit 8879519

Browse files
kevinthecheungkevinthecheung
authored
docs(firebase_auth): Add content from firebase.google.com (#8214)
1 parent 7181d53 commit 8879519

11 files changed

+1073
-31
lines changed

‎docs/auth/account-linking.mdx

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Link Multiple Auth Providers to an Account
3+
sidebar_label: Link Accounts
4+
---
5+
6+
You can allow users to sign in to your app using multiple authentication
7+
providers by linking auth provider credentials to an existing user account.
8+
Users are identifiable by the same Firebase user ID regardless of the
9+
authentication provider they used to sign in. For example, a user who signed in
10+
with a password can link a Google account and sign in with either method in the
11+
future. Or, an anonymous user can link a Facebook account and then, later, sign
12+
in with Facebook to continue using your app.
13+
14+
## Before you begin
15+
16+
Add support for two or more authentication providers (possibly including
17+
anonymous authentication) to your app.
18+
19+
## Link auth provider credentials to a user account
20+
21+
To link auth provider credentials to an existing user account:
22+
23+
1. Sign in the user using any authentication provider or method.
24+
25+
1. Complete the sign-in flow for the new authentication provider up to, but not
26+
including, calling one of the `signInWith`- methods. For example, get
27+
the user's Google ID token, Facebook access token, or email and password.
28+
29+
1. Get a `Credential` object for the new authentication provider:
30+
31+
```dart
32+
// Google Sign-in
33+
final credential = GoogleAuthProvider.credential(idToken: idToken);
34+
35+
// Email and password sign-in
36+
final credential =
37+
EmailAuthProvider.credential(email: emailAddress, password: password);
38+
39+
// Etc.
40+
```
41+
42+
1. Pass the `Credential` object to the sign-in user's `linkWithCredential()`
43+
method:
44+
45+
```dart
46+
try {
47+
final userCredential = await FirebaseAuth.instance.currentUser
48+
?.linkWithCredential(credential);
49+
} on FirebaseAuthException catch (e) {
50+
switch (e.code) {
51+
case "provider-already-linked":
52+
print("The provider has already been linked to the user.");
53+
break;
54+
case "invalid-credential":
55+
print("The provider's credential is not valid.");
56+
break;
57+
case "credential-already-in-use":
58+
print("The account corresponding to the credential already exists, "
59+
"or is already linked to a Firebase User.");
60+
break;
61+
// See the API reference for the full list of error codes.
62+
default:
63+
print("Unknown error.");
64+
}
65+
```
66+
67+
If the call to `linkWithCredential()` succeeds, the user can now sign in using
68+
any linked authentication provider and access the same Firebase data.
69+
70+
## Unlink an auth provider from a user account
71+
72+
You can unlink an auth provider from an account, so that the user can no
73+
longer sign in with that provider.
74+
75+
To unlink an auth provider from a user account, pass the provider ID to the
76+
`unlink()` method. You can get the provider IDs of the auth providers linked to
77+
a user from the `User` object's `providerData` property.
78+
79+
```dart
80+
try {
81+
await FirebaseAuth.instance.currentUser?.unlink(providerId);
82+
} on FirebaseAuthException catch (e) {
83+
switch (e.code) {
84+
case "no-such-provider":
85+
print("The user isn't linked to the provider or the provider "
86+
"doesn't exist.");
87+
break;
88+
default:
89+
print("Unkown error.");
90+
}
91+
}
92+
```

‎docs/auth/anonymous-auth.mdx

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Authenticate with Firebase Anonymously
3+
sidebar_label: Anonymous Auth
4+
---
5+
6+
You can use Firebase Authentication to create and use temporary anonymous accounts
7+
to authenticate with Firebase. These temporary anonymous accounts can be used to
8+
allow users who haven't yet signed up to your app to work with data protected
9+
by security rules. If an anonymous user decides to sign up to your app, you can
10+
[link their sign-in credentials](account-linking) to the anonymous account so
11+
that they can continue to work with their protected data in future sessions.
12+
13+
## Before you begin
14+
15+
1. If you haven't already, follow the steps in the [Get started](start) guide.
16+
17+
1. Enable Anonymous sign-in:
18+
19+
- In the Firebase console's **Authentication** section, open the
20+
[Sign in method](https://console.firebase.google.com/project/_/authentication/providers)
21+
page.
22+
- From the **Sign in method** page, enable the **Anonymous sign-in**
23+
method and click **Save**.
24+
25+
## Authenticate with Firebase anonymously
26+
27+
When a signed-out user uses an app feature that requires authentication with
28+
Firebase, sign in the user anonymously by calling `signInAnonymously()`:
29+
30+
```dart
31+
try {
32+
final userCredential =
33+
await FirebaseAuth.instance.signInAnonymously();
34+
print("Signed in with temporary account.");
35+
} on FirebaseAuthException catch (e) {
36+
switch (e.code) {
37+
case "operation-not-allowed":
38+
print("Anonymous auth hasn't been enabled for this project.");
39+
break;
40+
default:
41+
print("Unkown error.");
42+
}
43+
}
44+
```
45+
46+
:::note
47+
To protect your project from abuse, Firebase limits the number of new
48+
email/password and anonymous sign-ups that your application can have from the
49+
same IP address in a short period of time. You can request and schedule
50+
temporary changes to this quota from the
51+
[Firebase console](https://console.firebase.google.com/project/_/authentication/providers).
52+
:::
53+
54+
## Convert an anonymous account to a permanent account
55+
56+
When an anonymous user signs up to your app, you might want to allow them to
57+
continue their work with their new account—for example, you might want to
58+
make the items the user added to their shopping cart before they signed up
59+
available in their new account's shopping cart. To do so, complete the following
60+
steps:
61+
62+
1. When the user signs up, complete the sign-in flow for the user's
63+
authentication provider up to, but not including, calling one of the
64+
`signInWith`- methods. For example, get the user's Google ID token,
65+
Facebook access token, or email address and password.
66+
67+
1. Get a `Credential` object for the new authentication provider:
68+
69+
```dart
70+
// Google Sign-in
71+
final credential = GoogleAuthProvider.credential(idToken: idToken);
72+
73+
// Email and password sign-in
74+
final credential =
75+
EmailAuthProvider.credential(email: emailAddress, password: password);
76+
77+
// Etc.
78+
```
79+
80+
1. Pass the `Credential` object to the sign-in user's `linkWithCredential()`
81+
method:
82+
83+
```dart
84+
try {
85+
final userCredential = await FirebaseAuth.instance.currentUser
86+
?.linkWithCredential(credential);
87+
} on FirebaseAuthException catch (e) {
88+
switch (e.code) {
89+
case "provider-already-linked":
90+
print("The provider has already been linked to the user.");
91+
break;
92+
case "invalid-credential":
93+
print("The provider's credential is not valid.");
94+
break;
95+
case "credential-already-in-use":
96+
print("The account corresponding to the credential already exists, "
97+
"or is already linked to a Firebase User.");
98+
break;
99+
// See the API reference for the full list of error codes.
100+
default:
101+
print("Unknown error.");
102+
}
103+
```
104+
105+
If the call to `linkWithCredential()` succeeds, the user's new account can
106+
access the anonymous account's Firebase data.
107+
108+
:::note
109+
This technique can also be used to [link any two accounts](account-linking).
110+
:::
111+
112+
113+
## Next steps
114+
115+
After a user creates a new account, this account is stored as part of your
116+
Firebase project, and can be used to identify a user across every app in your
117+
project, regardless of what sign-in method the user used.
118+
119+
In your apps, you can get the user's basic profile information from the
120+
`User` object. See [Manage Users](manage-users).
121+
122+
In your Firebase Realtime Database and Cloud Storage Security Rules, you can
123+
get the signed-in user's unique user ID from the `auth` variable, and use it to
124+
control what data a user can access.
125+
126+
You can allow users to sign in to your app using multiple authentication
127+
providers by [linking auth provider credentials](account-linking)) to an
128+
existing user account.
129+
130+
To sign out a user, call `signOut()`:
131+
132+
```dart
133+
await FirebaseAuth.instance.signOut();
134+
```

‎docs/auth/custom-auth.mdx

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Authenticate with Firebase Using a Custom Authentication System
3+
sidebar_label: Custom Auth
4+
---
5+
6+
You can integrate Firebase Authentication with a custom authentication system by
7+
modifying your authentication server to produce custom signed tokens when a user
8+
successfully signs in. Your app receives this token and uses it to authenticate
9+
with Firebase.
10+
11+
## Before you begin
12+
13+
1. If you haven't already, follow the steps in the [Get started](start) guide.
14+
1. [Install and configure the Firebase Admin SDK](https://firebase.google.com/docs/admin/setup).
15+
Be sure to [initialize the SDK](https://firebase.google.com/docs/admin/setup#initialize-sdk)
16+
with the correct credentials for your Firebase project.
17+
18+
## Authenticate with Firebase
19+
20+
1. When users sign in to your app, send their sign-in credentials (for
21+
example, their username and password) to your authentication server. Your
22+
server checks the credentials and, if they are valid,
23+
[creates a custom Firebase token](https://firebase.google.com/docs/auth/admin/create-custom-tokens)
24+
and sends the token back to your app.
25+
26+
1. After you receive the custom token from your authentication server, pass it
27+
to `signInWithCustomToken()` to sign in the user:
28+
29+
```dart
30+
try {
31+
final userCredential =
32+
await FirebaseAuth.instance.signInWithCustomToken(token);
33+
print("Sign-in successful.");
34+
} on FirebaseAuthException catch (e) {
35+
switch (e.code) {
36+
case "invalid-custom-token":
37+
print("The supplied token is not a Firebase custom auth token.");
38+
break;
39+
case "custom-token-mismatch":
40+
print("The supplied token is for a different Firebase project.");
41+
break;
42+
default:
43+
print("Unkown error.");
44+
}
45+
}
46+
```
47+
48+
## Next steps
49+
50+
After a user creates a new account, this account is stored as part of your
51+
Firebase project, and can be used to identify a user across every app in your
52+
project, regardless of what sign-in method the user used.
53+
54+
In your apps, you can get the user's basic profile information from the
55+
`User` object. See [Manage Users](manage-users).
56+
57+
In your Firebase Realtime Database and Cloud Storage Security Rules, you can
58+
get the signed-in user's unique user ID from the `auth` variable, and use it to
59+
control what data a user can access.
60+
61+
You can allow users to sign in to your app using multiple authentication
62+
providers by [linking auth provider credentials](account-linking)) to an
63+
existing user account.
64+
65+
To sign out a user, call `signOut()`:
66+
67+
```dart
68+
await FirebaseAuth.instance.signOut();
69+
```

0 commit comments

Comments
 (0)