Merge pull request #2849 from mfrlin/issue-2656

Changed wiki tutorial to showcase passwrd hashing with bcrypt.

1 files changed, 42 insertions, 1 deletions

diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst
index 44097b35b..523acc53b 100644
--- a/docs/tutorials/wiki/authorization.rst
+++ b/docs/tutorials/wiki/authorization.rst
@@ -18,6 +18,7 @@ require permission, instead of a default "403 Forbidden" page.
 
 We will implement the access control with the following steps:
 
+* Add password hashing dependencies
 * Add users and groups (``security.py``, a new module).
 * Add an :term:`ACL` (``models.py``).
 * Add an :term:`authentication policy` and an :term:`authorization policy`
@@ -38,6 +39,25 @@ Then we will add the login and logout feature:
 Access control
 --------------
 
+Add dependencies
+~~~~~~~~~~~~~~~~
+
+Just like in :ref:`wiki_defining_views` we need a new dependency.
+We need to add the ``bcrypt`` [1]_ package, to our tutorial package's
+``setup.py`` file by assigning this dependency to the ``requires`` parameter
+in the ``setup()`` function.
+
+Open ``setup.py`` and edit it to look like the following:
+
+.. literalinclude:: src/authorization/setup.py
+   :linenos:
+   :emphasize-lines: 21
+   :language: python
+
+Only the highlighted line needs to be added.
+
+Do not forget to run ``pip install -e .`` just like in :ref:`wiki-running-pip-install`.
+
 Add users and groups
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -61,7 +81,20 @@ request)`` returns ``None``.  We will use ``groupfinder()`` as an
 :term:`authentication policy` "callback" that will provide the
 :term:`principal` or principals for a user.
 
-In a production system, user and group data will most often come from a
+There are two helper methods that will help us later to authenticate users.
+The first is ``hash_password`` which takes a raw password and transforms it using
+bcrypt_ into an irreversible representation, a process known as "hashing". The
+second method, ``check_password``, will allow us to compare the hashed value of the
+submitted password against the hashed value of the password stored in the user's
+record. If the two hashed values match, then the submitted
+password is valid, and we can authenticate the user.
+
+We hash passwords so that it is impossible to decrypt and use them to
+authenticate in the application. If we stored passwords foolishly in clear text,
+then anyone with access to the database could retrieve any password to authenticate
+as any user.
+
+In a production system, user and group data will most often be saved and come from a
 database, but here we use "dummy" data to represent user and groups sources.
 
 Add an ACL
@@ -370,3 +403,11 @@ following URLs, checking that the result is as expected:
   the login form with the ``editor`` credentials), we'll see a Logout link in
   the upper right hand corner.  When we click it, we're logged out, and
   redirected back to the front page.
+
+
+.. _bcrypt: https://pypi.python.org/pypi/bcrypt
+
+.. [1] We are using the bcrypt_ package from PyPI to hash our passwords
+       securely. There are other one-way hash algorithms for passwords if
+       bcrypt is an issue on your system. Just make sure that it's an
+       algorithm approved for storing passwords versus a generic one-way hash.