Authentication Changes (#6)

* Add auth file

Signed-off-by: PoojaB26 <[email protected]>

* Add assets & update CSS

* Add Authentication directories

* Add Firebase Setup changes

Signed-off-by: PoojaB26 <[email protected]>

* Add firebase related imgs

Signed-off-by: PoojaB26 <[email protected]>

* Add landscape style css

* Add Firestore + Billing setup info

* Add Google Auth (Firebase) docs

* Fix h3 CSS

* Script: Convert links to html tags

* Update Google Auth docs

* Add Email Auth

* Move Firebase Auth under How-Tos

* Move imgs to folder

* Add authentication approaches concept

* Add verification info

* Add anon auth how-tos

* Fix admonitions & formatting

* Shuffle the auth sections and address review comments

* Revert changes

* Add images for auth methods

* Rename file

* Fix slug

* Fix formatting issues

* Move supabase docs to correct folder

---------

Signed-off-by: PoojaB26 <[email protected]>

Author: PoojaB26

docs/Integrations/authentication/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Authentication",
+    "position": 1
+}

docs/Integrations/authentication/authentication-methods.md

@@ -0,0 +1,73 @@
+---
+title: Auth Methods
+sidebar_position: 1
+
+---
+
+# Authentication Methods Overview
+
+Authentication enables users to create accounts and log into your app, establishing a secure,
+verified connection. In the dynamic world of applications, users can authenticate using various
+methods, including **email login**, **OAuth**, and **phone authentication**, among others.
+
+While each method has its unique features and advantages, they all share a common goal: enhancing
+security and verifying the identity of users to provide a safe and personalized user experience.
+
+## Email Login Authentication
+
+The email login method involves users registering with an email address and
+password.
+
+Security in this approach is enhanced through **Email Verification**,
+where a link or code is sent to the user's email to confirm ownership. This step
+prevents unauthorized account creation and ensures that the user can recover
+their account and receive important communications.
+
+![email-login.png](imgs%2Femail-login.png)
+
+## OAuth (Open Authorization)
+
+**OAuth** is a popular authentication protocol that enables users to authorize
+one
+application to interact with another on their behalf without revealing their
+password. This method is commonly used to allow applications to access service
+features or user information from other services, such as logging into a
+third-party app using Google or Facebook credentials.
+
+By using OAuth, the user's
+login credentials stay secure with the original service provider, and only
+specific permissions are granted to third-party apps via access tokens. This
+approach minimizes the risk of exposing sensitive user data and streamlines the
+login process across various platforms.
+
+## Phone Authentication
+
+Another method is phone authentication, where a user's phone number is used as a
+form of identity verification. Upon registering or logging in, the user receives
+a text message with a verification code that must be entered to proceed. This
+method leverages the security of mobile networks and the uniqueness of phone
+numbers to ensure that the person attempting access is the legitimate owner of
+the account.
+
+![phone-login.png](imgs%2Fphone-login.png)
+
+## Anonymous Authentication
+
+Anonymous Authentication allows users to interact with your application without
+signing in with permanent credentials, by creating temporary anonymous accounts.
+This method is beneficial for users who want to test services before committing
+to creating an account. If a user decides to sign up later, their anonymous
+account can be upgraded to a regular account, preserving their data and
+interactions.
+
+Each anonymous session is typically isolated, with strict permissions to prevent
+access to sensitive features or user data. When upgrading to a full account,
+secure practices are used to link the anonymous data to the new authenticated
+profile, ensuring that no data leakage or unauthorized access occurs during the
+transition.
+
+Each authentication method aims to balance user convenience with high security,
+ensuring that personal and sensitive data remains protected while providing a
+seamless user experience. 
+
+![anon-user.png](imgs%2Fanon-user.png)

docs/Integrations/authentication/generated-code.md

