docs: Add Firebase IDP docs #395
Conversation
marcelomendoncasoares
left a comment
marcelomendoncasoares
left a comment
There was a problem hiding this comment.
Great work with the docs, @exaby73! Have a few suggestions for improvement mainly on the guide.
| ## Prerequisites | ||
|
|
||
| Before setting up Firebase authentication, ensure you have: | ||
|
|
||
| - A Firebase project (create one at [Firebase Console](https://console.firebase.google.com/)) | ||
| - Firebase CLI installed (`npm install -g firebase-tools`) | ||
| - FlutterFire CLI installed (`dart pub global activate flutterfire_cli`) | ||
| - At least one authentication method enabled in your Firebase project |
There was a problem hiding this comment.
Suggestion: Instead of a "Prerequisites" session, can we introduce each one along the way as steps on the guide? For example, the last one (having methods enabled) is already shown below, so it is not actually a prerequisite for the guide.
| ```yaml | ||
| development: | ||
| firebaseServiceAccountKey: | | ||
| { | ||
| "type": "service_account", | ||
| "project_id": "your-project-id", | ||
| "private_key_id": "...", | ||
| "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", | ||
| "client_email": "firebase-adminsdk-xxxxx@your-project-id.iam.gserviceaccount.com", | ||
| "client_id": "...", | ||
| "auth_uri": "https://accounts.google.com/o/oauth2/auth", | ||
| "token_uri": "https://oauth2.googleapis.com/token" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Suggestion: Can we add a similar example to the Google Sign-In setup guide? This is very good for users to visualize.
| ### Generate and Migrate | ||
|
|
||
| Run the following commands to generate client code and create the database migration: | ||
|
|
||
| ```bash | ||
| serverpod generate | ||
| ``` | ||
|
|
||
| Then create and apply the migration: | ||
|
|
||
| ```bash | ||
| serverpod create-migration | ||
| docker compose up --build --detach | ||
| dart run bin/main.dart --role maintenance --apply-migrations | ||
| ``` | ||
|
|
||
| More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). |
There was a problem hiding this comment.
Suggestion: Suppress this details and keep only the reference to the providers configuration, as we do on the other provider setup guides. This is intentional to avoid making specific guides more verbose with steps that users might already be familiar while also simplifying future evolution of the docs (like when introducing new migrations UX).
For consistency, I would suggest having the same wording we use on others:
| ### Generate and Migrate | |
| Run the following commands to generate client code and create the database migration: | |
| ```bash | |
| serverpod generate | |
| ``` | |
| Then create and apply the migration: | |
| ```bash | |
| serverpod create-migration | |
| docker compose up --build --detach | |
| dart run bin/main.dart --role maintenance --apply-migrations | |
| ``` | |
| More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). | |
| Finally, run `serverpod generate` to generate the client code and create a migration to initialize the database for the provider. More detailed instructions can be found in the general [identity providers setup section](../../setup#identity-providers-configuration). |
| ## Client-side configuration | ||
|
|
There was a problem hiding this comment.
Suggestion: Add a brief summary of the session here, like saying that we will use the official Firebase packages and that the below steps follow standard Firebase usage guide. If there is one, it is also worth referencing an official Firebase troubleshooting guide. Although this is slightly redundant with the general description of the setup, it is here that the information is useful, so it is worth repeating.
| 5. **Token is sent** to your server's `firebaseIdp.login()` endpoint | ||
| 6. **Server validates** the JWT using the service account credentials | ||
| 7. **Server creates or updates** the user account and issues a Serverpod session token | ||
| 8. **Client session is updated** and the user is authenticated with Serverpod |
There was a problem hiding this comment.
| 8. **Client session is updated** and the user is authenticated with Serverpod | |
| 8. **Client session is updated** and the user is authenticated with Serverpod in the Flutter app |
|
|
||
| Before setting up Firebase authentication, ensure you have: | ||
|
|
||
| - A Firebase project (create one at [Firebase Console](https://console.firebase.google.com/)) |
There was a problem hiding this comment.
Suggestion: Add ending dot to all entries on lists. This is a general suggestion for all lists (numbered or not) to make it more syntactically correct and consistent with other lists throughout the authentication docs. We usually have lists that are either an introductory stem (like this one) or a sequence of sentences, which both require punctuation.
| 8. **Client session is updated** and the user is authenticated with Serverpod | ||
|
|
||
| :::info | ||
| The `initializeFirebaseSignIn()` call in the client setup automatically signs out from Firebase when the user signs out from Serverpod, keeping both systems in sync. |
There was a problem hiding this comment.
Suggestion: The way I read this is that the call in itself will sign out (once), but not that it will keep monitoring changes. Just a small wording suggestion to make it clearer:
| The `initializeFirebaseSignIn()` call in the client setup automatically signs out from Firebase when the user signs out from Serverpod, keeping both systems in sync. | |
| The `initializeFirebaseSignIn()` call in the client setup will ensure that the user gets automatically signed out from Firebase when signing out from Serverpod to keep both systems in sync. |
| ## Present the authentication UI | ||
|
|
||
| ### Using FirebaseAuthController | ||
|
|
||
| The `FirebaseAuthController` handles syncing Firebase authentication state with your Serverpod backend. After a user signs in with Firebase, pass the Firebase user to the controller: | ||
|
|
||
| ```dart | ||
| import 'package:firebase_auth/firebase_auth.dart' as firebase_auth; | ||
| import 'package:serverpod_auth_idp_flutter_firebase/serverpod_auth_idp_flutter_firebase.dart'; | ||
|
|
||
| // Create the controller | ||
| final controller = FirebaseAuthController( | ||
| client: client, | ||
| onAuthenticated: () { | ||
| // User successfully synced with Serverpod | ||
| // NOTE: Do not navigate here - use client.auth.authInfoListenable instead | ||
| }, | ||
| onError: (error) { | ||
| ScaffoldMessenger.of(context).showSnackBar( | ||
| SnackBar(content: Text('Error: $error')), | ||
| ); | ||
| }, | ||
| ); | ||
|
|
||
| // After user signs in with Firebase | ||
| final firebaseUser = firebase_auth.FirebaseAuth.instance.currentUser; | ||
| if (firebaseUser != null) { | ||
| await controller.login(firebaseUser); | ||
| } | ||
| ``` | ||
|
|
||
| For details on building custom authentication UIs and integrating with `firebase_ui_auth`, see the [customizing the UI section](./customizing-the-ui). |
There was a problem hiding this comment.
Suggestion: This session is about Presenting the UI, but we are only showing how to use the controller. I suggest flipping the importance here: have the SignInScreen example directly here and showing more details of the controller in the other session. Because the goal of the guide is for the user to finish having the provider fully integrated and usable from the UI.
| # Customizing the UI | ||
|
|
||
| When using the Firebase identity provider, you build your authentication UI using Firebase's own packages (`firebase_auth` or `firebase_ui_auth`). The `FirebaseAuthController` handles syncing the authenticated Firebase user with your Serverpod backend. | ||
|
|
||
| :::info | ||
| Unlike other Serverpod identity providers, Firebase does not provide built-in sign-in widgets. You use Firebase's official packages for the UI, then sync the result with Serverpod using `FirebaseAuthController`. | ||
| ::: | ||
|
|
There was a problem hiding this comment.
Suggestion: Have a first sub-header here with a full example on how to use the SignInScreen beyond the one to be added in the Presenting the UI session of the setup guide.
2 participants
No description provided.