path: root/docs/tutorials/wiki2/authentication.rst

.. _wiki2_adding_authentication:

=====================
Adding authentication
=====================

:app:`Pyramid` provides facilities for :term:`authentication` and
:term:`authorization`.  In this section we'll focus solely on the
authentication APIs to add login/logout functionality to our wiki.

We will implement authentication with the following steps:

* Add an :term:`authentication policy` and a ``request.user`` computed
  property (``security.py``).
* Add routes for /login and /logout (``routes.py``).
* Add login and logout views (``views/auth.py``).
* Add a login template (``login.jinja2``).
* Add "Login" and "Logout" links to every page based on the user's
  authenticated state (``layout.jinja2``).
* Make the existing views verify user state (``views/default.py``).
* Redirect to /login when a user is denied access to any of the views
  that require permission, instead of a default "403 Forbidden" page
  (``views/auth.py``).

Authenticating requests
-----------------------

The core of :app:`Pyramid` authentication is a :term:`authentication policy`
which is used to identify authentication information from a ``request``,
as well as handling the low-level login/logout operations required to
track users across requests (via cookies or headers or whatever else you can
imagine).

Add the authentication policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a new file ``tutorial/security.py``:

.. literalinclude:: src/authentication/tutorial/security.py
   :linenos:
   :emphasize-lines: 9,14,28
   :language: python

Here we've defined:

* A new authentication policy named ``MyAuthenticationPolicy`` which is
  subclassed from pyramid's
  :class:`pyramid.authentication.AuthTktAuthenticationPolicy` which tracks
  the :term:`userid` using a signed cookie.
* A ``get_user`` function which can convert the ``unauthenticated_userid``
  from the policy into a ``User`` object from our database.
* Finally, the ``get_user`` is registered on the request as ``request.user``
  to be used throughout our application as the authenticated ``User`` object
  for the logged-in user.

The logic in this file is a little bit interesting and so we'll go into
detail about what's happening here:

First, the default authentication policies all provide a method named
``unauthenticated_userid`` which is responsible for the low-level parsing
of the information in the request (cookies, headers, etc). If a ``userid``
is found then it is returned from this method. This is named
``unauthenticated_userid`` because at the lowest level it knows the value of
the userid in the cookie but it doesn't know if it's actually a user in our
system (remember, anything the user sends to our app is untrusted).

Second, our application should only care about ``authenticated_userid`` and
``request.user`` which have gone through our application-specific process of
validating that the user is logged-in.

In order to provide an ``authenticated_userid`` we need a verification step.
That can happen anywhere, so we've elected to do it inside of the cached
``request.user`` computed property. This is a convenience that makes
``request.user`` the source of truth in our system. It is either ``None`` or
a ``User`` object from our database. This is why the ``get_user`` function
uses the ``unauthenticated_userid`` to check the database

Configure the app
~~~~~~~~~~~~~~~~~

Since we've added a new ``tutorial/security.py`` module we need to include it.

Open the file ``tutorial/__init__.py`` and edit the following lines:

.. literalinclude:: src/authentication/tutorial/__init__.py
   :linenos:
   :emphasize-lines: 11
   :language: python

Our authentication policy is expecting a new setting, ``auth.secret``. Open
the file ``development.ini`` and add the highlighted line below:

.. literalinclude:: src/authentication/development.ini
   :lines: 18-20
   :emphasize-lines: 3
   :lineno-match:
   :language: ini

Finally best-practices tell us to use a different secret for production so
open ``production.ini`` and add a different secret:

.. literalinclude:: src/authentication/production.ini
   :lines: 15-17
   :emphasize-lines: 3
   :lineno-match:
   :language: ini

Add permission checks
~~~~~~~~~~~~~~~~~~~~~

:app:`Pyramid` has full support for declarative authorization which we'll
cover in the next chapter. However many people looking to get their feet
wet are just interested in authentication with some basic form of
home-grown authorization. We'll show below how to accomplish the simple
security goals of our wiki now that we can track the logged-in state of users.

Remember our goals:

* Allow only ``editor`` and ``basic`` logged-in users to create new pages.
* Only allow ``editor`` users and the page creator (possibly a ``basic`` user)
  to edit pages.

Open the file ``tutorial/views/default.py`` and fix the following imports:

.. literalinclude:: src/authentication/tutorial/views/default.py
   :lines: 5-13
   :lineno-match:
   :emphasize-lines: 2,9
   :language: python

Only the highlighted lines need to be changed.

Now edit the ``add_page`` view function:

.. literalinclude:: src/authentication/tutorial/views/default.py
   :lines: 62-76
   :lineno-match:
   :emphasize-lines: 3-5,10
   :language: python

Only the highlighted lines need to be changed.

If the user is not logged in or is not in the ``basic`` or ``editor`` roles
then we raise ``HTTPForbidden`` which will return a "403 Forbidden" response
to the user. However we hook this later to redirect to the login page. Also,
now that we have ``request.user`` we no longer have to hard-code the creator
as the ``editor`` user so we can finally drop that hack.

