Add docs for the Web API mode

Author: rayluo

docs/app-vs-api.rst

@@ -1,18 +1,30 @@
 .. note::
 
-    Web Application (a.k.a. website) and Web API are different,
-    and are supported by different Identity components.
-    Make sure you are using the right component for your scenario.
+    Web Application (a.k.a. website) and Web API are different scenarios,
+    both supported by the same Identity Auth component with different decorators.
+    Make sure you are using the right decorator for your scenario.
 
-    +-------------------------+---------------------------------------------------+-------------------------------------------------------+
-    | Aspects                 | Web Application (a.k.a. website)                  | Web API                                               |
-    +=========================+===================================================+=======================================================+
-    | **Definition**          | A complete solution that users interact with      | A back-end system that provides data (typically in    |
-    |                         | directly through their browsers.                  | JSON format) to front-end or other system.            |
-    +-------------------------+---------------------------------------------------+-------------------------------------------------------+
-    | **Functionality**       | - Users interact with views (HTML user interfaces)| - Does not return views (in HTML); only provides data.|
-    |                         |   and data.                                       | - Other systems (clients) hit its endpoints.          |
-    |                         | - Users sign in and establish their sessions.     | - Clients presents a token to access your API.        |
-    |                         |                                                   | - Each request has no session. They are stateless.    |
-    +-------------------------+---------------------------------------------------+-------------------------------------------------------+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Aspects
+     - Web Application (a.k.a. website)
+     - Web API
+   * - **Definition**
+     - A complete solution that users interact with directly through their browsers.
+     - A back-end system that provides data (typically in JSON format) to front-end or other system.
+   * - **Functionality**
+     - | - Users interact with views (HTML user interfaces) and data.
+       | - Users sign in and establish their sessions.
+     - | - Does not return views (in HTML); only provides data.
+       | - Other systems (clients) hit its endpoints.
+       | - Clients presents a token to access your API.
+       | - Each request has no session. They are stateless.
+   * - **Identity component**
+     - Same ``Auth`` class
+     - Same ``Auth`` class
+   * - **Decorator to use**
+     - ``@auth.login_required``
+     - ``@auth.authorization_required``
 

docs/django-webapi.rst

@@ -45,7 +45,7 @@ Django Web API protected by an access token
 -------------------------------------------
 
 #. In your web project's ``views.py``, decorate some views with the
-   :py:func:`identity.django.ApiAuth.authorization_required` decorator::
+   :py:func:`identity.django.Auth.authorization_required` decorator::
 
     from django.conf import settings
 
@@ -69,7 +69,7 @@ All of the content above are demonstrated in
 API for Django web projects
 ---------------------------
 
-.. autoclass:: identity.django.ApiAuth
+.. autoclass:: identity.django.Auth
    :members:
    :inherited-members:
 

docs/flask-webapi.rst

@@ -15,15 +15,15 @@ Configuration
 
 #. Install dependency by ``pip install identity[flask]``
 
-#. Create an instance of the :py:class:`identity.Flask.ApiAuth` object,
+#. Create an instance of the :py:class:`identity.flask.Auth` object,
    and assign it to a global variable inside your ``app.py``::
 
     import os
     from flask import Flask
-    from identity.flask import ApiAuth
+    from identity.flask import Auth
 
     app = Flask(__name__)
-    auth = ApiAuth(
+    auth = Auth(
         client_id=os.getenv('CLIENT_ID'),
         ...=...,  # See below on how to feed in the authority url parameter
         )
@@ -35,7 +35,7 @@ Flask Web API protected by an access token
 ------------------------------------------
 
 #. In your web project's ``app.py``, decorate some views with the
-   :py:func:`identity.flask.ApiAuth.authorization_required` decorator.
+   :py:func:`identity.flask.Auth.authorization_required` decorator.
    It will automatically put validated token claims into the ``context`` dictionary,
    under the key ``claims``.
    or emit an HTTP 401 or 403 response if the token is missing or invalid.
@@ -59,7 +59,7 @@ All of the content above are demonstrated in
 API for Flask web API projects
 ------------------------------
 
-.. autoclass:: identity.flask.ApiAuth
+.. autoclass:: identity.flask.Auth
    :members:
    :inherited-members:
 

docs/index.rst

@@ -51,6 +51,7 @@ This Identity library is a Python authentication/authorization library that:
    flask
    flask-webapi
    quart
+   quart-webapi
    abc
    generic
 

docs/quart-webapi.rst

@@ -0,0 +1,67 @@
+Identity for a Quart Web API
+==============================
+
+.. include:: app-vs-api.rst
+
+Prerequisite
+------------
+
+Create `a hello world web project in Quart <https://quart.palletsprojects.com/en/latest/quick_start.html>`_.
+Here we assume the project's main file is named ``app.py``.
+
+
+Configuration
+-------------
+
+#. Install dependency by ``pip install identity[quart]``
+
+#. Create an instance of the :py:class:`identity.quart.Auth` object,
+   and assign it to a global variable inside your ``app.py``::
+
+    import os
+    from quart import Quart
+    from identity.quart import Auth
+
+    app = Quart(__name__)
+    auth = Auth(
+        client_id=os.getenv('CLIENT_ID'),
+        ...=...,  # See below on how to feed in the authority url parameter
+        )
+
+   .. include:: auth.rst
+
+
+Quart Web API protected by an access token
+------------------------------------------
+
+#. In your web project's ``app.py``, decorate some views with the
+   :py:func:`identity.quart.Auth.authorization_required` decorator.
+   It will automatically put validated token claims into the ``context`` dictionary,
+   under the key ``claims``.
+   or emit an HTTP 401 or 403 response if the token is missing or invalid.
+
+   ::
+
+    @app.route("/")
+    @auth.authorization_required(expected_scopes={
+        "your_scope_1": "api://your_client_id/your_scope_1",
+        "your_scope_2": "api://your_client_id/your_scope_2",
+    })
+    async def index(*, context):
+        claims = context['claims']
+        # The user is uniquely identified by claims['sub'] or claims["oid"],
+        # claims['tid'] and/or claims['iss'].
+        return {"message": f"Data for {claims['sub']}@{claims['tid']}"}
+
+All of the content above follows the same pattern as
+`Flask web API sample <https://github.com/Azure-Samples/ms-identity-python-webapi-flask>`_
+but uses async/await syntax for Quart.
+
+API for Quart web API projects
+------------------------------
+
+.. autoclass:: identity.quart.Auth
+   :members:
+   :inherited-members:
+
+   .. automethod:: __init__