docs: update authentication guide

Author: AsifArmanRahman

docs/guide/authentication.rst

@@ -1,136 +1,277 @@
 Authentication
 ==============
 
-The ``sign_in_with_email_and_password()`` method returns user
-data, including a token you can use to adhere to security rules.
-
+The authentication service allows you to signup, login,
+edit profile, apply security to the data you might store
+in either :ref:`Database<guide/database:Database>` or
+:ref:`Storage<guide/storage:Storage>`, and of course delete
+your account.
 
 .. code-block:: python
 
    # Get a reference to the auth service
    auth = firebaseApp.auth()
+..
 
-   # Log the user in
-   user = auth.sign_in_with_email_and_password(email, password)
-
-   # Log the user in anonymously
-   user = auth.sign_in_anonymous()
+   .. note::
+      All sign in methods return user data, including a token
+      you can use to adhere the security rules.
 
-   # Add user info
-   user = auth.update_profile(display_name, photo_url, delete_attribute)
 
-   # Get user info
-   user = auth.get_account_info()
+create_user_with_email_and_password
+-----------------------------------
 
-   # Get a reference to the database service
-   db = firebaseApp.database()
+Users can create an account using their
+email address and choice of password.
 
-   # data to save
-   data = {
-       "name": "Mortimer 'Morty' Smith"
-   }
+.. code-block:: python
 
-   # Pass the user's idToken to the push method
-   results = db.child("users").push(data, user['idToken'])
+   # Creating an account
+   auth.create_user_with_email_and_password(email, password)
 ..
 
+   .. note::
+      Make sure you have the Email/Password provider enabled in your
+      Firebase dashboard under Authentication -> Sign In Method.
 
 
-Token expiry
-------------
+sign_in_with_email_and_password
+-------------------------------
 
+User can login using their email and password, provided they
+:ref:`created an account<guide/authentication:create_user_with_email_and_password>`
+first.
 
 .. code-block:: python
 
+   # Log the user in
    user = auth.sign_in_with_email_and_password(email, password)
-   # before the 1 hour expiry:
-   user = auth.refresh(user['refreshToken'])
-   # now we have a fresh token
-   user['idToken']
 ..
 
 
-Custom tokens
--------------
+create_custom_token
+-------------------
 
-You can also create users using `custom
-tokens <https://firebase.google.com/docs/auth/server/create-custom-tokens>`__,
-for example:
+| You can also create users using `custom tokens`_,
+| For example:
 
 .. code-block:: python
 
+   # Create custom token
    token = auth.create_custom_token("your_custom_id")
 ..
 
 You can also pass in additional claims.
 
 .. code-block:: python
 
+   # Create custom token with claims
    token_with_additional_claims = auth.create_custom_token("your_custom_id", {"premium_account": True})
 ..
 
-You can then send these tokens to the client to sign in, or sign in as
-the user on the server.
+   .. note::
+      You need admin credentials (Service Account Key) to create 
+      custom tokens.
+
+.. _custom tokens:
+   https://firebase.google.com/docs/auth/server/create-custom-tokens
+
+
+sign_in_with_custom_token
+-------------------------
+
+You can send these custom tokens to the client to
+sign in, or sign in as the user on the server.
 
 .. code-block:: python
 
+   # log in user using custom token
    user = auth.sign_in_with_custom_token(token)
 ..
 
