Custom User Ids for User Restricted Resource Access.

The feature now supports custom User Ids, allowing for more flexibility
and token revocation with token-based authentication.

- 'AUTH_USERNAME_FIELD' renamed to 'AUTH_FIELD'
- 'auth_username_field' renamed to 'auth_field'
- BasicAuth and subclasses now support the user_id property

This change breaks backward compatibility. If you want to preserve the
old 'AUTH_USERNAME_FIELD' behavior, just set 'self.user_id' to
'username'.

Closes pyeve#73.

Author: nicolaiarocci

CHANGES

@@ -8,6 +8,11 @@ Version 0.0.9
 
 Not released yet.
 
+- Custom user ids for User-Restricted Resource Access, allowing for more
+  flexibility and token revocation with token-based authentication. Closes #73.
+- ``AUTH_USERNAME_FIELD`` renamed to ``AUTH_FIELD``.
+- ``auth_username_field`` renamed to ``auth_field``.
+- BasicAuth and subclasses now support ``user_id`` property.
 - Updated the event hooks naming system to be more robuts and consistent.
   Closes #80.
 - To emphasize the fact that they are tied to a method, all ``on_<method>``

docs/authentication.rst

@@ -393,21 +393,60 @@ unless they are made explicitly public.
 
 User-Restricted Resource Access
 -------------------------------
-When this feature is enabled, authorized users can only read/update/delete
-items created by themselves. 
+When this feature is enabled, each stored document is associated with the
+account that created it. This allows the API to transparently serve only
+account-created documents on all kind of requests: read, edit, delete and of
+course create.  User autentication needs to be enabled for this to work
+properly.
+
+At global level this feature is enabled by setting ``AUTH_FIELD`` and locally
+(at endpoint level) by setting ``auth_field``. These properties define the name
+of the field used to store the id of the user who created the document.  So for
+example by setting ``AUTH_FIELD`` to ``user_id``, you are effectively (and
+trasparently to the user) adding a ``user_id`` field to every stored
+document. This will then be used to retrieve/edit/delete documents stored by
+the user. 
+
+But how do you set the ``auth_field`` value? By simply setting it in your
+custom class. Let us revise our BCrypt-authentication example from above:
+
+.. code-block:: python
+   :emphasize-lines: 25-27
 
-What actually happens behind the scenes is that the value of
-`Authorization.username` request header is automatically added to new documents
-stored by the API. A filter on the same header is also transparently applied to
-all read, edit and delete requests. 
+    # -*- coding: utf-8 -*-
+
+    """
+        Auth-BCrypt
+        ~~~~~~~~~~~
+
+        Securing an Eve-powered API with Basic Authentication (RFC2617).
 
-``AUTH_USERNAME_FIELD`` defines the  name of the database field used to store
-the `Authorization.username` header. ``auth_username_field`` is the
-resource-level equivalent, which allows to effectively override the global
-setting, if present.  
+        You will need to install py-bcrypt: ``pip install py-bcrypt``
 
-This feature can be used with both :ref:`basic` and :ref:`token` as they both
-rely on the `Authorization.username` field. 
+        This snippet by Nicola Iarocci can be used freely for anything you like.
+        Consider it public domain.
+    """
+
+    import bcrypt
+    from eve import Eve
+    from eve.auth import BasicAuth
+
+
+    class BCryptAuth(BasicAuth):
+        def check_auth(self, username, password, allowed_roles, resource):
+            # use Eve's own db driver; no additional connections/resources are used
+            accounts = app.data.driver.db['accounts']
+            account = accounts.find_one({'username': username})
+            # set 'auth_field' value to the account's ObjectId 
+            # (instead of _Id, you might want to use ID_FIELD)
+            self.user_id = account['_Id']
+            return account and \
+                bcrypt.hashpw(password, account['password']) == account['password']
+
+
+    if __name__ == '__main__':
+        app = Eve(auth=BCryptAuth)
+        app.run()
 
 .. admonition:: Please note
 

docs/config.rst

@@ -227,14 +227,14 @@ uppercase.
                                 present. Can and most likely will be overriden 
                                 when configuring single resource endpoints.
 
-``AUTH_USERNAME_FIELD``         Enables :ref:`user-restricted`. When the
+``AUTH_FIELD``                  Enables :ref:`user-restricted`. When the
                                 feature is enabled users can only
                                 read/update/delete resource items created by
                                 themselves. The keyword contains the actual
-                                name of the field used to store the username of
+                                name of the field used to store the id of
                                 the user who created the resource item. Can be
                                 overwritten by resource settings. Defaults to
-                                ``''``, which disables the feature. 
+                                ``None``, which disables the feature. 
 
 ``ALLOW_UNKNOWN``               When ``True`` this option will allow insertion
                                 and edition of arbitrary, unknown fields to
@@ -461,13 +461,13 @@ always lowercase.
                                 collections. See `Advanced Datasource
                                 Patterns`_. 
 
