Added option to use api_token parameter to supply API key, improved...

Added option to use api_token parameter to supply API key, improved documentation of all authentication service pluggable modules.

lib/hawat/blueprints/auth_api/__init__.py

@@ -10,28 +10,47 @@
 
 """
 Description
------------
+--------------------------------------------------------------------------------
 
-This pluggable module provides default authentication service for API endpoints.
-After this module is enabled, users may pregenerated API tokens/keys to authenticate
-themselves when accessing various API application endpoints.
+This pluggable module provides API key based authentication service. When this
+module is enabled, users may generate and use API keys to authenticate themselves
+when accessing various API application endpoints.
 
 Currently the API key may be provided via one of the following methods:
 
 * The ``Authorization`` HTTP header.
 
   You may provide your API key by adding ``Authorization`` HTTP header to your
-  requests. Following two forms are accepted::
+  requests. Following forms are accepted::
 
     Authorization: abcd1234
+    Authorization: key abcd1234
     Authorization: token abcd1234
 
-* The ``api_key`` parameter of the HTTP ``POST`` request.
+* The ``api_key`` or ``api_token`` parameter of the HTTP ``POST`` request.
 
-  You may provide your API key as additional HTTP parameter ``api_key`` of your
-  ``POST`` request to particular application endpoint. Using ``GET`` requests is
-  forbidden due to the fact that request URLs are getting logged on various places
-  and your keys could thus be easily compromised.
+  You may provide your API key as additional HTTP parameter ``api_key`` or
+  ``api_token`` of your ``POST`` request to particular application endpoint.
+  Using ``GET`` requests is forbidden due to the fact that request URLs are getting
+  logged on various places and your keys could thus be easily compromised.
+
+
+Provided endpoints
+--------------------------------------------------------------------------------
+
+``/auth_api/<user_id>/key-generate``
+    Page enabling generation of new API key.
+
+    * *Authentication:* login required
+    * *Authorization:* ``admin``
+    * *Methods:* ``GET``, ``POST``
+
+``/auth_api/<user_id>/key-delete``
+    Page enabling deletion of existing API key.
+
+    * *Authentication:* login required
+    * *Authorization:* ``admin``
+    * *Methods:* ``GET``, ``POST``
 """
 
 
@@ -140,7 +159,7 @@ class GenerateKeyView(HTMLMixin, SQLAlchemyMixin, ItemChangeView):  # pylint: di
 
 class DeleteKeyView(HTMLMixin, SQLAlchemyMixin, ItemChangeView):  # pylint: disable=locally-disabled,too-many-ancestors
     """
-    View for deleting existing user accounts.
+    View for deleting API keys from user accounts.
     """
     methods = ['GET','POST']
 
@@ -212,15 +231,15 @@ class DeleteKeyView(HTMLMixin, SQLAlchemyMixin, ItemChangeView):  # pylint: disa
 #-------------------------------------------------------------------------------
 
 
-class AuthBlueprint(HawatBlueprint):
+class APIAuthBlueprint(HawatBlueprint):
     """
-    Hawat pluggable module - environment based authentication.
+    Hawat pluggable module - API key based authentication (*auth_api*).
     """
 
     @classmethod
     def get_module_title(cls):
         """*Implementation* of :py:func:`hawat.base.HawatBlueprint.get_module_title`."""
-        return gettext('Hawat API authentication service pluggable module')
+        return gettext('API key authentication service')
 
     def register_app(self, app):
         """
@@ -243,25 +262,28 @@ class AuthBlueprint(HawatBlueprint):
             https://flask-login.readthedocs.io/en/latest/#custom-login-using-request-loader
             """
 
-            # Attempt to extract token from Authorization header. Two formats may
-            # be used:
+            # Attempt to extract token from Authorization header. Following formats
+            # may be used:
             #   Authorization: abcd1234
+            #   Authorization: key abcd1234
             #   Authorization: token abcd1234
             api_key = request.headers.get("Authorization")
             if api_key:
                 vals = api_key.split()
                 if len(vals) == 1:
                     api_key = vals[0]