Now edit the ``edit_page`` view function:

.. literalinclude:: src/authentication/tutorial/views/default.py
   :lines: 45-60
   :lineno-match:
   :emphasize-lines: 5-7
   :language: python

Only the highlighted lines need to be changed.

If the user is not logged in or the user is not the page's creator **and**
not an ``editor`` then we raise ``HTTPForbidden``.

These simple checks should protect our views.

Login, logout
-------------

Now that we've got the ability to detect logged-in users, we need to
add the /login and /logout views so that they can actually login!

Add routes for /login and /logout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Go back to ``tutorial/routes.py`` and add these two routes as highlighted:

.. literalinclude:: src/authentication/tutorial/routes.py
   :lines: 3-6
   :lineno-match:
   :emphasize-lines: 2-3
   :language: python

.. note:: The preceding lines must be added *before* the following
   ``view_page`` route definition:

   .. literalinclude:: src/authentication/tutorial/routes.py
      :lines: 6
      :language: python

   This is because ``view_page``'s route definition uses a catch-all
   "replacement marker" ``/{pagename}`` (see :ref:`route_pattern_syntax`)
   which will catch any route that was not already caught by any route
   registered before it. Hence, for ``login`` and ``logout`` views to
   have the opportunity of being matched (or "caught"), they must be above
   ``/{pagename}``.

Add login, logout and forbidden views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a new file ``tutorial/views/auth.py`` where we will add the following
code:

.. literalinclude:: src/authentication/tutorial/views/auth.py
   :linenos:
   :language: python

This code adds 3 new views to application:

- The ``login`` view renders a login form and processes the post from the
  login form, checking credentials against our ``users`` table in the database.

  The check is done by first finding a ``User`` record in the database and
  then using our ``user.check_password`` method to compare the passwords.

  If the credentials are valid then we use our authentication policy to
  store the user's id in the response using :meth:`pyramid.security.remember`.

  Finally, the user is redirected back to the page they were trying to access
  (``next``) or the front page as a fallback. This parameter is used by
  our forbidden view as explained below to finish the login workflow.

- The ``logout`` view handles requests to /logout by clearing the credentials
  using :meth:`pyramid.security.forget` and then redirecting them to the front
  page.

- The ``forbidden_view`` is registered using the
  :class:`pyramid.view.forbidden_view_config` decorator. This is a special
  :term:`exception view` which is invoked when a
  :class:`pyramid.httpexceptions.HTTPForbidden` exception is raised.

  This view will handle a forbidden error by redirecting the user to /login.
  As a convenience it also sets the ``next=`` query string to the current url
  (the one that is forbidding access). This way if the user successfully logs
  in they will be sent back to the page they had been trying to access.

Add the ``login.jinja2`` template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create ``tutorial/templates/login.jinja2`` with the following content:

.. literalinclude:: src/authentication/tutorial/templates/login.jinja2
   :language: html

The above template is referenced in the login view that we just added in
``tutorial/views/auth.py``.

Add a "Login" and "Logout" links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open ``tutorial/templates/layout.jinja2`` and add the following code as
indicated by the highlighted lines.

.. literalinclude:: src/authentication/tutorial/templates/layout.jinja2
   :lines: 35-46
   :lineno-match:
   :emphasize-lines: 2-10
   :language: html

The ``request.user`` will be ``None`` if the user is not authenticated, or a
``tutorial.models.User`` object if the user is authenticated. This
check will make the logout link active only when the user is logged in and
vice versa the login link is only active when the user is logged out.

Viewing the application in a browser
------------------------------------

We can finally examine our application in a browser (See
:ref:`wiki2-start-the-application`).  Launch a browser and visit each of the
following URLs, checking that the result is as expected:

- http://localhost:6543/ invokes the ``view_wiki`` view.  This always
  redirects to the ``view_page`` view of the ``FrontPage`` page object.  It
  is executable by any user.

- http://localhost:6543/FrontPage invokes the ``view_page`` view of the
  ``FrontPage`` page object. There is a "Login" link in the upper right corner.

- http://localhost:6543/FrontPage/edit_page invokes the edit view for the
  FrontPage object.  It is executable by only the ``editor`` user.  If a
  different user (or the anonymous user) invokes it, a login form will be
  displayed.  Supplying the credentials with the username ``editor``, password
  ``editor`` will display the edit page form.

- http://localhost:6543/add_page/SomePageName invokes the add view for a page.
  It is executable by the ``editor`` or ``basic`` user.  If a different user
  (or the anonymous user) invokes it, a login form will be displayed. Supplying
  the credentials with the username ``basic``, password ``basic`` will display
  the edit page form.

- http://localhost:6543/SomePageName/edit_page is editable by the ``basic``
  if the page was created by that user in the previous step. If, instead, the
  page was created by ``editor`` then the login page should be shown for the
  ``basic`` user.

- After logging in (as a result of hitting an edit or add page and submitting
  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.