@@ -0,0 +1,97 @@
+---
+sidebar_label: Generated Code
+---
+
+# Authentication: Generated Code
+
+In FlutterFlow, enabling Authentication is a very simple task. You can check the documentation for the same here but ideally it is just enabling Authentication in Settings, choose your Authentication Type and adding an Action to your desired Auth button. But behind the scenes, a lot of code generation happens to enable this function for you, lets go through it one by one. 
+
+We will first discuss the base authentication architecture and then discuss the code changes when we choose custom authentication vs Firebase/Supabase auth. 
+
+## File structure
+When we enable Authentication in the Settings dashboard, it creates the following folders in our file structure to manage custom authentication. 
+```
+lib/
+    auth/
+         custom_auth/
+              auth_util.dart
+              custom_auth_manager.dart
+              custom_auth_user_provider.dart
+```
+         
+Similarly, when we enable say Firebase authentication, the following files and folders are generated for you. 
+
+```
+lib/
+    auth/
+         firebase_auth/
+              auth_util.dart
+              email_auth.dart (along with other providers)
+              firebase_auth_manager.dart
+              firebase_user_provider.dart
+         auth_manager.dart
+         base_auth_user_provider.dart
+```
+
+:::info
+This documentation is exclusively focused on the generated code for Custom Authentication. For instructions on integrating custom authentication into your FlutterFlow app, please refer here.
+:::
+
+# Custom Auth Manager
+The most crucial component of our generated authentication system is the ``CustomAuthManager`` class. It is responsible for managing authentication session attributes such as the ``authenticationToken``, ``refreshToken``, ``tokenExpiration``, and user-specific attributes like `uid` and `userData`. 
+
+This class provides essential functionalities including:
+`signIn()`: Handles user sign-in processes. 
+
+`signOut()`: Manages user sign-out actions. 
+
+`updateAuthUserData()`: Updates authentication and user data. 
+
+`persistAuthData()`: Persists authentication data across sessions for persistent login capabilities.
+
+In addition to the `CustomAuthManager`, we have another important file in our authentication framework: `custom_auth_user_provider.dart. `
+
+This file defines a class, ``<ProjectName>AuthUser``, to encapsulate the state of an authenticated user. It leverages BehaviorSubject from the [rxdart](https://pub.dev/packages/rxdart) package to manage a stream of the user object, enabling real-time updates to the user's authentication state. This stream is initially set with a user object that indicates a logged-out state. Subsequent authentication actions will update this stream, enabling real-time adjustments to any part of the application that depends on the user's authentication status.
+
+Building on our authentication framework, the `custom_auth_manager.dart` file brings in the currentUser variable, an instance of the ``<ProjectName>AuthUser`` class. This global reference allows for quick and centralized access to the currently signed-in user's information, enabling access to their authentication state across the application. 
+
+The `loggedIn` property further simplifies verifying if a user is logged in by checking the currentUser's status.
+
+## Auth Manager Initialization
+Then, we have the auth_util file, which contains a singleton instance of `CustomAuthManager`
+
+```
+final _authManager = CustomAuthManager();
+CustomAuthManager get authManager => _authManager;
+```
+
+The `authManager.initialize()` is called in `main()` before runApp is executed. 
+
+The `initialize()` method creates an instance of SharedPreferences, preparing it for `authToken`, `refreshToken`, etc, and also handles the logic for token expiration, including the automatic logout when these tokens expire.
+
+:::info
+Also note that this initialization occurs only because the 'Persist Auth Sessions' option has been enabled in the Custom Authentication Settings.
+
+<img src="/img/persist-auth-session.png" alt="Alt text for the image" />
+
+:::
+
+This file also offers easy-to-use getters for essential information such as the user's ID, login token, and other data. This setup simplifies the process of accessing and managing login details throughout your app.
+
+## Log in Implementation
+When the Log In action is activated by tapping a button, we initiate a series of operations behind the scenes to ensure a smooth login process. 
+
+Upon calling the signIn method, it triggers the `_updateCurrentUser` method from `CustomAuthManager` internally. 
+
+This method receives various parameters such as `authenticationToken`, `refreshToken`, `tokenExpiration`, `authUid`, and `userData`, updating the CustomAuthManager class's properties with these details. Consequently, this stores the current session's authentication and user information effectively.
+
+:::info
+To learn more about the concepts of Authentication Token, Refresh Token, and Token Expiry Time, please refer the [Concepts](concepts/token) doc.
+:::
+
+A new user object, marked as logged in (`loggedIn` set to true), along with the provided `authUid` and `userData`, is then added to the user object stream mentioned earlier. This update informs all the stream's subscribers about the changed user state, signaling that the user has successfully logged in.
+
+Additionally, the `persistAuthData` method is invoked to save the updated authentication details (tokens, expiration, user ID, etc.) for future sessions.
+
+After signing in, `context.goNamedAuth('AuthPage', context.mounted);` is called that navigates the user to the Logged In Page specified in FlutterFlow's Authentication Settings.
+

docs/Integrations/authentication/imgs/add-app.gif

@@ -0,0 +1,4 @@
+{
+    "label": "Types",
+    "position": 2
+}

docs/Integrations/authentication/imgs/anon-auth.png

@@ -0,0 +1,46 @@
+---
+title: Authentication Types
+sidebar_position: 1
+---
+
+# Authentication Types
+FlutterFlow provides native support for a variety of Authentication Services, including **Firebase**, **Supabase**, and **Custom Authentication** options. To integrate these services into your app, simply navigate to 'App Settings,' select 'Authentication,' and then choose your preferred service. From there, you can set up initial pages for both entry and logged-in states. Follow any additional steps as necessary to complete the setup.
+
+## Firebase Authentication
+
+In FlutterFlow, you can seamlessly connect with **Firebase** and utilize the available authentication
+methods.
+
+Firebase Authentication integrates tightly with other Firebase services, leveraging industry
+standards like OAuth 2.0 and OpenID Connect. This makes it highly adaptable for use with your custom
+backend, ensuring a secure and scalable solution.
+
+:::info
+Learn how to enable Firebase Authentication and integrate popular auth providers in your FlutterFlow
+app. [Learn more here](#)
+:::
+
+## Supabase Authentication
+
+In FlutterFlow, you can also integrate Supabase to manage authentication efficiently.
+
+Supabase provides a powerful and flexible authentication solution, similar to Firebase but with some
+unique advantages like support for PostgreSQL.
+
+:::info
+Discover how to set up Supabase Authentication and link it with available auth providers within your
+FlutterFlow app. [Learn more here](#)
+:::
+
+## Custom Authentication
+
+In FlutterFlow, you have the flexibility to implement custom authentication solutions tailored to
+your specific needs. This allows for a highly personalized approach to security, enabling you to
+design and integrate authentication mechanisms that perfectly fit the unique requirements of your
+application. Whether you need to work with legacy systems or have specific security protocols,
+custom authentication provides the necessary control.
+
+:::info
+Explore how to implement custom authentication strategies in your FlutterFlow app, ensuring your
+authentication flow aligns with your business requirements. [Learn more here](#)
+:::

docs/Integrations/authentication/imgs/anon-user.png

@@ -0,0 +1,4 @@
+{
+    "label": "Custom Auth",
+    "position": 3
+}

docs/Integrations/authentication/imgs/create-account-action.png

@@ -0,0 +1,13 @@
+---
+title: custom-auth
+sidebar_position: 3
+---
+
+# Enabling custom authentication [TODO / Different PR]
+To enable custom authentication in FlutterFlow:
+- Open Setting and Integrations > App Settings > Authentication.
+- Turn on the **Enable Authentication** toggle and set Authentication Type to Custom.
+- To ensure that your users are directed to the appropriate pages based on their login status, you must set the initial pages.
+- By default, the **Persist Auth Sessions** option is enabled, which means users remain logged in until they actively log out. With this option enabled, your app will automatically open to the homepage whenever it's restarted.
+
+<iframe src="https://demo.arcade.software/pKfPIx8T6uEbds8xon1t?embed&show_copy_link=true" title="app.flutterflow.io/authentication" frameborder="0" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" width="100%" height="600"></iframe>

docs/Integrations/authentication/imgs/credential-page.png

@@ -0,0 +1,69 @@
+---
+id: auth-token
+sidebar_label: Tokens
+sidebar_position: 1
+---
+
+# Tokens: Types and Lifespans
+
+Before diving into **Authentication**, let's first clarify some key terms we'll encounter. These
+concepts are essential for understanding how secure access and user verification work.
+
+- **Authentication Token**: An Auth Token acts as a digital key provided to
+  client apps upon successful login. This key verifies the user's identity for subsequent actions
+  within the app, eliminating the need for repeated login prompts. It ensures secure and streamlined
+  access to the app's features.
+
+- **Refresh Token**: This token functions as a secondary mechanism to renew the
+  authentication token without requiring the user to re-enter login credentials. This is
+  particularly useful for maintaining a user's session securely, even when the primary
+  authentication token expires, enhancing both security and user experience.
+
+- **Token Expiry Time** : This refers to the lifespan of an authentication token.
+  It defines the period during which the token remains valid. This is a critical security measure to
+  prevent unauthorized access, ensuring that tokens are regularly refreshed and authenticated.
+
+Developers must save these values in the persisted app state to keep it secure.
+
+:::warning[Remember]
+Not all login APIs will return an Auth Token, Refresh Token, and Token Expiry Time. The details of
+the response depend on the configuration of your backend API. Always check your API documentation to
+understand what is returned upon successful authentication.
+:::
+
+<figure>
+    ![login-request.png](..%2F..%2Fimgs%2Flogin-request.png)
+  <figcaption class="centered-caption">1.1 An example of a Login API transaction that 
+returns the above values in its response</figcaption>
+</figure>
+
+### Example of Auth using Tokens
+
+For example, when a user logs in using a Login API, the server verifies the submitted credentials
+and typically responds with both an **Auth Token** and a **Refresh Token** (both strings). The
+authentication token is short-lived; for instance, it may be valid for 1 hour and is used to
+authenticate API requests (_as shown in diagram 1.1_).
+
+If you need to use the token, it is typically included in any authenticated API request, such as
+accessing a list of users available only to logged-in users. In this case, the app sends a request
+to the API with a header that includes an Authorization header containing the authentication token.
+
+<figure>
+    ![token-success-request.png](..%2F..%2Fimgs%2Ftoken-success-request.png)
+  <figcaption class="centered-caption">An example of an Authenticated API request that 
+sends a Authorization Bearer Token that uses the saved Auth Token</figcaption>
+</figure>
+
+After an hour, or as determined by the token's expiry time, the authentication token expires. Any
+attempt to access another post with the expired token will result in a 401 Unauthorized response.
+
+To retrieve a new token, a common practice involves the client app making a request to a specific
+endpoint, submitting the saved refresh token in the request body. The server then validates the
+refresh token and responds with a new authentication token.
+
+![token-fail-request.png](..%2F..%2Fimgs%2Ftoken-fail-request.png)
+
+Thanks to the refresh token, users can continue accessing the app without needing to log in again.
+This process enhances security by limiting the lifespan of each token while ensuring a seamless
+experience for the user.
+

docs/Integrations/authentication/imgs/email-login.png

@@ -0,0 +1,4 @@
+{
+    "label": "Firebase Auth",
+    "position": 2
+}

docs/Integrations/authentication/imgs/enable-auth-fr.png

@@ -0,0 +1,38 @@
+---
+title: Anonymous Login
+sidebar_position: 3
+---
+
+# Anonymous Login
+
+:::info[Prerequisites]
+
+Before getting started with this section, ensure you have:
+
+- Completed all steps in [**Firebase Setup**](..%2F..%2F..%2FFirebase%2FConnect%20to%20Firebase%20Setup.md).
+
+- Completed [**Initial Setup**](docs/Integrations/Authentication/How-Tos/Firebase-Auth/initial-setup.md)
+required for authentication.
+
+- Learn more about the concepts
+of [**Anonymous Authentication**](docs/Integrations/Authentication/Concepts/authentication-approaches.md)
+:::
+
+## Enable Anonymous Authentication in Firebase
+
+To enable Anonymous authentication, first go to your Firebase console and enable
+the authentication provider:
+
+<iframe src="https://demo.arcade.software/rzWEzk1DdYGG7V5AA8pd?embed&show_copy_link=true" title="EcommerceFlow - Authentication - Sign-in method - Firebase console" frameborder="0" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" width="100%" height="600"></iframe>
+
+## Add Anonymous Login Action
+
+1. On the button designated for anonymous authentication, add a new Action.
+
+2. Search for and select the **Log In** action (located under Backend/Database > Firebase
+   Authentication).
+
+3. Set the Auth Provider to **Anonymous**.
+
+4. Enable the **Create User Document** toggle and set the Collection to _users_. This action will
+   create an entry for the user in the database without any details upon successful login.

docs/Integrations/authentication/imgs/login-action.png

@@ -0,0 +1,6 @@
+---
+title: Apple Login
+sidebar_position: 4
+---
+
+# Apple Login