-                elif len(vals) == 2 and vals[0] == "token":
+                elif len(vals) == 2 and vals[0] in ("token", "key"):
                     api_key = vals[1]
                 else:
                     api_key = None
-            # API key may also be received via POST method, parameter 'api_key'.
-            # The GET method is forbidden due to the lack of security, there is
-            # a possiblity for it to be stored in various insecure places like web
-            # server logs.
+            # API key may also be received via POST method, parameters 'api_key'
+            # or 'api_token'. The GET method is forbidden due to the lack
+            # of security, there is a possiblity for it to be stored in various
+            # insecure places like web server logs.
             if not api_key:
                 api_key = request.form.get('api_key')
+            if not api_key:
+                api_key = request.form.get('api_token')
 
             # Now login the user with provided API key.
             if api_key:
@@ -307,7 +329,7 @@ def get_blueprint():
     instance of :py:class:`hawat.base.HawatBlueprint` or :py:class:`flask.Blueprint`.
     """
 
-    hbp = AuthBlueprint(
+    hbp = APIAuthBlueprint(
         BLUEPRINT_NAME,
         __name__,
         template_folder = 'templates',

lib/hawat/blueprints/auth_dev/__init__.py

@@ -10,7 +10,7 @@
 
 """
 Description
------------
+--------------------------------------------------------------------------------
 
 This Hawat pluggable module provides special authentication method, that is
 particularly usable for developers and enables them to impersonate any user.
@@ -31,7 +31,7 @@ default in *development* environment.
 
 
 Provided endpoints
-------------------
+--------------------------------------------------------------------------------
 
 ``/auth_dev/login``
     Page providing special developer login form.
@@ -194,7 +194,7 @@ class DevAuthBlueprint(HawatBlueprint):
     @classmethod
     def get_module_title(cls):
         """*Implementation* of :py:func:`hawat.base.HawatBlueprint.get_module_title`."""
-        return gettext('Hawat developer authentication service pluggable module')
+        return gettext('Developer authentication service')
 
     def register_app(self, app):
         """

lib/hawat/blueprints/auth_env/__init__.py

@@ -10,7 +10,7 @@
 
 """
 Description
------------
+--------------------------------------------------------------------------------
 
 This pluggable module provides default authentication service based on server
 environment. In this case the burden of performing actual authentication is
@@ -27,7 +27,7 @@ email about the fact new account was just created.
 
 
 Environment variables
----------------------
+--------------------------------------------------------------------------------
 
 Currently following environment variables set up by the HTTP server are supported:
 
@@ -57,7 +57,7 @@ Currently following environment variables set up by the HTTP server are supporte
 
 
 Provided endpoints
-------------------
+--------------------------------------------------------------------------------
 
 ``/auth_env/login``
     Page providing login functionality via server set environment variables.
@@ -490,13 +490,13 @@ class RegisterView(HTMLMixin, SQLAlchemyMixin, RenderableView):
 
 class EnvAuthBlueprint(HawatBlueprint):
     """
-    Hawat pluggable module - environment based authentication.
+    Hawat pluggable module - environment based authentication (*auth_env*).
     """
 
     @classmethod
     def get_module_title(cls):
         """*Implementation* of :py:func:`hawat.base.HawatBlueprint.get_module_title`."""
-        return gettext('Hawat environment authentication service pluggable module')
+        return gettext('Environment authentication service')
 
     def register_app(self, app):
         """

lib/hawat/blueprints/auth_pwd/__init__.py

@@ -10,14 +10,14 @@
 
 """
 Description
------------
+--------------------------------------------------------------------------------
 
 This pluggable module provides classical web login form with password authentication
 method.
 
 
 Provided endpoints
-------------------
+--------------------------------------------------------------------------------
 
 ``/auth_pwd/login``
     Page providing classical web login form.
@@ -215,7 +215,7 @@ class PwdAuthBlueprint(HawatBlueprint):
     @classmethod
     def get_module_title(cls):
         """*Implementation* of :py:func:`hawat.base.HawatBlueprint.get_module_title`."""
-        return gettext('Hawat password authentication service pluggable module')
+        return gettext('Password authentication service')
 
     def register_app(self, app):
         """