-``auth_username_field``         Enables :ref:`user-restricted`. When the
+``auth_field``                  Enables :ref:`user-restricted`. When the
                                 feature is enabled users can only
                                 read/update/delete resource items created by
                                 themselves. The keyword contains the actual
-                                name of the field used to store the username of
+                                name of the field used to store the id of
                                 the user who created the resource item. Locally
-                                overrides ``AUTH_USERNAME_FIELD``.
+                                overrides ``AUTH_FIELD``. 
 
 ``allow_unknown``               When ``True`` this option will allow insertion
                                 and edition of arbitrary, unknown fields to

docs/tutorials/account_management.rst

@@ -253,15 +253,52 @@ associated with the account that created it. This allows the API to transparentl
 serve only account-created documents on all kind of requests: read, edit, delete
 and of course create.
 
-The only thing that we need to do is configure the name of the field that will
-be used to store the owner of the document. It can be done at a global level
-(all endpoints will use the same field) and/or at endpoint level (see feature
-documentation for details). Let's just set the global field name in our
-settings file:
+There are only two things that we need to do in order to activate this feature:
+
+    1. configure the name of the field that will be used to store the owner of the
+    document
+    2. set the document owner on each incoming POST request.
+
+
+Since we want to enable this feature for all of our API endpoints we'll just
+update our ``settings.py`` file by setting a proper ``AUTH_FIELD`` value:
+
+::
+
+    # Name of the field used to store the owner of each document
+    AUTH_FIELD = 'user_id'
+
+
+Then, we want to update our authentication class to properly update the field's
+value:
 
 .. code-block:: python
+   :emphasize-lines: 15-17
+   
 
-    AUTH_USERNAME_FIELD: 'username'
+    from eve import Eve
+    from eve.auth import BasicAuth
+    from werkzeug.security import check_password_hash
+
+
+    class RolesAuth(BasicAuth):
+        def check_auth(self, username, password, allowed_roles, resource):
+            # use Eve's own db driver; no additional connections/resources are used
+            accounts = app.data.driver.db['accounts']
+            lookup = {'username': username}
+            if allowed_roles:
+                # only retrieve a user if his roles match ``allowed_roles``
+                lookup['roles'] = {'$in': allowed_roles}
+            account = accounts.find_one(lookup)
+            # set 'AUTH_FIELD' value to the account's ObjectId 
+            # (instead of _Id, you might want to use ID_FIELD)
+            self.user_id = account['_id']
+            return account and check_password_hash(account['password'], password)
+
+
+    if __name__ == '__main__':
+        app = Eve(auth=RolesAuth)
+        app.run()
 
 This is all we need to do. Now, when a user hits the, say, ``/invoices/``
 endpoint with a GET request, he will only be served with the invoices created
@@ -483,19 +520,9 @@ methods. See :ref:`auth` for more details.
 6. Only allowing access to account resources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This is achieved with the :ref:`user-restricted` feature, as seen in
-:ref:`accounts_basic`. Update the settings file with the following global
-setting (or use the local ``auth_username_field`` if you only want to enable
-the feature on selected endpoints):
-
-.. code-block:: python
-
-    AUTH_USERNAME_FIELD: 'token'
-
-Stored documents will be associated with their account token. When a user hits
-the, say, ``/invoices/`` endpoint with a GET request, he will only be served
-with the invoices created by his own token. The same will happen with DELETE
-and PATCH, making it impossible for an authenticated user to accidentally
-retrieve, edit or delete other people data.
+:ref:`accounts_basic`. You might want to store the user token as your
+``AUTH_FIELD`` value, but if you want user tokens to be easily revocable, then
+your best option is to use the account unique id for this.
 
 Basic vs Token: Final Considerations
 ------------------------------------
@@ -505,10 +532,4 @@ stored on the client and  being sent over the wire with every request. If
 you're sending your tokens out-of-band, and you're on SSL/TLS, that's quite
 a lot of additional security. 
 
-If you are using the :ref:`user-restricted` feature then a second and not
-irrelevant advantage is that, since you are just storing tokens with documents,
-when the user will eventually change his/her username no maintenance will be
-needed, as the token itself won't change. With Basic Authentication, since we
-would be storing usernames with documents, we'd be forced to update them all.
-
 .. _SSL/TLS: http://en.wikipedia.org/wiki/Transport_Layer_Security

eve/auth.py

@@ -48,11 +48,17 @@ class BasicAuth(object):
     """ Implements Basic AUTH logic. Should be subclassed to implement custom
     authorization checking.
 
+    .. versionchanged:: 0.0.9
+       Support for user_id property.
+
     .. versionchanged:: 0.0.7
        Support for 'resource' argument.
 
     .. versionadded:: 0.0.4
     """
