Rewrite Quick Tutorial narrative in authentication.rst for consistent flow

1 files changed, 23 insertions, 19 deletions

diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst
index c28958b33..892beb3ec 100644
--- a/docs/quick_tutorial/authentication.rst
+++ b/docs/quick_tutorial/authentication.rst
@@ -1,7 +1,7 @@
 .. _qtut_authentication:
 
 ==============================
-20: Logins With Authentication
+20: Logins with authentication
 ==============================
 
 Login views that authenticate a username and password against a list of users.
@@ -35,13 +35,14 @@ Steps
 
     $ cd ..; cp -r view_classes authentication; cd authentication
 
-#. This step depends on bcrypt_, so add it as a dependency in
-   ``authentication/setup.py``:
+#. Add ``bcrypt`` as a dependency in ``authentication/setup.py``:
 
    .. literalinclude:: authentication/setup.py
+    :language: python
+    :emphasize-lines: 5-6
     :linenos:
 
-#. Now we can activate the development-mode distribution:
+#. We can now install our project in development mode:
 
    .. code-block:: bash
 
@@ -107,23 +108,32 @@ Unlike many web frameworks, Pyramid includes a built-in but optional security
 model for authentication and authorization. This security system is intended to
 be flexible and support many needs. In this security model, authentication (who
 are you) and authorization (what are you allowed to do) are not just pluggable,
-but de-coupled. To learn one step at a time, we provide a system that
-identifies users and lets them log out.
+but decoupled. To learn one step at a time, we provide a system that identifies
+users and lets them log out.
 
 In this example we chose to use the bundled :ref:`AuthTktAuthenticationPolicy
 <authentication_module>` policy. We enabled it in our configuration and
 provided a ticket-signing secret in our INI file.
 
-The function ``hash_password`` hashes user's password by bcrypt_ instead of
-storing password in plain text directly as a best practice [1]_. And function
-``check_password`` will compare the hashed value of the submitted password
-against the hashed value of the user's password.
-
 Our view class grew a login view. When you reached it via a ``GET`` request, it
 returned a login form. When reached via ``POST``, it processed the submitted
 username and password against the "groupfinder" callable that we registered in
 the configuration.
 
+The function ``hash_password`` uses a one-way hashing algorithm with a salt on
+the user's password via ``bcrypt``, instead of storing the password in plain
+text. This is considered to be a "best practice" for security.
+
+.. note::
+    There are alternative libraries to ``bcrypt`` if it is an issue on your
+    system. Just make sure that the library uses an algorithm approved for
+    storing passwords securely.
+
+The function ``check_password`` will compare the two hashed values of the
+submitted password and the user's password stored in the database. If the
+hashed values are equivalent, then the user is authenticated, else
+authentication fails.
+
 In our template, we fetched the ``logged_in`` value from the view class. We use
 this to calculate the logged-in user, if any. In the template we can then
 choose to show a login link to anonymous visitors or a logout link to logged-in
@@ -141,11 +151,5 @@ Extra credit
    request? Use ``import pdb; pdb.set_trace()`` to answer this.
 
 .. seealso:: See also :ref:`security_chapter`,
-   :ref:`AuthTktAuthenticationPolicy <authentication_module>`.
-
-.. _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.
+   :ref:`AuthTktAuthenticationPolicy <authentication_module>`, `bcrypt
+   <https://pypi.python.org/pypi/bcrypt>`_