+sign_in_anonymous
+-----------------
+
+Allows users (who haven't signed up yet) to
+use your app without creating an account.
+
+
+.. code-block:: python
+
+   # Log the user in anonymously
+   user = auth.sign_in_anonymous()
+..
+
+   .. note:: 
+      Make sure you have the **Anonymous** provider enabled in your
+      Firebase dashboard under Authentication -> Sign In Method.
 
 
-Manage Users
-------------
+create_authentication_uri
+-------------------------
 
+Signing in with social providers is done through two steps. First step
+one is done via redirecting user to the providers' login page using
+:ref:`create_authentication_uri<guide/authentication:create_authentication_uri>`
+which is can be used dynamically for all providers.
 
-Creating users
-^^^^^^^^^^^^^^
+
+   .. warning::
+      At the moment only sign is via **Google** is supported, other
+      ones might break or work.
+
+The method returns an link to redirect user to providers' sign in page.
+Once the user signs into their account, user is asked for permissions
+and when granted, are redirect to the uri set while creating
+**OAuth Client IDs**, with authorization code to which can be further
+used to generate tokens to sign in with social providers in
+:ref:`second step<guide/authentication:sign_in_with_oauth_credential>`.
 
 .. code-block:: python
 
-   auth.create_user_with_email_and_password(email, password)
+   # Get a reference to the auth service with provider secret set
+   auth = firebaseApp.auth(client_secret='client-secret-file.json')
 ..
 
-   .. note::
-      Make sure you have the Email/password provider enabled in your
+.. code-block:: python
+
+   # Example usage with Flask
+   @auth.route('/login/google')
+   def login_google():
+      return redirect(auth.create_authentication_uri('google.com'))
+
+..
+
+   .. note:: 
+      Make sure you have the **social** provider enabled in your
       Firebase dashboard under Authentication -> Sign In Method.
 
-Verifying emails
-^^^^^^^^^^^^^^^^
+authenticate_login_with_google
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method is actually an reference to
+:ref:`create_authentication_uri<guide/authentication:create_authentication_uri>`
+with **Google** preset as the provider to use.
+
 
 .. code-block:: python
 
-   auth.send_email_verification(user['idToken'])
+   # Example usage with Flask
+   @auth.route('/login/google')
+   def login_google():
+      return redirect(auth.authenticate_login_with_google())
 ..
 
-Sending password reset emails
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   .. note:: 
+      Make sure you have the **Google Sign In** provider enabled in
+      your Firebase dashboard under Authentication -> Sign In Method.
+
+
+sign_in_with_oauth_credential
+-----------------------------
+
+Second step to sign in using social provider is to pass the URL
+(containing multiple params) that the user is redirected to, into this
+method. This method auto generates the tokens using params from that
+URL, then signs the user in using those tokens to Firebase linking the
+specific provider.
+
 
 .. code-block:: python
 
-   auth.send_password_reset_email("email")
+   # Here https://example.com/oauth2callback/ is the redirect URI
+   # that was set while creating OAuth Client ID
+
+   # Example usage with Flask
+   @auth.route('/oauth2callback/')
+   def oauth2callback():
+
+      user = auth.sign_in_with_oauth_credential(request.url)
+
+	   return jsonify(**user)
+
+
+get_account_info
+----------------
+
+This method returns an detailed version of the user's data associated
+with Authentication service.
+
+.. code-block:: python
+
+   # User account info
+   user_info = auth.get_account_info(user['idToken'])
 ..
 
-Get account information
-^^^^^^^^^^^^^^^^^^^^^^^
+
+update_profile
+--------------
+
+Update stored information or add information into the user's account.
 
 .. code-block:: python
 
-   auth.get_account_info(user['idToken'])
+   # Update user's name
+   auth.update_profile(user['idToken'], display_name='Iron Man')
+
+   # update user's profile picture
+   auth.update_profile(user['idToken'], photo_url='https://i.pinimg.com/originals/c0/37/2f/c0372feb0069e6289eb938b219e0b0a1.jpg')
 ..
 
-Refreshing tokens
-^^^^^^^^^^^^^^^^^
+
+refresh
+-------
+
+Firebase Auth Tokens are granted when an user logs in, and are
+associated with an expiration time of an hour generally, after
+that they lose validation and a new set of Tokens are needed,
+and they can be obtained by passing the ``refreshToken`` key
+from the users' tokens, received when logged in.
 
 .. code-block:: python
 
+   # before the 1 hour expiry:
    user = auth.refresh(user['refreshToken'])
+
+   # now we have a fresh token
+   user['idToken']
 ..
 
-Delete account
-^^^^^^^^^^^^^^
+
+delete_user_account
+-------------------
+
+In case any user want to delete their account, it can be done by
+passing ``idToken`` key from the users' tokens, received when logged
+in.
 
 .. code-block:: python
 
    auth.delete_user_account(user['idToken'])
 ..
+
+
+send_password_reset_email
+-------------------------
+
+In case any user forgot his password, it is possible to send
+them email containing an code or link to reset their password.
+
+.. code-block:: python
+
+   auth.send_password_reset_email(email)
+..
+
+
+send_email_verification
+-----------------------
+
+To ensure the email address belongs to the user who created the
+account, it is recommended to request verification of the email.
+Verification code/link can be sent to the user by passing ``idToken``
+key from the users' tokens, to this method.
+
+.. code-block:: python
+
+   auth.send_email_verification(user['idToken'])
+..