+    def __init__(self):
+        self.user_id = None
+
     def check_auth(self, username, password, allowed_roles, resource):
         """ This function is called to check if a username / password
         combination is valid. Must be overridden with custom logic.

eve/default_settings.py

@@ -12,6 +12,8 @@
     :license: BSD, see LICENSE for more details.
 
     .. versionchanged:: 0.0.9
+       'AUTH_USERNAME_FIELD' renamed to 'AUTH_FIELD', and default value set to
+       None.
        'DATE_FORMAT now using GMT instead of UTC.
 
     .. versionchanged:: 0.0.7
@@ -67,7 +69,7 @@
 EXTRA_RESPONSE_FIELDS = []
 
 
-AUTH_USERNAME_FIELD = ''        # user-restricted resource access is disabled
+AUTH_FIELD = None               # user-restricted resource access is disabled
                                 # by default.
 
 ALLOW_UNKNOWN = False           # don't allow unknown key/value pairs for

eve/flaskapp.py

@@ -287,6 +287,7 @@ def set_defaults(self):
         or global configuration settings.
 
         .. versionchanged:: 0.0.9
+           'auth_username_field' renamed to 'auth_field'.
            Always include automatic fields despite of datasource projections.
 
         .. versionchanged:: 0.0.8
@@ -348,8 +349,8 @@ def set_defaults(self):
             else:
                 item_methods = eve.ITEM_METHODS
             settings.setdefault('item_methods', item_methods)
-            settings.setdefault('auth_username_field',
-                                self.config['AUTH_USERNAME_FIELD'])
+            settings.setdefault('auth_field',
+                                self.config['AUTH_FIELD'])
             settings.setdefault('allow_unknown', self.config['ALLOW_UNKNOWN'])
             settings.setdefault('extra_response_fields',
                                 self.config['EXTRA_RESPONSE_FIELDS'])

eve/io/base.py

@@ -157,7 +157,9 @@ def _datasource_ex(self, resource, query=None, client_projection=None):
         to which an API resource refers to
 
         .. versionchanged:: 0.0.9
-           support for Python 3.3.
+           Storing self.app.auth.userid in auth_field when 'user-restricted
+           resource access' is enabled.
+           Support for Python 3.3.
 
         .. versionchanged:: 0.0.6
            'auth_username_field' is injected even in empty queries.
@@ -199,11 +201,11 @@ def _datasource_ex(self, resource, query=None, client_projection=None):
             request.endpoint == 'item_endpoint' and request.method
             not in config.DOMAIN[resource]['public_item_methods']
         ):
-
             # if 'user-restricted resource access' is enabled and there's an
             # Auth request active, add the username field to the query
-            username_field = config.DOMAIN[resource].get('auth_username_field')
-            if username_field and request.authorization and query is not None:
-                query.update({username_field: request.authorization.username})
+            auth_field = config.DOMAIN[resource].get('auth_field')
+            if auth_field and self.app.auth.user_id:
+                if request.authorization and query is not None:
+                    query.update({auth_field: self.app.auth.user_id})
 
         return datasource, query, fields

eve/methods/post.py

@@ -46,6 +46,10 @@ def post(resource, payl=None):
        renamed to 'on_insert'.
        You can now pass a pre-defined custom payload to the funcion.
 
+    .. versionchanged:: 0.0.9
+       Storing self.app.auth.userid in auth_field when 'user-restricted
+       resource access' is enabled.
+
     .. versionchanged: 0.0.7
        Support for Rate-Limiting.
        Support for 'extra_response_fields'.
@@ -100,9 +104,11 @@ def post(resource, payl=None):
 
                 # if 'user-restricted resource access' is enabled and there's
                 # an Auth request active, inject the username into the document
-                username_field = resource_def['auth_username_field']
-                if username_field and request.authorization:
-                    document[username_field] = request.authorization.username
+                auth_field = resource_def['auth_field']
+                if auth_field:
+                    userid = app.auth.user_id
+                    if userid and request.authorization:
+                        document[auth_field] = userid
 
             else:
                 # validation errors added to list of document issues

eve/tests/auth.py

@@ -9,6 +9,7 @@
 
 class ValidBasicAuth(BasicAuth):
     def check_auth(self, username, password, allowed_roles, resource):
+        self.user_id = 123
         return username == 'admin' and password == 'secret' and  \
             (allowed_roles == ['admin'] if allowed_roles else True)
 
@@ -237,7 +238,7 @@ def setUp(self):
         self.test_client = self.app.test_client()
         self.valid_auth = [('Authorization', 'Basic YWRtaW46c2VjcmV0')]
         self.invalid_auth = [('Authorization', 'Basic IDontThinkSo')]
-        self.field_name = 'auth_username_field'
+        self.field_name = 'auth_field'
         self.data = {'item1': json.dumps({"ref": "0123456789123456789012345"})}
         for resource, settings in self.app.config['DOMAIN'].items():
             settings[self.field_name] = 'username'